Re: [Docutils-develop] Writing reST tools

[David G. <go...@us...>]

Aahz wrote:
> Okay, so there's simple docs on writing documents in reST, but I'm
> having difficulty figuring out how to write tools for processing reST
> without understanding the whole system, particularly given that I'm not
> exactly an XML geek.

A "How a Writer works & how to write one" document is on the to-do list, but
that's all so far.

> 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. ;-)

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.

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.

Next, ask questions.  Iterate.  Continual incremental improvement.

-- 
David Goodger  <go...@us...>  Open-source projects:
  - Python Docutils: http://docutils.sourceforge.net/
    (includes reStructuredText: http://docutils.sf.net/rst.html)
  - The Go Tools Project: http://gotools.sourceforge.net/