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

[Fred L. Drake]

Paul Prescod writes:
 > I think we should tackle the tutorial first, as it will require less
 > custom markup and programming.

  As Guido pointed out, there are non-technical reasons not to mess
with this one.  I think the primary advantages or SGML/XML come about
when dealing with something interesting like the Library Reference,
which offers a need to heavily structured data and substanstial
sections of prose.

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

  When I last looked at the interfaces, jade and the grove interface
were new.  I'll take a look at the grove interface when I get a
chance; it does sound like it would be more useful.

 > 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

  For static output there should be no need to use anything other than 
jade & a collection of stylesheets.  I was thinking more along the
lines of run-time access to the library reference, which could be used 
to support interactive help systems and the like.  It may be that
static generation of a more Python-friendly format would be
appropriate; perhaps a shelf as a repository for small documentation
objects that could then be rendered for display at runtime based on
user preferences or context.


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