Re: [Docutils-develop] Writing reST tools

[Aahz <aa...@py...>]

On Fri, Aug 02, 2002, David Goodger wrote:
> Aahz wrote:
>> 
>> My primary interest -- I think -- is in a Writer class, because I'm
>> trying to create OpenOffice documents.
> 
> OpenOffice docs are XML; internal Docutils document trees are
> equivalent to DOM trees, which is XML.  Guess what?  You're becoming
> an XML geek. ;-)

<sour look>  Yes, I knew that already.  Fortunately, I think I mostly
don't need to actually understand what I'm doing.

> A Writer walks the internal document tree, and translates each node
> or group of nodes into the target (OpenOffice) structure.  To write
> a Writer, you have to understand both the Docutils document tree and
> the target format.  I believe the OpenOffice document structure has
> some documentation (how good, I don't know).  The Docutils document
> tree is documented in spec/docutils.dtd, which is current but skeletal
> (it's only a gross structure description; it says nothing about
> semantics or internal node attributes), and in spec/doctree.txt, which
> is incomplete.  To get something more complete and fleshed-out, ask
> questions.  I'll be happy to answer, and those answers will go into
> the docs.  I'll try to work on the docs too, but it will go faster
> with prompting from you.

I was a bit confused about the relationship between write() and
translate(); I think the latter might be better named "visit()".

I'm less using the OpenOffice docs than I am writing OpenOffice
documents and examining the XML output.  

> Start by examining the most complete Writer module we have,
> docutils/writers/html4css1.py.  Take the output from processing a
> document with tools/docutils-xml.py, and compare to the output from
> tools/html.py.  The HTMLTranslator class in html4css1.py traverses
> the tree given by the docutils-xml.py output, which is equivalent
> to the internal document tree, using a Visitor pattern.  Every node
> in the document tree triggers a "visit_node" method on entry, and a
> "depart_node" method on exit.  These methods build a target format
> document one piece at a time.

Okay, got that.  It's not that different from sgmllib.

Now, how do I add a new directive?  (For index tags.)
-- 
Aahz (aa...@py...)           <*>         http://www.pythoncraft.com/

Project Vote Smart: http://www.vote-smart.org/