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

[David Bannon]

On Mon, 2012-12-10 at 20:15 -0500, Joshua Judson Rosen wrote:

> I think I'd try just calling the `xdg-open' command if it exists,
> and then probably try falling back to the `run-mailcap' or `see' command
> if xdg-open doesn't work--so it'd use whatever PDF/HTML viewer/brower
> is appropriate on the user's system.

'see' is fine on my Ubuntu box but not available on a Centos box I still
have access to. But xdg-open does work there.



> 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 ?


> Except when they're using the program offline--there are a lot of places
> where GPS works but there's no Wi-Fi or even cell towers :)

You are telling me ?  I come from Australia !


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


> ... so it would seem that distributing docs in HTML (including
> the screenshots PNGs) would put us in good company.

yes, HTML seems to be pretty much seen as the normal way of doing it.
But it does not mean we have to do it that way.



> .... my fear here is that version-controlling the
> images in the main repository .....

I have to confess I am a lot more comfortable with CVS than today's way
of doing this stuff so its really your call.

But if we don't put the images and the HTML/PDF build recipes in the
main repo, we do need them somewhere, need some version control. We
could easily generate the Web content and the PDF and then push the PDF
into the main repo. Not probs.

> .....part of the rationale I see for that is that
> then people can just grab the docs and peruse them before they've
> figured out whether they're even really interested in the package.

I generally look for the project's on line HTML documentation before I
install something. I grumble if all I can find is a PDF because I need
download the whole thing and may well look at page one and see its not
what I want. But its not uncommon for projects to have Web content and a
single PDF, that way, we can cater to all tastes (at the expense of a
mild increase in disk usage on your web server).

> Especially if people want to print them out'.

Agreed, printing really requires a PDF. Lets hope not too much printing
happens these days, think of the trees !

>  but it's really nice to have both ;)

Yep. As long as there is not a disk space issue, we should do just that.


David