Re: DAVENPORT: DocBook for documenting Python code

[Norman Walsh <ndw@nwalsh.com>]

/ Konrad Hinsen <hinsen@cnrs-orleans.fr> was heard to say:
| Norman Walsh <ndw@nwalsh.com> wrote:
| > Well, I'd be happy to help write a customization layer for the
| > stylesheets that did Python instead. Most of the examples I have
| > are in C or a C-like language, so that's what I coded up.
| 
| But is the stylesheet the right place to put such information? It
| would have to cover hundreds of programming languages to be general.
| And I might invent my own next week, published together with a manual
| written in DocBook. I'd much prefer a DTD/stylesheet combination
| that lets me take care of specific syntax myself.

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

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.

If you invent something completely new markup, you're going to
have to invent a stylesheet for it, too.

| > In an effort to improve the accuracy of document interchange,
| > DocBook has some explicit processing expectations. As you've
| > noted, these are rather C-like.
| 
| 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 am definitely interested. But this raises another point: I must
| write my manuals now, not when some great new DocBook version comes
| out. Is there some general mechanism to deal with information for
| which no specialized markup exists? My priorities would be

The best advice I can offer is select tags that have the best
combination of similar semantics and useable content models and
then use the role attribute to subclass them.

| 1) Decent results with current DocBook processors (i.e. stylesheets).
| 
| 2) Easy conversion to better markup when available.

Easy conversion from one markup to another is a holy grail. The
best that can be said is that structural markup decorated with
role attributes ought to be a good starting point.  Better than
most, anyway.

| At the moment I just use <literal> with various role attributes for
| everything Python-related, which seems to work well. But it isn't
| nearly as detailed as the existing markup for C code, so if in the
| future there will be better ways to do it, I'd have to make manual
| changes, which is unlikely to happen.

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

| Another approach would be to invent my own markup and have it
| machine-translated to current DocBook. But then I might just as well
| forget about DocBook and create my own DTD!

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.

                                        Cheers,
                                          norm
-- 
Norman Walsh <ndw@nwalsh.com>      | Resist the urge to hurry; it will
http://www.oasis-open.org/docbook/ | only slow you down
Member, DocBook Editorial Board    |