Re: [Docutils-users] Custom writer

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

Patrick K. O'Brien wrote:
> I'm wondering how hard it is to create a custom writer. In
> particular, one that produces a particular type of xml file. I've
> read all the docutils documentation and most of the emphasis seems
> to be on how to write text using RST, or what kind of HTML it
> produces. What I haven't seen much of is how to use RST for a
> particular application.

A void waiting to be filled!  What an opportunity for you!  ;)

There is some other information available:

* PEP 258 gives an overview of the architecture:
  <http://docutils.sf.net/spec/pep-0258.html>
* The DTD gives the schema for the internal data structure (which is
  what a Writer component translates from):
  <http://docutils.sf.net/spec/docutils.dtd>
* "The Docutils Document Tree" describes the DTD:
  <http://docutils.sf.net/spec/doctree.html>

The DTD and doctree doc only describe part of the internal data
structure, the part that is exposed as XML using the docutils-xml.py
front-end (which uses the writers/docutils_xml.py module).  The rest
of the details (keeping track of hyperlinks and other bookkeeping) is
documented inside the docutils/nodes.py module in docstrings.  I'm
sure it's not complete though.  Take a look at the existing writers to
see how they work.  In the main distribution, see
docutils/writers/html4css1.py.  In the sandbox, see sandbox/aahz/OO/
(OpenOffice.org writer) and sandbox/oliverr/docbook/, both of which
produce XML.

For anything that's not clear, please ask (doc...@li...
is probably more appropriate), and I will endeavour to answer.  These
answers will undoubtedly find their way back into the documentation.

> What I'd like to do next is be able to create tutorials in structured
> text and have a tool that produces a valid IBM tutorial xml file. Can
> anyone tell me if this is a sensible application of RST?

Sure, sounds fine.

> One of the constraints is that it would have to limit the structured
> text to the features that are supported by the IBM tutorial xml spec.

Feasible, by code reinforced by documentation.  I don't have time to
look up the references you've given; I will next week.

> The current tools seem to me (and I could be wrong) to expect to be
> able to handle the full range of RST conventions.

In all cases, the final output format doesn't match exactly with the
Docutils doctree.  Usually the solution is to map Docutils constructs
onto one or more target primitives.  The HTML writer does that a lot.

> The other issue is whether the IBM format expects certain things
> that RST doesn't currently allow.

That may be a more immediate issue.  Worse comes to worst, you can
always create custom directives for the specialized data.  The "raw"
directive may be a useful stop-gap.

[later...]
> Thanks. Having looked at your code, as well as the other sandboxes, I
> think what I want to do isn't too crazy.

Not crazy at all.

> Has anyone ever written a quick overview of how to go about a custom
> application of reST?

Engelbert Gruber has collected some notes in
<http://docutils.sf.net/sandbox/grubert/making_a_writer.html>.  It
needs a lot of fleshing out though.  You may get some pointers from
Oliver Rutherfurd's
<http://www.rutherfurd.net/articles/rst-ht2html.html>.

-- 
David Goodger  <go...@py...>  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/