This is the mail archive of the
docbook@lists.oasis-open.org
mailing list for the DocBook project.
Re: DAVENPORT: Announce: Extended DocBook Synopses v1.0
/ "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 |