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

[Joshua Judson Rosen]

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

    screenshots:
            bzr checkout --lightweight $(screenshots_upsptream) \
                         --revision=$(screenshots_revspec)


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))))."