Re: Doc Tasks (was RE: docstrings in Guile!)

[Daniel Lundin <daniel at emacs dot org>]

"Greg J. Badros" <gjb@cs.washington.edu> writes:

> forcer <forcer@mindless.com> writes:
> 
> > "Greg J. Badros" <gjb@cs.washington.edu> writes:
> > 
> > I suggest you get yourself the current texinfo 4.0 and read it's
> > documentation. 
> 
> I'm glad TeXInfo might not be as awful as I thought, but I still remain
> steadfast in believing SGML/XML based markup is the way to go. Visit any 
> bookstore and compare the amount of interest in and work on XML/SGML
> vs. TeXInfo.

First of all hi everybody, I'm fairly new to the list and so far been
lurking in the corner. I thought I'd share my views on this
topic though since it falls closely to home as I've been choosing
between docbook and texinfo myself recently in a project at work.

Docbook is very thorough, that being both its pros and cons. There are
a lot of tags that obfuscate the source for documentation in a way that
is less than optimal for human reading. Editing is most conveniently
done in emacs using psgml mode, which does for docbook basically
fontlocking, tag handling/removal/hiding/completion, which is nice,
but there is no real support for maintaining the actual structure of
the material as in texinfo-mode. 

Using texinfo-mode one enjoys features like showing a document's
structure, handling references between nodes, and
verify/complete/create links and menus much easier than in
psgml-mode. 

From the writer's perspective texinfo is easier to use for
documenting source since it is largely self-checking (texinfo-mode),
it contains a lot less tags to juggle around, and it is very readable
in source form since the tags are a lot less obtrusive than when using
SGML-style closed-tags markup. When writing docbook one is often
busy choosing that right tag that gives the right look rather than
being able to concentrate on the content text itself.

Also, rendering a docbook source takes a lot of tools and requires
large software packages (jade, jadetex,dsssl,tex/latex ...) to build.
Texinfo requires less to build and is simpler for a user to make, using
makeinfo and friends. It also renders easier to more formats like plain text,
print, html, and info. Docbook/DSSSL, in practice, only delivers
print and html output. Texinfo produces great plaintext output (as seen
in info), especially the handling of images is neat - Just add three
files for each image: image.eps, image.png and image.txt - and
makeinfo will use the right one for the different output formats, so a
diagram or figure can have an ascii representation to be used for the
info/text version. Very useful.

I've looked into the docbook->texinfo conversion several times,
but yet not found a tool that does the job in a good manner. I suppose
the right thing would be to write DSSSL style sheets to produce texinfo
or even info output,  but that is yet to be done. Assuming the
conversion was working,  you would as was pointed out earlier in the
thread, loose certain amount of (unneeded?) markup in the process
which  would reduce the quality of the end result.

So personally I'd definitely stick to texinfo. It's smaller, takes
less time to learn and is easier to use, and it produces the output
formats desired for accessible documentation. It is also the standard
for GNU documentation.

Well, that was some rant. I hope it made any sense at all.

-- 
Daniel Lundin <daniel@emacs.org>