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."