David Bannon <dban...@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 _______________________________________________ This message is sent to you from FOSS-GPS@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