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

[Joshua Judson Rosen]

David Bannon <dbannon at internode.on.net> writes:
>
> how *do* users know where to find the PDF/whatever manual that's
> stashed off in /usr/share/doc/...? Where do users *expect* to find
> documentation?
>
> > Maybe the answer is simply: `in the Help menu!'?
>
> Yep, that would be cool. But what would you pop up if a user so
> requests ?

Well, that's a good question--contentwise, either the HTML or the PDF;
then there's the `what do you call to display it?' question.
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.

My Debian system here says the mailcap utils are `standard'...;
do they actually exist everywhere--on other systems?

> > Well, `if I had my druthers'..., I'd be inclined to just go with texinfo
>
> I can live with it as long as the end user has alternatives to 'info' !
> HTML, PDF would be fine.

OK.

> > I'm generally skeptical of `lightweight markup' languages like
> > asciidoc, [...], so I always feel like I'm fighting to get them stop
> > guessing at `What I Mean' and just let me tell them.
>
> So speaks the C programmer ! (I agree by the way)
>
> > ... so that we can just have `make dist' generate docs--and figure
> > out what people actually need to install in order to work with it?
>
> Well, that depends on what we want. Sounds like we agree we can do
> without a comprehensive man page.

Right--I already have help2man generating a man page:

    http://bazaar.launchpad.net/~rozzin/foxtrotgps/texinfo/revision/219

(needed a little sed magic to compensate for GLib/GOption not
 producing quite the same syntax as help2man is expecting...)

> So how do we expect users to read our help pages ? Live on the web,
> easy.

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 :)

> Local set of html pages in /usr/share/doc ? And the same set of
> files as on foxtrotsgps web site ? Why not ?
>
> Is a pdf is easier to distribute being a single file ?
>
> It really has no other advantage IMHO.

I don't know....

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

Looking at what other people do, though..., according to what I have
installed on my laptop (noting that this is a new computer and still has
relatively little software installed on it...):

    find /usr/share/doc -name '*.html' \
    | sed -re 's:(doc/[^/]*)/.*:\1:' \
    | sort --unique | wc --lines

    => 101 packages

    find /usr/share/doc -name '*.pdf*' \
    | sed -re 's:(doc/[^/]*)/.*:\1:' \
    | sort --unique | wc --lines

    => 19 packages

    (and 7 of those 19 are TeX)


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

I still don't know what those packages are distributing in their
upstream source tarballs. I'm not really as nervous about the idea of
distributing images in release tarballs as I am about tracking them in
the main VC repository; my fear here is that version-controlling the
images in the main repository `worked a lot better' in the svn or CVS
days (the centralised VC systems made a lot of things a lot worse, but
they did free people from having to download sections of the repository
they didn't care about); I've had the `what do you mean I need to
download 200 MB of screenshot-history before I can hack on 100 kB of
code' experience before....

A lot of the GNU packages offer documentation in all forms for dowload
from their web-sites; 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.
For a document with lots of embedded images, a PDF definitely
makes that easier. Especially if people want to print them out'.

If I had to choose between PDF and HTML, I'd pick HTML because
it integrates better into the web-site; but it's really nice to
have both ;)

`make clean' really wants to delete the PDF, HTML, and whatever other
output..., but we can override that if we want (I don't think we want
`make clean', or even `make distclean', to remove things that the
user isn't normally expected to rebuild--or even be able to rebuild?).

> > texinfo source is actually mostly just plaintext, with a
> > little (easy-to-understand--I think...) markup where necessary,
> > and converts to all of the outputs that we want.
>
> Ah, thats important ! I was not at all happy with the PDF asciidoc
> generated. asscidoc's source is quite useful human readable text as is.
> Cannot say that about texi.

Agreed.

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