This is the mail archive of the
davenport@berkshire.net
mailing list for the Davenport project.
Re: DAVENPORT: DocBook for documenting Python code
Norman Walsh <ndw@nwalsh.com> wrote:
> Well, I'd be happy to help write a customization layer for the
> stylesheets that did Python instead. Most of the examples I have
> are in C or a C-like language, so that's what I coded up.
But is the stylesheet the right place to put such information? It
would have to cover hundreds of programming languages to be general.
And I might invent my own next week, published together with a manual
written in DocBook. I'd much prefer a DTD/stylesheet combination
that lets me take care of specific syntax myself.
> In an effort to improve the accuracy of document interchange,
> DocBook has some explicit processing expectations. As you've
> noted, these are rather C-like.
I have nothing against specific "safe" features for popular languages,
but there should be some general fallback for others.
> No, you didn't overlook anything. Adding support for "modern"
> programming languages is a high priority issue. I recently
> posted a proposal, but haven't seen any replies (did anyone
> receive it?). I can repost it, if there's interest.
I am definitely interested. But this raises another point: I must
write my manuals now, not when some great new DocBook version comes
out. Is there some general mechanism to deal with information for
which no specialized markup exists? My priorities would be
1) Decent results with current DocBook processors (i.e. stylesheets).
2) Easy conversion to better markup when available.
At the moment I just use <literal> with various role attributes for
everything Python-related, which seems to work well. But it isn't
nearly as detailed as the existing markup for C code, so if in the
future there will be better ways to do it, I'd have to make manual
changes, which is unlikely to happen.
Another approach would be to invent my own markup and have it
machine-translated to current DocBook. But then I might just as well
forget about DocBook and create my own DTD!
--
-------------------------------------------------------------------------------
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
-------------------------------------------------------------------------------