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

[Joshua Judson Rosen]

David Bannon <dbannon at internode.on.net> writes:
>
> 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.

See responses, further down....

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

Yes--that sounds abut right to me.

> Do we need a PDF, text and an info file in the distribution ?
>
> A source build is another question altogether. Probably need them all.

We can distribute (and install) any/all of them pretty trivially.

The HTML+images adds about a half-MB of data, and the PDF adds another
half-MB, so what's currently a ~500-kB source tarball becomes either a
1-MB source tarball or a 1.5-MB source tarball (or thereabouts--
I haven't actually tried any of the `make dist' targets with images
and/or PDF included).

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

Yes....

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

Oh, right.... That's generated (and cleaned/re-generated) only if you
have maintainer-mode on; i.e. if you've configured with:

        ./configure --enable-maintainer-mode

I gather that the idea is for those strings to be updated *only*
when the maintainers know that they've made updates that are
specific to a newer revisions of the codebase, or when the changes
pass some threshold of `significance'....

I don't think I have a problem tracking version.texi in bzr.

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

I'm not sure I understand--there should definitely be "foxtrotgps.html"
and "foxtrotgps.txt" targets defined in the `doc/Makefile' file
that you get after running ./configure....

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

Oh, sorry--I actually didn't mean to suggest that we should just
use/require yelp; it was just a bit of an `alternatives to the
info command that you might prefer' digression. ;)

I can have a try at adding a `help'-menu or -button that opens
the documentation; at least as a first try, I'd just try invoking
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.

Users on small screens will probably appreciate loading the HTML
version rather than the PDF version--there's a better chance
that we the HTML will work on a 640x480 @ 7 cm screen, for example
(though I guess I'll have to try it and see!).

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

They can actually be used inline, similarly to HTML; it was
an explicit choice on my part to put them on their own lines
and center them.

I don't see a way to do CSS-style `floats' available via texinfo
(or in asciidoc, actually...), but the `pretty bullets' can be
accomplished by the same mechanism that asciidoc-generated HTML uses:
tables (note that texinfo calls them `multitables' [multi-row tables];
if you're familiar with HTML, what texinfo calls `tables' are roughly
equivalent to `definition lists' in HTML; or `labeled lists' in asciidoc).

In retrospect, I do think that I should have *bolded* the *items*
("Handheld GPS" and "GPS Mice") there--and possibly done without
the bullets....

I actually have a version of the foxtrotgps.texi that can recreate
your handheld/mouse `pretty bullets', and also places the map_download
image to the left of the text under `Pre Load or Refresh the Cached Maps'
heading, in all of the output formats except the plaintext ones
(and it does actually get laid-out correctly even in plaintext,
 just without the pictures), but...:

    * It's a more complicated (less obvious-looking), in source form;
    * I think I might actually prefer the simpler `definition list'
      form than the table-layout'd form; and...
    * I wanted to see how you guys reacted to seeing the two forms
      in comparison to each other.

One of the things that bothers me about the `pretty' version that
you got out of asciidoc is that the alignment between `bullets' is
screwy: the vertical divider-bars/sigils (and text) are misaligned
even between contiguous items. I gather is is due to the images
having different widths, which is fixable, but...:

Another thing is that it doesn't /look/ like asciidoc is really intended
to support either `pretty bullets' /or/ `floats' like you're doing,
either--the `delimited block' syntaxes all really seem to be for various
types of block-quoting (which explains why they change the font
and other text-characteristics inside the blocks...).

Asciidoc is actually just table-formatting them--with a separate
table for /each/ block....

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

Did you run "makeinfo --html" directly, or did you use
my "make foxtrotgps.html" target?

There are several options that can be passed to `makeinfo' to control
how the HTML is generated (e.g.: whether it's split separate files;
whether per-node headings with `next', `previous', and `up' links
are used; what CSS code to include); the argumentation I gave
in Makefile.am was intended to mirror the single-file style that you
produced with asciidoc. Now that you raise the issue, I realise that
I'm not sure whether you had done that intentionally or because that's
`just how asciidoc does it'; did asciidoc give you a choice?

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

I actually thought that was more of a feature than a bug....

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

And here I was thinking I was helping by making it not do that!

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

I'm game for HTML, actually; I suspect that most users will agree
with you, and they're really the audience for finished documentation
(as opposed to maintainers who, one might say, `know the program
 inside-out').


> 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

That's 3/3 of the people who have bothered commenting so far, then.


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

> 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