This is the mail archive of the
davenport@berkshire.net
mailing list for the Davenport project.
Re: DAVENPORT: DocBook for documenting Python code
> | Whose top 10?
>
> Yours, of course. But seriously, C/C++, Java, Perl, and Python
> (in alphabetical order ;-) would cover a lot more of the world
> than what we've got right now.
Sure. From my (scientist's) point of view, Fortran should also be
taken into account, if only for books on the history of computing ;-)
> Yep. BTW, could you send me some examples of "complex"
> funcsynopses in Python and how a Python programmer would like
> them to appear? (I might help you out with the markup and
> stylesheet bits in DocBook, even if you don't use DocBook in the
> end ;-)
Here's an example that contains every possible feature:
function(a, b, c=None, d=[{2, 3}, 'abc'], *optional_arguments,
**keyword_arguments)
And that's how it should appear in print, possibly using different
fonts for various parts. No semicolon at the end!
But already proper markup is difficult with the current DocBook:
> Given something like this:
>
> def compile_dir(dir, maxlevels=10, ddir=None)
>
> This markup:
>
> <funcsynopsis>
> <funcprototype>
> <funcdef><function>compile_dir</function></funcdef>
> <paramdef><parameter>dir</parameter></paramdef>
> <paramdef><parameter>maxlevels</parameter>=10</paramdef>
> <paramdef><parameter>ddir</parameter>=None</paramdef>
> </funcprototype>
> </funcsynopsis>
>
> seems to do a pretty good job. I'd think with a Role attribute
> to control a few bits of punctuation, it'd be quite suitable
> (and very little work). Are there other, more difficult, cases
> that I've overlooked?
It would be nice to have markup for the default values. Using
<literal> would already be sufficient, but that's not allowed
inside <paramdef>. Another not-so-straightforward case is a
function without parameters. In Python you just write nothing,
i.e. "function()". But DocBook forces me to write <void>.
Which is acceptable if <void> gets translated into nothing,
but it remains weird to a Python programmer.
> | 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;
>
> No it's not. Not really. If all your worried about is processing
> a few documents that you have control over, there's no
> significant difference at all. I mean, you weren't really
You are right, as long as I limit myself to my own subset of SGML,
XML doesn't change anything.
> The devil, as they say, is in the details. It strikes me that option
> 1 is a lot less work, really. But I already know DocBook and I've
> never found typing the markup all that problematic, so I'm biased.
I found that in many cases the markup is much longer than the
actual text!
> That said, it's a lot of fun to build things yourself (I've
> reinvented more than one wheel just for that reason).
Me too! And I found that octogons are actually pretty good
approximations to circles ;-)
> Nope. I don't agree. An author's job is to write the words. The
> production folks, they may have some worries, but not the
> author. Of course, if you wear both hats... :-/
It's worse: I am program author, document author, publisher, user
support, and user!
Konrad.
--
-------------------------------------------------------------------------------
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
-------------------------------------------------------------------------------