Re: [Docutils-develop] reST.php?

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

Dethe Elza wrote:
> Also, if we parse directly to a DOM it makes reST more flexible and
> easier to port, since a DOM binding exists for most languages.  Many
> DOMs use either SAX or Expat to build the DOM itself, my idea would
> be to replace the low-level parser with reST.

I don't see how that would improve flexibility.  The parser can
already build a real DOM tree; just call ``document.asdom()``.  What
benefits would a DOM approach provide?  I'm not being defensive; I'd
really like to know.  If there is a benefit that outweighs the cost,
it should be explored.

> Building up a true XML DOM internally has several advantages.  More
> potential developers would be familiar with the API than are
> currently comfortable with the reST internals.

I don't think the document tree is the bottleneck.  Rather, I think
it's the complexity of the parser.  Unfortunately, parsing
reStructuredText *is* complex, because it has to grok two-dimensional
patterns that humans understand implicitly.  It's the curse of
user-friendliness. ;-)

> Writers could be written in XSLT without knowing anything about reST
> besides it's DTD.

This can already be done: just use ``document.asdom()`` then run that
through the XSLT engine.  The reason we don't go that route is because
there is no XSLT engine in core Python.  If PyXML is ever incorporated
into the core, we can re-examine that decision.

> And my *other* project of converting existing HTML and DocBook
> documents into reST for maintenance would be that much easier!

I don't follow this at all.  Can you elaborate?

> Even further off-topic, the docs mention that reST has constructs
> which are missing from DocBook.  What are they?

There are plenty.  Off the top of my head: field lists, option lists,
decorations (headers & footers), doctest blocks, line blocks,
transitions.  None of these are difficult to render or approximate
using regular DocBook elements, it's just that there's no one-to-one
correspondence.  Even in elements where there *is* a strong
correspondence, some are not completely compatible, such as definition
lists.  It is the goal of http://docutils.sf.net/spec/doctree.html to
document all of this; any assistance would be gratefully accepted and
much appreciated.

The Docutils document model was designed by me (with much input, of
course), as it makes sense to me.  I've had some experience with
various models, including DocBook and TEI, and I've designed several
DTDs before.  Every document designer has different sensibilities, so
differences and incompatibilies are inevitable.  For example, I know
of no DTD that has the equivalent of a "transition" element, although
they're quite common in novels and articles.

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