[FOSS-GPS] FoxtrotGPS: building documentation (was: FoxtrotGPS documentation (format? license?))

Joshua Judson Rosen rozzin at geekspace.com
Wed Dec 12 16:06:39 PST 2012

David Bannon <dbannon at internode.on.net> writes:
> > Right--I already have help2man generating a man page:
> You might be better generating it and leaving there as a static file.
> Generating the .1 file adds a dependency on help2man for people building
> from source. I expect foxtrotgps.1 need not change ?

The "dist_" prefix on "dist_man_MANS = foxtrotgps.1" makes `make dist'
do that for the tarballs; and "dist_doc_DATA = foxtrotgps.pdf"
does the same for the PDF. We can do the same for the HTML
by adding foxtrotgps.html and the images to dist_doc_DATA.

> > If we distribute the PDF in the source tarballs, we might be able to
> > rationalise not distributing all of the broken-out screenshots there,
> > and instead just saying `you need screenshots if you want to rebuild
> > the docs and canonical screenshots are available from <whatever URL>',
> > which in turn might make it a little easier to rationalise not carrying
> > all of the screenshots around in the main bzr repository....
> There is not a lot of space saving, PNG files inside a PDF keep much of
> their size. But a PDF does cut down on number of files. And there is,
> perhaps, little point in making someone building from source build the
> documentation unless they want to.

I think I mentioned in one of the previous e-mails: I don't
so much have an issue with just including everything (pre-built PDFs,
pre-built HTML docs w/ images, and texinfo source) in the tarballs--
I'd be OK with adding another MB to the tarballs and then re-evaluating
the decision if anyone complains; I just worry about the main VC
repository getting crufted-up from tracking this stuff *there*.

I think we don't have to track the HTML or PDF output in bzr
(if you want a build of the work-in-progress docs straight out of bzr,
`makeinfo' is already available pretty-much everywhere--and
the build-requirements for makeinfo itself are pretty light if
for some reason you don't already have a package available).
And, if you're getting stuff from bzr, it seems like you're probably
most interested in source-material rather than prebuilt docs,
anway--especially if pre-built docs are themselves available
for download from the website. But, given that we don't have a way
of automatically producing screenshots, *they* do need to be
captured somewhere ;)

It could be a separate bzr repository. One thought is that,
even with the screenshots in a separate repository,
we can make it easy to get them with a make-target like this:

    screenshots_upstream = lp:foxtrotgps-screenshots
    screenshots_revspec = last:1

            bzr checkout --lightweight $(screenshots_upsptream) \

I'll put together a couple of bzr branches that can actually build
docs one way or the other, and we can compare them.

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

More information about the FOSS-GPS mailing list