[Gllug] Interactive Documentation.

[Mike Brodbelt]

Richard Jones wrote:

> If you want to generate a manual, *and* all of the potential editors
> are clueful, then you'd be hard pressed to beat DocBook/XML as a
> format, with a standard version control system and simple text editors
> to edit (I recommend Aquamacs on Mac OS X - a fantastic version of
> Emacs for editing XML docs).

Hmmm - I've had decidedly negative experiences with DocBook. Maybe its
better now, but last time I tried you could either use SGML, or XML. The
SGML toolchain worked, and the XML one didn't (mostly). The whole
toolchain was far too fragile in my experience, and emitted obscure
errors even with trivial documents. The DocBook DTD also seems to be
something of a moving target. I'm a vi user, and editing XML in vi is
painful - it's far too verbose, and simple things like commenting
sections out are unwieldy. Emacs may be better here, but when you get
round to saying one should change editor to fit the format, then I think
the format is the problem, not the editor.

These days I use Latex for almost all significant work. It's pleasant to
edit, the toolchain is mature and doesn't break, and with pdflatex and
the hyperref package it's trivial to produce professional looking PDF
output. I find OpenOffice just as frustrating to use as Word for the
most part - WYSIWYG editors consistently try to do what they think the
user wants, and frequently get it wrong. Latex doesn't have this problem
- it does exactly what I tell it to, and leaves it up to me to sort out
any obvious problems in the output. This reduces my stress level no end.

Maybe DocBook is better now, but I remember much pain trying to get
simple PDF options out of OpenJade, DSSSL stylesheets, and other
oddness... With the output options from Latex, I can see no compelling
reason to try it again.

Mike
-- 
Gllug mailing list  -  Gllug at gllug.org.uk
http://lists.gllug.org.uk/mailman/listinfo/gllug