[PYTHON DOC-SIG] SGML-Tools

[Fred L. Drake]

Ka-Ping Yee wrote:
> Hm.  Well, i hung around on the HTML working group list for
> quite a while and watched what was going on, and was thus
> interested enough to go find out more about how SGML works.

  No, but you're right: it does help to be aware of what's going on,
and *that* is still hard to come by.

> Perhaps one of the advantages of working in SGML is that we
> can use the existing SGMLParser stuff, and define Python

  My thought exactly; either SGML or XML should be easy to support if
we don't do anything elaborate in the documents, but I would want to
make it more general and robust.  (Preferably by a lot....)  Another
possibility would be to write another SGMLParser implementation around
nsgmls output; this keeps the document-type stuff similar to what we
have now while allowing substantial SGML to be used as needed.  I
expect we'd at least want to support general entities in the internal
declaration subset.  That would allow:

<!doctype pydoc [
  <!entity python cdata "My Favorite Programming Language">
  ]>
<pydoc>
  <title>Python!
  <abstract>This is about &python;!  By the time you've read this,
  it will be yours too!
  </abstract>
  ...
</pydoc>

  One (potential, at least) problem is that the SGMLParser stuff in
Grail is *not* part of the Python standard library.  It is part of
Grail and might not be available.  A re-implementation of the
interface using nsgmls as a backend would not be difficult to write,
but raises the entry fee.

> Another alternative is to use James Clark's nsgmls parser
> and then examine the output from that, which is emitted in
> a straightforward list of commands, one per line.  I think
> the LinuxDoc people use this approach.

  They do.  A huge number of SGML processes are built around exactly
this; I'd really like to see this done using Python instead of Perl.

> However, there is the issue of embedded documentation.  I
> suspect that many people will not want to enter SGML when
> they are editing docstrings for classes or functions, yet
> still desire the power of a "real document" to write
> reference material, so that we'll have to decide on two

  Docstrings are separate.  My inclination is to take one or more of
the formats that have been proposed for docstring conventions and
providing a parser that can load a source file and generate the
corresponding SGML.  This can be done as simply another implementation
of the SGMLParser base class.  (Yes, at some point I'll rip the parser
and handler classes apart, but probably not for Grail 0.3.)


  -Fred

--
Fred L. Drake, Jr.
fdrake@cnri.reston.va.us
Corporation for National Research Initiatives
1895 Preston White Drive
Reston, VA    20191-5434

_______________
DOC-SIG  - SIG for the Python Documentation Project

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