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

[David Bannon]

Hmm, I even installed makeinfo on my laptop ! And ran 'info', first time
in, maybe, 5 years. It has not got any better !

Anyway, what you say makes a lot of sense Joshua. Mostly. 


> 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 ? I guess you don't want it hard coded into the binary ? I'd
suggest HTML, everyone has a browser. 


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

> 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. So how do we expect users to read our
help pages ? Live on the web, easy. 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. 

A plain text file would also be nice, reminiscent of a man page !

We are not writing a book....

> 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.
Both handle making usable html and neither, IMHO, manage man pages.


> --if you can come up with an ASCII-art

ASCII-art ? Only good for finding out who has proportional text in their
email client !


> And, yes, it (also) produces info pages..., 

I knew it would come to that !

> --GNOME's `yelp' help-viewer tool can actually display them, 

Not for me as it turns out. Interesting, there are no other info files
on may laptop, that surprised me. Anyway, I installed makeinfo,
converted your file, but yelp would not read it. Sigh...


> And I believe KDE and other desktop environments have similar tools
> (like `kdehelp'?).

Don't know, stopped using KDE with V4.0. I guess we need to text against
each if we went that path.


> > So, I suggest that the FoxtrotGPS web page has HTML, the distribution
> > has the text source file, and, perhaps a PDF. A man page then needs to
> > say little more that see the other docs and maybe mention the much
> > lauded command line options and the two extra utilities.
> 
> Exactly :)
> 
> > License ? ... CC or, maybe just because its easy, GPL. 


>       Looking at <http://wiki.debian.org/DFSGLicenses>, it looks like
>       Debian accepts CC BY-SA 3.0 but rejects earlier versions--

I am sure we could ask them to make an exception for us (I don't think
so! :-)  ).

If the package maintainers are happy with CC BY-SA 3.0, thats easy, lets
do it. I have already agreed to CC BY-SA 2.0 for OSM, map and wiki and
don't want to read any more license agreements.

The change to CC BY-SA 2.0 just about ripped osm apart. Sigh....


>       I have no idea what Fedora's / Red Hat's policies are
>       (Til may, since I believe he's responsible for the
>        foxtrotgps package in Fedora).

Til ?

In summary, I think asciidoc has some limitations, it does not deliver
on seemless generation of different formats, if you want man pages, all
other formats look like man pages. The PDF leave out the graphic
bullets, as, as noted "everything between two "~" characters in
different file-paths is being subscripted(?)).

Til might have more experience with asciidoc than I do, he may be able
to put aside these issues ??

Maybe I'll have a play with texi. But I still won't look at it in info !

David