This is the mail archive of the davenport@berkshire.net mailing list for the Davenport project.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]

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
-------------------------------------------------------------------------------


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]