Re: DAVENPORT: DocBook for documenting Python code

[Norman Walsh <ndw@nwalsh.com>]

/ Konrad Hinsen <hinsen@cnrs-orleans.fr> was heard to say:
| > 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?

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.

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

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

| 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
thinking of using shortref, were you? ;-)

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

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.

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

I understand what you mean, but by analogy it sounds like you're
saying, "I need a 21 speed bike, and I know how to machine and
build my own bicycle from scratch and I can estimate how much
effort that would be, so it seems less risky than trying to
retrofit a new freewheel and derailer onto this twelve speed
that I can get for free." But again, I'm biased, I've done a lot
of tinkering with the twelve speed and can dissasemble and
reassemble it with my eyes closed at this point.

That said, it's a lot of fun to build things yourself (I've
reinvented more than one wheel just for that reason). 

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

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... :-/

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

I just took a quick peek at some Python scripts here. 

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?

| > 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! :-(

Well, maybe, but we (this list) might be able to get something we
could all agree on in pretty short order.

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

That'll work, too. Good luck!

                                        Cheers,
                                          norm
-- 
Norman Walsh <ndw@nwalsh.com>      | Growth for the sake of growth is
http://www.oasis-open.org/docbook/ | the ideology of the cancer
Member, DocBook Editorial Board    | cell.--Edward Abbey