[DOC-SIG] Re: [PSA MEMBERS] [XML] Notes on the Tutorial's markup

[Paul Prescod]

Fred L. Drake wrote:
>   I expect initial conversion of the Library Reference could be done
> using Python, and then "fixed up" manually using an editor like XEmacs
> (or Emacs) and PSGML mode.

I think we should tackle the tutorial first, as it will require less
custom markup and programming.

>   Regarding processing, I'd have no problems using SP to do this; a
> Python interface to the generic interface would not be difficult to
> create, if a little tedious.  I'm willing to do this, but it would be
> evenings / weekends, and only if it'll get used.

If you do this, I would strongly encourage you to skip the Generic
Interface and move to the more poweful Grove Interface. On Windows, this
interface is already available through COM. I think it is relevant that
the grove is the only interface that James Clark explicitly chose to
publish for scripters (Windows scripters). Note also that the grove
interface is explicitly designed for "wrapping" as James did with COM.
The Perlers have also made a wrapper for the grove interface, so we've
got an "interface gap" there. The SGML Tools (was LinuxDoc) project is
moving to the Perl/Grove interface, I think. 

The grove interface is more powerful because it provides access to the
entire SGML document at once. This is an awesome amount of context and
it makes life much easier. Rather than squirreling away little bits of
information to be used somewhere else, you can make a function to look
them up in the grove. Also, it makes forward references a hundred times
easier. The days of running a program six times to resolve references
are past, I think.

It might seem that this would take up too much RAM, but experience shows
it to be very efficient. On modern computers, it is probably much more
efficient than the multiple-pass processes of the past.

Using the grove interface is one of the major things that makes Jade so
much easier to use for processing SGML documents than Perl/Python. The
grove interface is one of the major arguments of favour of SGML over
something macro based. I've got a simple Python Library that implements
a subset of Jade's grove interface, but it is written entirely in Python
and it's slow. I could speed it up with optimization, but would rather
just make the grove wrapper when I get time to digest all of the
interfaces.

But anyhow, cool as the grove interface is, it isn't clear yet that we
need any interface for this particular project. Hopefully we can depend
on the existing tools (Jade and existing stylesheets). Once we want to
go beyond their capabilities, we must decide whether to extend Python to
be as powerful as Jade (through wrappers to Jade's internals) or just
use Jade/Scheme. My dream come true would be to subclass Jade's
interpreter object and allow it to read in Python classes and use them
to completely drive the processing (instead of the usual Scheme files).

 Paul Prescod

_______________
DOC-SIG  - SIG for the Python Documentation Project

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