Re: DAVENPORT: DocBook for documenting Python code

[Rahul Dave <rahul@reno.cis.upenn.edu>]

You may want to take a look into sgmlspl which is a perl script from 
David Megginson which converts an older docbook DTD to latex/html. Its
very easily to modify(being perl).

There seems to be a misconception that Docbook has poor documentation.
There are resources by Nik Clayton at the Freebsd site, Mark Galassi (who
has nicely packaged and out of the box RPMS) and in the distribution itself.

Writing up in docbook may be tedious, but the real win is in searching. I mean,
if you tag <command>ifconfig</command> you can ask a question like: what
are all the commands that have to do with maintaining network interfaces.
with the advent of query languages like xml-ql, one can even combine queries
from different sources. If all thats desired is formatting, linuxdoc1.0 is
sufficient and is writable semi wysiwig using lyx.

One way to implement api markup maybe to use xml namespaces instead of 
adding more stuff to docbook, and thus increasing its complexity. 
But you'd be on your own in translating the markup.

Rahul
I got this from you:
> 
> > I have a feeling that writing a DTD/stylesheet combination that
> > was simultaneously completely general and useful would be a
> > <ahem/> significant challenge.
> 
> The DocBook project already looks as if it was a significant challenge
> as well ;-)
> 
> > But I'd like to come up with some markup that handles a lot of
> > the cases nicely, and I'm perfectly willing to update the
> > stylesheets so that the top 10 languages are supported with
> > maximal utility.
> 
> Whose top 10?
> 
> > If you invent something completely new markup, you're going to
> > have to invent a stylesheet for it, too.
> 
> The alternatives I am currently considering are:
> 
> 1) DocBook. That means first learning DocBook (not at all trivial,
>    without decent documentation). It also means typing enormous
>    amounts of markup, which is a rather tedious work even with the
>    support of PSGML mode in Emacs. Then I have to find out a way to
>    include something that was not taken into account (Python). Then I
>    have to modify the stylesheets accordingly, which means learning
>    DSSL as well (I don't know if any documentation is available). Then
>    I have to deal with Jade and live with the shortcomings of JadeTeX,
>    which at the moment doesn't produce decently formatted printed
>    documentation.
> 
> 2) A specialized XML DTD for my problem. I'd have to write the DTD
>    itself and some processor. But XML is much simpler than SGML;
>    I could build on the XML package in Python for parsing and write
>    my own Python code for generating HTML and LaTeX. Since I know
>    Python, HTML, and LaTeX very well, there is no need to learn
>    anything new, and I have full control over the result.
> 
> It is not at all obvious which of the two solutions is less work, but
> it is definitely easier to estimate the effort for the second than for
> the first one. The more I look at it, using DocBook seems most of all
> a big risk; it's a system I don't understand well enough to know if it
> can do what I need and with what effort.
> 
> This is not meant to be a criticism of the DocBook approach; of course
> I understand that a uniform and general format for documentation is
> something useful. But with the present tools and documentation, a
> manual author must worry too much about technical problems, instead of
> working on the real task, which is writing the manual.
> 
> > | I have nothing against specific "safe" features for popular languages,
> > | but there should be some general fallback for others.
> > 
> > What would you like to see in the general fallback that you don't
> > get from some combination of <literal>, <programlisting>, and
> > <synopsis>.
> 
> I would like to be able, for example, to extract a list of classes and
> functions (with parameter list) in my manual. And I would like to be
> able to define a particular formatting (font etc.) for such items.
> 
> > Well, if you at least share your experiences, there's a good
> > chance that better markup will be available the next time you
> > write about Python. ;-/
> 
> But by then I might need yet another syntax! :-(
> 
> > Or choose a middle ground:
> > 
> >  - Extend DocBook with markup that supports Python really well.
> >  - Update the stylesheets to support your new markup
> >  - Submit your proposal for consideration in a future version of
> >    DocBook.
> 
> 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!
> 
> I am currently inclined towards another middle ground: use my down
> DTD and processing software, but keeping the markup compatible
> with DocBook as far as possible. Then if one day DocBook processing
> tools become useable, I can drop my homegrown converters.
> -- 
> -------------------------------------------------------------------------------
> Konrad Hinsen                            | E-Mail: hinsen@cnrs-orleans.fr
> Centre de Biophysique Moleculaire (CNRS) | Tel.: +33-2.38.25.55.69
> Rue Charles Sadron                       | Fax:  +33-2.38.63.15.17
> 45071 Orleans Cedex 2                    | Deutsch/Esperanto/English/
> France                                   | Nederlands/Francais
> -------------------------------------------------------------------------------
>