[FOSS-GPS] FoxtrotGPS: now with HTML/PDF/texinfo docs (was: building documentation)

[Joshua Judson Rosen]

David Bannon <dbannon at internode.on.net> writes:
>
> On Wed, 2012-12-12 at 19:06 -0500, Joshua Judson Rosen wrote:
> > ......
> > I'll put together a couple of bzr branches that can actually build
> > docs one way or the other, and we can compare them.
>
> Joshua, I note this is still pending.
[...]

Mm--I blame the myriad holiday distractions....

Good news, though--I did finally emerge from the holidays and find some
time to pull everything together:

I just pushed up the texinfo changeover, including your additions
and Til's, into the foxtrotgps-dev branch in bzr; and I also put
the manual in HTML format up on the website (there's also a PDF
up there in the same directory as the HTML manual, I just haven't
found a place to put a link to it...). I took a few minor
liberties before committing: fixed typos, normalised punctuation
(e.g.: "eg" -> "e.g.") and screenshot file-names, added more hyperlinks,
broke the "menu of common operations, allowing such things as..."
paragraph out into a bulletted list (following advice from a local
proofreader), used the same `main window' screenshot as is already
on the website....

For the time being, I've collected all of the screenshots into
a branch on Launchpad, and added a Makefile rule that fetches them
on demand. If you invoke any of the `make dist' targets, all of
the screenshots will get bundled into the resulting tarball/directory
along with the full manual in HTML format and the `shim' man page,
and those are installed by `make install'.

The PDF version of the manual builds with "make -C doc pdf"
(and PostScript and DVI outputs can be generated similarly),
but it doesn't happen by default (I think you were right
that HTML is probably a better default format than PDF).
"make -C doc foxtrotgps.txt" also works, but also doesn't
happen by default (should it?).

I've run through a few tests to verify, and I believe that building
from tarballs output by `make dist' will not require help2man,
makeinfo, or any of the other Texinfo utilties out of the box.
The tarballs are *much* larger that they have been up to now,
though (~2 MB compressed with gzip, ~1.7 MB compressed with xz,
which is ~4x the size of the 1.1.1 release tarballs!).

Oh--I also turned Automake's `maintainer-mode' on *by default*.
Tracking the version.texi in bzr actually turned out to be
a little problematic, because it ends up getting updated
every time someone runs ./autogen.sh or otherwise needs
to generate the "configure" script from configure.in; just
turning maintainer-mode on by default solves that problem
handily, but also seems like a good idea in general (see
the comments on commit #224).

-- 
"Don't be afraid to ask (λf.((λx.xx) (λr.f(rr))))."