RE: DAVENPORT: DocBook for documenting Python code

["SIMMONDS, Scott" <SSIMMOND@baea.com.au>]

<opinion>
You need to keep in mind that DTD design is not an easy task, DocBook has
been carefully crafted over a number of years and the maintainers appear to
be receptive suggestions for improvements and changes which increase it's
utility. I don't disagree that detailed documentation on DocBook, ala The
TeX Book/LaTeX Book is lacking, although Norm promises his tome on the topic
will be published Real Soon Now. 

The introductory material by Messrs. Galassi and Clayton is sufficient to
get started and whilst generating/inserting markup is not painless, psgml
mode helps considerably.

Time invested up front in DocBook will be worth more that "rolling your own"
and looking to convert later, I offer the apparent anguish of the LDP
maintainers over the LinuxDoc -> DocBook conversion (both the mechanics and
the principle) as an example.
</opinion>

<advice attrib="free">
>>  - Extend DocBook with markup that supports Python really well.

Extend DocBook with markup that supports Object Oriented languages really
well, with attributes that allow variation based upon specific language
constructs, 
e.g. 
      <class lang="java" type="inner"> 
      <method lang="c++" type="public"> etc.

This may appear to be a lot of markup, but parsing text and munging it are
what languages like Python excel at.

>>  - Update the stylesheets to support your new markup
> Sounds reasonable. Except that I'd like to avoid messing around with
> stylesheets; at a first glance they seem to be at least as complex as
> the DTD itself!

<grin>
I don't disagree with that assessment, I'm sure there is global secret
society of Lisp afficionados who's goal is world domination and subjugation.
</grin>

Using the xml version of DocBook and writing Python to parse and generate
Latex/HTML (HTMLgen ?) may be an option worth consideration.
</advice>

<proposal>
Define an extension to DocBook to better support OO languages.

Create a customization layer for the DocBook stylesheets which support the
OO extension.
(Or xml/Python -> Latex/HTML)

Write Python code to automagically generate marked up code from OO language
of choice. (Inverse Literate Programming !)

>  - Submit your proposal for consideration in a future version of
>    DocBook.

Is there any interest on this list in supporting the development of such an
extension ?
</proposal>

Cheers,
Scott.
 --
 Scott Simmonds               
 British Aerospace Australia  
 Ph: 08 8290 7923             
 e-mail: ssimmond@baea.com.au