[DOC-SIG] Library reference manual debate

[Guido van Rossum]

Fredrik Lundh:
> Since I'm working on SGML/XML for our company's projects, at least I
> would much rather contribute to an SGML/XML based effort, than to
> hack on TIM. Others milage may vary, as usual ;-)

Fredrik, I'm afraid that you're already overcommitted -- I'd hate to
see the schedule for your book jeopardized.  (I think it is your
highest priority from the Python community's point of view.)

Otherwise, I'd challenge you to get started -- I'm sure you'd do a
great job.  Here's the challenge anyway -- maybe someone else can pick
it up.  I'm tired of hearing what *I* should do.  I've already hinted
on what I *would* do if I had to do it.  I'm more interested in
hearing from people who have done something that I (and the rest of
the Python community) can use.  "Use SGML" is not a productive
approach; "this is what I did using SGML" is.

What would be needed, at least at the proof of concept level, is a
tool that does the one-time conversion of a library manual section or
chapter to SGML, plus entries in Doc/Makefile that automatically
produce PostScript and HTML from the SGML.  Since these are the output
formats that are currently supported, it makes sense to require that
they are both supported by any proposed new system before it is
judged.  Knowing in the abstract that SGML can be converted to HTML
and PostScript isn't enough -- I want to see the generated HTML and
PostScript so that I (and others) can judge how good it is and what
still needs to be done.

As a concrete test, the Python library manual is full of sections like
this one:

    \begin{funcdesc}{sub}{pattern\, repl\, string\optional{, count=0}}
    Return the string obtained by replacing the leftmost non-overlapping
    occurrences of \var{pattern} in \var{string} by the replacement
    \var{repl}, which can be a string or the function that returns a
    string.  If the pattern isn't found, \var{string} is returned
    unchanged. The pattern may be a string or a regexp object; if you need
    to specify regular expression flags, you must use a regexp object, or
    use embedded modifiers in a pattern string; e.g.
    %
    \bcode\begin{verbatim}
    sub("(?i)b+", "x", "bbbb BBBB") returns 'x x'.
    \end{verbatim}\ecode
    %
    The optional argument \var{count} is the maximum number of pattern
    occurrences to be replaced; count must be a non-negative integer, and
    the default value of 0 means to replace all occurrences.

    Empty matches for the pattern are replaced only when not adjacent to a
    previous match, so \code{sub('x*', '-', 'abc')} returns '-a-b-c-'.
    \end{funcdesc}

How should this be translated to SGML?  Which DTD should be used?  I'm
not particularly happy with the way the argument list has to be
formatted in LaTeX, especially when optional or keyword arguments are
present -- can SGML do better?

For comparison, here's an example of a complex function description in
TIM:

    @deffn Function ORB_init (@metavar{argv}=(), @metavar{orb_id}='ilu')
    @ftindex CORBA.ORB_init (Python LSR function)

    Returns an instance of @class{@Python{CORBA.ORB}} with the specified
    @metavar{orb_id} (currently only the ORB ID @Python{'ilu'} is
    supported).  The arguments which may be passed in via @metavar{argv}
    are ignored.
    @end deffn

Note that one feature I like is that the LaTeX {funcdesc} environment
automatically creates the index entry for the function; it combines it
with some information provided earlier in the file:

    \renewcommand{\indexsubitem}{(in module re)}

I see that this is done manually in TIM (although I'm not sure why).

--Guido van Rossum (home page: http://www.python.org/~guido/)

_______________
DOC-SIG  - SIG for the Python Documentation Project

send messages to: doc-sig@python.org
administrivia to: doc-sig-request@python.org
_______________