This is the mail archive of the
davenport@berkshire.net
mailing list for the Davenport project.
Re: DAVENPORT: DocBook for documenting Python code
/ 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