[FOSS-GPS] FoxtrotGPS documentation (format?)

David dbannon at internode.on.net
Mon Nov 12 14:29:25 PST 2012


OK Joshua, sounds like the only problems we have left then are format and license, the easy ones (I don't think) !

Seriously, I love my man pages, for command line tools, the only way to go. However, people using GUI apps rarely look for a man page, I bet most FoxtrotGPS users don't know it exists. And GUI users want embedded pictures, nice formatting. So what are the alternatives ?

Docbook, LaTeX etc has, IMHO, too high a learning curve for a project like this.

HTML ? Impossible to maintain.

MS Word -> [PDF; HTML] Please, please  don't even think that way.

AsciiDoc has some noticeable flaws, don't think if it as a one source many formats unless you are willing to compromise the appearance of the outputs. On the other hand, its text 'source' is quite easily human readable, quite presentable. It makes reasonable HTML very easily and the PDF's it makes, with one exception are also good.

Importantly, a decision to go with AsciiDoc is not irreversible, it would be easy to convert whats there to just about any other format if necessary.  

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.

License ?  I'd go along with what ever the developers decide but my preference would be CC or, maybe just because its easy, GPL. Clearly, I want no ownership.

http://www.users.on.net/~dbannon/FoxDoc/foxtrotgps.html

David

Joshua Judson Rosen <rozzin at geekspace.com> wrote:

>Charles Curley <charlescurley at charlescurley.com> writes:
>>
>> On Sat, 10 Nov 2012 12:21:22 +1100
>> David Bannon <dbannon at internode.on.net> wrote:
>>
>> > http://www.users.on.net/~dbannon/FoxDoc/foxtrotgps.html
>>
>> I think it's useful. I had no idea the keyboard shortcuts were there!
>> There's a lot of work to complete it, but this is an excellent start.
>
>The listing of keyboard shortcuts is from the manpage update last week;
>I think the question isn't really about whether to document things,
>or even about what to document, but really of what `source format'
>should be used for documentation.
>
>Right now our source-format for documention is troff (with `mandoc'
>macros). It's great for formatting, which makes it great for printing
>and OK for reading with a `man page' reader (e.g.: man, info, tkman, yelp)
>but it has a little bit of a learning curve and is (I find) somewhat hard
>to read. Apparently other people also find it hard to read ;)
>
>Also, I guess there also is (or should be) a question of what license to use
>for the documentation--because it should be easy for people to `repurpose'
>it into useful formats that may not have been thought of yet. Right now,
>there's no license declared specifically for the documentation;
>if we leave it like that, then we're probaby implying that it's
>GPL'd along with the rest of the codebase, and then technically people
>are supposed to distributed annotated source whenever they publish it...,
>which might put people off from, say, making `FoxtrotGPS quick-reference',
>mugs or T-shirts (it could happen!).
>
>Daniel Baumann wrote the initial version of the man page and generously
>offered to basically let us distribute it under whatever license terms
>we wanted, and all of the other content added so far to that man page
>(which, granted, isn't that much!) has been written by me, so it's
>not too late to actually *pick a license for the documentation*.
>
>I don't know what the popular free license for documentation is,
>these days--seems like GFDL never really cought on; Creative Commons
>BY-SA (Attribution Share-Alike), maybe? Or 3-clause BSD?
>
>-- 
>"Don't be afraid to ask (λf.((λx.xx) (λr.f(rr))))."
>_______________________________________________
>This message is sent to you from FOSS-GPS at lists.osgeo.org mailing list.
>Visit http://lists.osgeo.org/mailman/listinfo/foss-gps to manage your subscription
>For more information, check http://wiki.osgeo.org/wiki/FOSS-GPS


More information about the FOSS-GPS mailing list