Re: DAVENPORT: Announce: Extended DocBook Synopses v1.0

[Norman Walsh <ndw@nwalsh.com>]

/ "Fred L. Drake, Jr." <fdrake@cnri.reston.va.us> was heard to say:
|   1.  <methodsynopsis> requires a <methodname/> element, but for
|       Python constructors, it's always __init__.  I do *not* want to
|       have to include that, since the stylesheets would be required to 
|       get rid of it, other users would start to get really annoyed by
|       it.  I know I would!  The destructor has the same issue; the

Ok, so I see two solutions:

1. Make <methodname> optional or
2. Add <constructorsynopsis> and <destructorsynopsis> with optional
   <methodname>s.

Despite tag proliferation, I think I prefer 2. Comments?

|   2.  <type/> seems to be for specific types; I'd like to be able to
|       specify return and parameter types as either a specific type or
|       an abstract type.

I see type as for the type name, how is an abstract type name in Python
different from a concrete type name?

|       The <classsynopsis/> allows an <interface/>
|       element for the class, but the docbook 3.0 reference says that
|       should be used for refering to components of a GUI.  I want to

Oh, barf! I hadn't noticed that name collision. Drat and blast!
I don't know what to do about that. I know what I'd like to do,
subvert Interface and steal it for this new purpose. Given that
it's losing it's class attribute in 4.0 and getting a
drastically simplified content model, we might just pull that
off.

I had intended <interface> to be for the Java-like "implements
this interface" construction. Is that what you had in mind as
well, or does Python have something else?

|   3.  The structure seems to be entirely hierarchical, though the
|       current Python documentation isn't.  What we have is currently
|       *not* structured that way at all, and I'm not convinced it
|       should be (for Python).  Documentation for a module is
|       structured like this:
| 
| 	\section{\module{foo} --- do foo stuff}
| 
|           % some module-level meta-information goes here...
| 
|           The \module{foo} module is used to frobnicate bar objects.
|           It provides the following class:
| 
|           \begin{classdesc}{FooFrobber}{arg1, arg2\optional{, arg3}}
|             Description, explaining the args, side effects, etc.
|           \end{classdesc}

This looks more like a <refentry> for each class which seems entirely
reasonable. Perhaps <fieldsynopsis> and <methodsynopsis> (and
<constructorsynopsis> and <destructorsynopsis>) should be made peer
to the other synopsis elements so that they can appear in the middle
of exposition, outside of a <classsynopsis>.

|       Now, I understand that a lot of re-ordering can be done with
|       style sheets, so marking up the class all at one point isn't a
|       huge problem (given someone sufficiently knowledgable to write
|       the stylesheets), but there are some issues that I don't see how 
|       to address:
|         - How do I mark up "put the explanation of method frob *here*"?
|           (document structuring, as opposed to data structuring)

Callouts, obviously. No, I didn't say that. Really. I didn't.

|         - How do I add the descriptions in the first place?

I think you need what I said above, the ability to put these synopses
in the middle of other stuff.

|   4.  How do I mark up module information?  Modules are very different 
|       from classes, and can include functions, classes, data, and
|       constants.  I imagine Perl would need something like this as
|       well, as well as other, less-common languages (SML, etc.).

I haven't got a good answer for this one. Although if I loosen things up, 
maybe it would fit in <refentry>.

|   6.  This markup seems very "heavy"; perhaps things like the names of 
|       methods/classes/parameters should be attributes of the various
|       elements?  Let's make this message a bit longer and try it out:
| 
|         <classsynopsis language="Python" name="Message">
|           <fieldsynopsis name="headers" type="list"/>
| 
|           <methodsynopsis class="constructor">
|             <methodparam name="fp" type="file"/>
|           </methodsynopsis>
| 
|           <methodsynopsis name="getheaders" type="list">
|             <methodparam name="key" type="string"/>
|           </methodsynopsis>
|         </classsynopsis>
| 
|       This may not be very "DocBookish", which would be a problem.

That's one problem. The other problem is that after you stuff something
in an attribute, you can never add more markup to it. I'm thinking that
you might want to put <replaceable>, for example, in a method name if
it was part of a template.

|   This message is too long, and I need to get some work done.  I'll
| keep thinking about this.

Thanks for the comments. If there's general agreement on the changes I
outlined above, I'll bang out a new version of edbsyn later this week.

                                        Cheers,
                                          norm

-- 
Norman Walsh <ndw@nwalsh.com>      | Everything the same; everything
http://www.oasis-open.org/docbook/ | distinct.
Member, DocBook Editorial Board    |