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

["Fred L. Drake, Jr." <fdrake at acm dot org>]

Norm,
  Sorry I've taken so long to get back to you on this; general
swampage, kids, and having to get paid work done, you know.  ;-)

Norman Walsh writes:
 > 1. Make <methodname> optional or
 > 2. Add <constructorsynopsis> and <destructorsynopsis> with optional
 >    <methodname>s.
 > 
 > Despite tag proliferation, I think I prefer 2. Comments?

  I agree; 2 seems more explicit, which is something we like in the
Python world.  It certainly makes it hard to misinterpret.

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

  A type is specific: the name of a class or "built-in" type
(integers, etc).  An abstract type is more like a Java interface,
except there's no declaration for it.  For instance, a function may
operate on sequence objects, but there's really nothing that
corresponds to a class name.  There's no base class, but the interface 
is known to behave in certain ways.  There are other common cases in
Python as well.  "File-like objects" are very popular!  ;-)

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

  An abstract type is very much like a Java interface, without the
explicit explicit declaration.

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

  I'll have to look at the <refentry> documentation a bit.  I'm not at 
all sure that's quite what I want; I'd like the description of
something described by <*synopsis> to be tightly bound to the
<*synopsis>; perhaps some sort of container that could be used in place 
of a "raw" <*synopsis> with a content model something like:

   <!ELEMENT describedsynopsis ((funcsynopsis|methodsyopsis|...),
                                (%some.sort.of.para.mix;)+)>

[I said stuff about the current organization of module contents;
 you said:]
 > I think you need what I said above, the ability to put these synopses
 > in the middle of other stuff.

[Then I spoke of marking up modules, and you said:]
 > I haven't got a good answer for this one. Although if I loosen things up, 
 > maybe it would fit in <refentry>.

  I've asked someone in the Python community who expressed an interest 
in helping about writing a (relatively) formal requirements document
for the Python documentation structures; that should provide an
opportunity for us Python types to clarify just what we need and what
we want.  I'm strongly in favor of making the Python documents more
structured; there is an increasing number of opportunities to use the
documentation as a source of online help in IDE-style tools, and that
means that data-structure is quite important.  It may be that module
references will become more tightly structured than they are now, and
the textual organization may change.  Or it may prove not to be too
hard to generate the current layout from more structured reference
information.
  I definately have some thinking to do on this one before Python can
decide on a DTD for the standard documents.

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

  Good point; I have a few instances of \method{start_\var{tag}} in
our SAX-like interfaces (htmllib, sgmllib, xmllib).

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

  Wow, I didn't get back to this in time for that, did I?  ;-)  Maybe
I should go back and look to see if you've already made some changes
to the extension!

  -Fred

--
Fred L. Drake, Jr.	     <fdrake@acm.org>
Corporation for National Research Initiatives