docutils-users

[Docutils-users] Custom writer

[Patrick K. O'B. <po...@or...>]

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.

Here is what I have in mind. IBM has a custom xml specification for 
tutorial files. When you create a tutorial in their xml format, they 
have a bunch of tools that transform that xml into several html files 
(with the IBM headers, footers, etc.), a US letter size PDF, an A4 size 
PDF, a zip file, etc. I just did my first tutorial for them and I used 
my own xml-generating Python utility to do so. It worked, but it wasn't 
exactly pretty and it was too much work, compared to a structured text 
approach.

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? 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. The current 
tools seem to me (and I could be wrong) to expect to be able to handle 
the full range of RST conventions. The other issue is whether the IBM 
format expects certain things that RST doesn't currently allow.

The IBM tutorial stuff is called Toot-O-Matic (no joke) and is available 
at https://www6.software.ibm.com/dl/devworks/dw-tootomatic-p. It's 
mostly Java and XSL stuff.

An article about it is at 
http://www-106.ibm.com/developerworks/xml/library/x-toot/index.html

Any suggestions or advice would be greatly appreciated.

-- 
Patrick K. O'Brien
Orbtech      http://www.orbtech.com/web/pobrien
-----------------------------------------------
"Your source for Python programming expertise."
-----------------------------------------------

Re: [Docutils-users] Custom writer

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

On Fri, Dec 13, 2002, 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.

If you look in sandbox/aahz, you'll see what I've hacked up to produce
OpenOffice.org XML.
-- 
Aahz (aa...@py...)           <*>         http://www.pythoncraft.com/

"To me vi is Zen.  To use vi is to practice zen.  Every command is a
koan.  Profound to the user, unintelligible to the uninitiated.  You
discover truth everytime you use it."  --...@li...

Re: [Docutils-users] Custom writer

[Patrick K. O'B. <po...@or...>]

On Saturday 14 December 2002 12:44 am, Aahz wrote:
> If you look in sandbox/aahz, you'll see what I've hacked up to
> produce OpenOffice.org XML.

Thanks. Having looked at your code, as well as the other sandboxes, I 
think what I want to do isn't too crazy. Has anyone ever written a 
quick overview of how to go about a custom application of reST?

-- 
Patrick K. O'Brien
Orbtech      http://www.orbtech.com/web/pobrien
-----------------------------------------------
"Your source for Python programming expertise."
-----------------------------------------------

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/

Re: [Docutils-users] Custom writer

[Patrick K. O'B. <po...@or...>]

On Saturday 14 December 2002 10:10 am, David Goodger wrote:
> 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!  ;)

I'm taking notes. I was going to see if I could make an article out of 
this effort.

> There is some other information available:

Thank you for all the tips and links. Looks like just what I needed.

-- 
Patrick K. O'Brien
Orbtech      http://www.orbtech.com/web/pobrien
-----------------------------------------------
"Your source for Python programming expertise."
-----------------------------------------------

Re: [Docutils-users] Custom writer

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

I looked at the DeveloperWorks tutorial DTD (dwtut.dtd) and supporting
docs.  It seems quite straightforward: a custom set of structural
elements wrapping an HTML core.  It would require a few directives
(like "example-column", "image-column", perhaps "xml-listing" etc.)
and a mapping of document -> tutorial, top-level section -> section,
next-level section -> panel.  Ideally the Toot-O-Matic Writer
component should check that no unsupported elements are present
(lower-level sections, tables, etc.).  It looks doable.  You may want
to subclass the writers/html4css1.py module, although your XML is so
different that copy&paste may be easier.  I'll be happy to answer any
questions.

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

Re: [Docutils-users] Custom writer

[Patrick K. O'B. <po...@or...>]

On Monday 16 December 2002 08:38 pm, David Goodger wrote:
> I looked at the DeveloperWorks tutorial DTD (dwtut.dtd) and
> supporting docs.  It seems quite straightforward: a custom set of
> structural elements wrapping an HTML core.  It would require a few
> directives (like "example-column", "image-column", perhaps
> "xml-listing" etc.) and a mapping of document -> tutorial, top-level
> section -> section, next-level section -> panel.  Ideally the
> Toot-O-Matic Writer component should check that no unsupported
> elements are present (lower-level sections, tables, etc.).  It looks
> doable.  You may want to subclass the writers/html4css1.py module,
> although your XML is so different that copy&paste may be easier.
>  I'll be happy to answer any questions.

Great. You've confirmed my impressions. Thank you. I'll plan to work on 
this as I have time available.

-- 
Patrick K. O'Brien
Orbtech      http://www.orbtech.com/web/pobrien
-----------------------------------------------
"Your source for Python programming expertise."
-----------------------------------------------