man vs info vs texinfo files

Per Bothner per at bothner.com
Thu Mar 5 23:37:35 UTC 2009


I remember (but now can't find it) somebody commenting on the man file
vs info documentation issue: that they disliked info because it doesn't
reformat properly depending on window size.

Fedora (and GNU systems in general) should stop shipping info files,
and should instead ship the texinfo source files.  The makeinfo
program will convert texinfo files into html or docbook, as well
as old-fashioned info.  Html or docbook is much nicer - you can
use non-monospace fonts (for the body), and the text can be
re-flowed to fit the window.  Also, indexes and cross-references
can take you to a precise location, rather than just a node.

An example of what you can do with texinfo:  The Kawa home
page at http://www.gnu.org/software/kawa/ is basically the
Kawa texinfo manual, formatted to docbook using makeinfo,
then formatted to HTML using the docbook-xslt stylesheets,
with some extra shell-script hacking.

The info format is a obsolete legacy format designed for plain
terminals.  However, texinfo is a decent format - more compact
and readable than (say) docbook.  Texinfo is still actively
maintained, with new features being added occasionally.

Info format should only be used for legacy programs that can
only read info format: The standalone info program, and the
emacs info mode.  In both case, the info files should be
generated on-the-fly as needed (and cached).

The user interface of the stand-alone info reader isn't
bad - but better would be the info program's user interface
(most importantly key-bindings) on top of a text-mode HTML
browser such as lynx.  In that case even the info program
wouldn't use info files.

If so, instead of shipping texinfo, we might ship
pre-formatted XHTML.  (Emacs info mode would need to be
able to handle such XHTML files, though.)

I doubt there is any important info documentation for which
we can't get the texinfo source, so making this switch
wouldn't lose any information.
-- 
	--Per Bothner
per at bothner.com   http://per.bothner.com/




More information about the fedora-test-list mailing list