[FOSS-GPS] FoxtrotGPS documentation, textinfo or asciidoc ?

[David Bannon]

OK, Joshua, Tilmann, I have finally got around to having a play with
using textinfo, specifically for FoxtrotGPS documentation.

My impressions are overall positive, it's obviously more mature than
AsciiDoc but maybe a little less 'rich' in its potential output. Before
proceeding to discuss what I have found, I'd really like to get an
agreement on how we present this documentation.

I suggest we need to have html documentation on the FoxtrotGPS website
and replicate it in (eg) /usr/share/doc/foxtrotgps in a standard
install. I think thats what most users would want and expect. Add to
that a man page stub that says "look at
the /usr/share/doc/foxtrotgps/index.html or website".

Do we need a PDF, text and an info file in the distribution ?

A source build is another question altogether. Probably need them all.

OK, now, TextInfo and in particular, Joshua's BZR branch. First, I note
a couple of issues -

1. The branch does not include the images, perhaps as it adds about half
a meg of data!

2. Its missing version.texi, needs to define $VERSION and $UPDATED

3. The build does not make .html or .text but it appears its intended to
do so.

4. The Gnome yelp tool might well be able to display foxtrotgps.info but
I suggest its going to be hard work making it do so. It will add a
dependency on yelp. And not all Linux distros ship yelp !

There are a few annoying issues I have spotted, none of which are a deal
breaker in my humble opinion.

a) The placement of images seems crude, they appear as a paragraph of
their own generally or at best, with their base level with the next line
of text. So no text wrapping, no pretty bullets etc.

b) The html files appear a directory below the ~/doc directory and
therefor miss their images. Easily fixed but annoying when someone
builds from source but does not install. They cannot use the html as it
is. We'd fix it before shipping a binary install of course.

c) Makeinfo does not observe scaling of images when generating html,
means we get them the right size initially, a good idea anyway.

d) textinfo does break up the whole thing into a bit nicer set of
'chapter based' html files. Not important but nice. 

So, when it comes to choosing between asciidoc and textinfo, I don't
care. I can work with either. I think a more interesting question is
"what is distributed to the end user". I suspect Joshua wants the key
documentation media to be info. I'd rather see it html. 

But if we end up with html on the website and info on the user's
machine, I can live with that too.

Oh, and for the record, I am more than happy with CC-BY-SA 3.0

David


 



On Thu, 2012-11-29 at 09:07 +0100, Dr. Tilmann Bubeck wrote:
> David,
> Joshua,
> 
> the tool: well, you compare texinfo and asciidoc. At the end its a 
> personal taste, what tool to prefer. I think, they both have advantages 
> and disadvantages and are very similar.
> 
> AsciiDoc is a little more less "markup", than texinfo is. Therefore the 
> source is a little bit more readable. On the other hand, the tool chain 
> for texinfo is much more stable and robust and a well-proven path.
> 
> As Joshua is the main responsible person behind foxtrotgps I tend to let 
> him decide and he seems to prefer texinfo. That is absolutely fine to me.
> 
> So I propose to use texinfo.
> 
> The license stuff: You propose CC-BY-SA 3.0 which is fine for Fedora 
> (and probably most others). Fedora declares this as "good" on their 
> license page:
> 
> https://fedoraproject.org/wiki/Licensing:Main?rd=Licensing#Good_Licenses_2
> 
> This is also true for GNU FDL.
> 
> So I support Joshuas proposal: texinfo + CC-BY-SA 3.0
> 
> The most important part for me was to get a manual into foxtrotgps which 
> is more than manual page/readme. I am happy to see this being discussed 
> now and even more, being decided and done. I offer my help for whichever 
> system gets selected.
> 
> :-)
> 
> Kind regards,
>    Till
> 
> _______________________________________________
> 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