[Pipet Devel] Docbook online

[David Lapointe]

On Fri, 19 Nov 1999, hinsen at dirac.cnrs-orleans.fr wrote:

> I decided to use DocBook for the ScientificPython and MMTK manuals,
> and my enthusiasm about DocBook gradually disappeared over the time.
> First of all, DocBook is extremely complicated, and deciding which
> markup to use for what use is not easy. And it doesn't help that the
> various existing documentations sometimes contradict each other.
> On the other hand, in spite of the enormous number of markup tags,
> some very basic things were forgotten; there is no straightforward
> markup for citing journal articles, and the markup for library
> and code documentation covers only C.
>
It is very complicated and definitely NOT WYSIWYG.  The appearance of DocBook: TDG
( the book ) will help somewhat. O'Reilly publishes their books using Docbook and 
they have two books on Python full of Python code docs.

> Another problem is translating DocBook to something readable for
> normal people. Jade with the DSSSL stylesheets does a good job at HTML
> translation (but be prepared to have a fast machine with lots of
> memory if you plan to use Jade), but hardcopy output produced via Jade
> and JadeTeX looks terrible; it doesn't even respect basic typesetting
> rules such as not breaking a page after the first line of a paragraph.

Well, this is always a problem.  I think those rules have to be set up on a  
per case basis, that is ,  the basic rules are generic and you would build up from there 
to what you want.  The lists about sgml ( I was reading the sgmltools list ) are   full of 
these issues.

I like the idea of one document-> many output formats.  There is a lot of work involved, however.

-- 
 .david
 David Lapointe
"First things first," mandates sci-fi icon 
Doctor Who, "but not necessarily in that order."