Re: documentation: DocBook vs. TeXinfo

[Mark Galassi <rosalia cygnus com>]

    Bigelow> [I was told that GNOME uses DocBook, GNU uses TeXinfo;
    Bigelow> what's up?  What should we use?]

That's an interesting story; here's my explanation of where things are 
in the GNU documentation world:

DocBook and TeXinfo are both nicely structured systems, with rich
content-based markup tags; thus they are both good source formats for
computer documentation.

DocBook is more structured and richer, and thus better for longevity
as well as indexing, searching and electronic presentation of
documents.  It is also more strict (probably a good thing), and its
SGML heritage adds more power.

TeXinfo is nice, and in my opinion it is the next-best choice after
DocBook.  Most other formats (LaTeX, LinuxDoc, RTF, MIF) don't cut it
at all because their markup is not based on the *content* of what's
being marked up.

DocBook has a couple of drawbacks:

1. The set of free tools is not yet mature enough, really.  What we
   still need are (a) for jadetex to grow up (apparently it's
   happening) (b) for Ulrich Drepper to write converters between
   DocBook and TeXinfo (it's on his TODO list, but he's busy with
   other stuff right now).  Item (b) will allow us to present info
   documents as well as plain text.

2. The set of tags is *very* big and hard for a beginner.  On my list
   of things to do is to define a "minimal acceptable set of tags that 
   a lazy writer should use", and this list would define a subset of
   DocBook which is basically equivalent to TeXinfo :-)

At Cygnus we felt that the drawbacks would be overcome soon enough
(and we are collaborating to fix most of the problems), so we decided
to plunge into DocBook.

When GNOME started up, I proposed DocBook as a format for
documentation, and people bought in to it because it seemed cool.
Then people started actually writing docs, and they fell back on what
they were comfortable with (LinuxDoc and HTML mostly), so I decided I
should actually *do* something for GNOME that was more than just
proposing stuff, so I translated their docs into DocBook.  Now many
people are actually writing in DocBook themselves.

Meanwhile the Linux documentation people have started migrating from
LinuxDoc to DocBook, which is cool.

The last hurdle is to get traditional GNU projects to adopt DocBook,
and I think the way to do that is to get the correspondence between
TeXinfo and DocBook implemented and smooth.