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


> I have a feeling that writing a DTD/stylesheet combination that
> was simultaneously completely general and useful would be a
> <ahem/> significant challenge.

The DocBook project already looks as if it was a significant challenge
as well ;-)

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

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

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

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.

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.

> | I have nothing against specific "safe" features for popular languages,
> | but there should be some general fallback for others.
> 
> 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.

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

> Or choose a middle ground:
> 
>  - Extend DocBook with markup that supports Python really well.
>  - Update the stylesheets to support your new markup
>  - Submit your proposal for consideration in a future version of
>    DocBook.

Sounds reasonable. Except that I'd like to avoid messing around with
stylesheets; at a first glance they seem to be at least as complex as
the DTD itself!

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