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

["Fred L. Drake, Jr." <fdrake@cnri.reston.va.us>]

Norman Walsh writes:
 > In an effort to stimulate further discussion of extended DocBook
 > synopses (for modern and OO languages), I've published an
 > extension containing my proposal and print/HTML DSSSL

  After taking a look at the DTD fragment and examples, it appears
that the way to use this is something like (not using legit. element
names):

        <classsynopsis language="Python">
          <classname>Message</classname>

          <fieldsynopsis>
            <type>list</type> <!-- "mutable sequence"? -->
            <varname>headers</varname>
          </fieldsynopsis>

          <methodsynopsis class="constructor">
            <methodname>__init__</methodname> <!-- required but useless -->
            <methodparam>
              <type>file</type> <!-- "file-like object"? -->
            </methodparam>
          </methodsynopsis>

          <methodsynopsis>
            <type>list</type> <!-- "mutable sequence"? -->
            <methodname>getheaders</methodname>
            <methodparam>
              <type>string</type>
              <parameter>key</parameter>
            </methodparam>
          </methodsynopsis>
        </classsynopsis>

  Now for a few comments & questions:

  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
      name is always __del__.  I imagine the C++ people have similar
      complaints for the destructor, and the C++ and Java people may
      share this concern for the constructor (you really only want to
      specify parameters).

  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.  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
      be able to distinguish between a "file" and a "file-like
      object".  (There are some issues for the Python community to
      deal with, namely names of abstract interfaces beyond those
      described in the language documentation.)

  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}

        \subsection{FooFrobber Objects \label{foofrobbers}}

          More explanatory text...

          \begin{methoddesc}{frob}{arg1, arg2}
            Description of method...
          \end{methoddesc}

      When a module offers several classes, it can be very convenient
      to introduce the classes at the top and describe their use at
      the high level, and then refer readers to subsections for
      information on the specific methods.

      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)
        - How do I add the descriptions in the first place?

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

  5.  Packages are similar to modules, but may also contain modules.
      We could mark them up as modules that have dotted names.

  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.

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

  -Fred

--
Fred L. Drake, Jr. <fdrake@cnri.reston.va.us>
Corporation for National Research Initiatives