[Doc-SIG] Docbook output

[Lennon Day-Reynolds]

I've been lurking here for quite a while, but thought I would weigh in 
quickly on the issue of DocBook output, since I spent a good portion of 
the last year working with about a dozen developers creating a 
DocBook-based documentation system for a research programming and 
specification language. We experimented with "custom" markup syntaxes, 
automatic DocBook generation from source code, etc., and the experience 
was not as pleasant or fruitful as I had initially hoped.

Basically, DocBook is the 400-lb. gorilla of markup formats. Most of our 
developers never used more than a 12-25 of the several hundred available 
element types, simply because there were too many to remember the proper 
nesting and attribute declaration policies for. The semantic richness of 
fully "DocBook-ized" documentation is impressive, but the time involved 
in actually placing more than basic structural and keyword markup around 
the text proved prohibitive in most cases.

WRT to the choice of top-level element ('book', 'chapter', 'article', 
et. al.), I would have to recommend starting with the Simplified DTD, 
unless you're going to allow some sort of inline directive in the source 
to make the chapter, section, and appendix blocks explicit. Of course, 
you could just create one "default" template which included a "global" 
foreword, and then had chapters assigned to each source file in the 
original document, but it seems like an awful lot of work just for 
something that's usually intended to be an precursor format for HTML, 
PDF, or LaTeX final output.

If you're seriously committed to DocBook output, though, might it not be 
easier to simply use an XSLT stylesheet to convert the DocUtils "native" 
XML format (basically just a dump of the internal document node 
structure, IIRC) into DocBook, rather than a seperate Python 
implementation? I'm a die-hard Python user, as well, but XSLT really is 
a great tool for this kind of deep tree walking and transformation task, 
esp. when your input and output are already both going to be XML 
documents.

One specific "gotcha" to keep an eye out for: DocBook tables are 
painful, compared to HTML. Web browsers, and even other document 
publishing tools, are pretty good about making a "best guess" attempt at 
laying out simple tables according to their contents, with little or no 
explicit size information from the author, but most of the DocBook 
rendering tools I've used tend to mangle any table that doesn't include 
explicit column widths.

In short, personally, I don't see any real use to DocBook output if HTML 
and PDF are already available with any degree of customizable 
formatting. Of course, that doesn't exclude the possibility that you 
might really want/need DocBook and XMLspec.

So, now that I've done my soapboxing for the day, it's time for some 
breakfast. Good luck, either way.

Lennon Day-Reynolds

P.S.: To everyone who's contributed to the Doc-SIG, reST, etc., I say, 
"Good work!" Things are starting to look really good, guys and gals.


On Saturday, June 15, 2002, at 09:56 PM, Dethe Elza wrote:

> OK, thanks for the feedback.
>
> For reference, Simplified Docbook (current draft) is at:
> http://www.oasis-open.org/docbook/xml/simple/1.0CR1/index.shtml
> The DTD is specifically aimed at documents with root <Article>.
>
> And the XMLspec info is at:
> http://www.w3.org/XML/1998/06/xmlspec-report-v21.htm
>
> I've done a bit more of my homework and read through the HTML writer, 
> which looks clear enough.  Sometimes I forget how easy it is to read 
> the source in Python.  Of course, it helps when the project is 
> well-organized.  Kudos to you.
>
> I've also joined the mailing lists, will load from CVS later.
>
> Thanks and I hope to be of some help.
>
> --Dethe
>
> --
> "Melting down holy grails to make silver bullets for my .357 Panacea"
> Dethe Elza (delza@burningtiger.com)
> Chief Mad Scientist
> Enfolding Systems (http://enfoldingsystems.com)
> Weblog: http://livingcode.ca/
>
>
>
> _______________________________________________
> Doc-SIG maillist  -  Doc-SIG@python.org
> http://mail.python.org/mailman/listinfo/doc-sig
>
>
Lennon Day-Reynolds
mail: lennon@day-reynolds.com
www: http://day-reynolds.com/lennon/