Re: [Docutils-develop] reST.php?

[Dethe E. <de...@ma...>]

>> I didn't know about asdom(), I'll have to explore that to see how
>> expensive it is and which DOM implementation it uses.
>
> It uses xml.dom.minidom, but it's intended to be able to use any DOM
> implementation (it's parameterized).

Excellent.  But reST actually converts to the DOM when you call 
asdom(), right? So it's a potentially expensive operation.

> Please don't think of *any* part of the current Docutils
> implementation as written in stone.  It's all experimental, all
> subject to change if we discover it's broken or deficient in some way.
> That's what the "0." part of the "0.2" ("0.2.3", currently) version
> number is meant to imply.

Point taken, and I'm glad we're able to have these discussions in that 
light.

>> I still think that the internals could be simplified and that this
>> would encourage more participation in the project.
>
> There are hairy parts of the parser code which could use refactoring,
> true.  You're working on one of them: the directive parser.  In the
> parser's core code (states.py), there's some duplicate code that could
> be refactored.  But that's low priority on my list at present.  It
> ain't broke (much), so it's not important (to me) to fix it (yet).

No, of course not.  Some things jump out at me because I'm new to the 
project.
If I find they're important enough to me, I may jump in and fix them.

>> I agree that the parser is the most complex component of reST, so if
>> it focuses on the parser and reuses architecture from the python
>> libraries for the rest of reST it may be easier to grok for a
>> programmer coming to it fresh.
>
> Ideally yes, but in practise it's too expensive.  It's just too
> convenient for a transform to say ``isinstance(node, Body)``, since
> the element hierarchy is built in to nodes.py.  This would be painful
> if we were using a DOM tree.

Why is node.nodeName == 'Body' more expensive than isinstance(node, 
Body)?
If it's because of a string compare rather than a pointer compare, then 
the strings can be interned and it's a pointer comparison again.  Or is 
there some other reason?


>>  Ideally I also want a writer to create reST from the reST
>> DOM.
>
> That last sentence seems to me the key, and that's exactly what's
> missing.  Transforming canonical Docutils DOM to internal nodes.py
> doctree should be reasonably easy, but without the reStructuredText
> writer, it's practically useless.  If I were writing a converter from
> XHTML or DocBook to reStructuredText, I would do it in a quick & dirty
> way, completely independently of Docutils (as I've described before).

Yes, and that's what I've done so far.  But once I'm done with the 
include
directives I want to take a look at a reST DOM -> reST text writer to 
get a
feel for how tricky it will be.

> In addition, there's a lot going on behind the scenes that the
> Docutils DTD doesn't expose.  Try running ``html.py --dump-internals
> input.txt ...`` to see what I mean.  ("--dump-internals" is an
> internal, hidden option, for debugging.)

OK, but without knowing more about *why* that is, it looks like a bug 
to me.
It's Tim Peter's koan, "explicit is better than implicit."  Once we 
start getting too much magic going on under the covers, python starts 
veering towards perl.  IMHO that's one
of the major problems in Zope, and makes work in Zope, beyond the very 
trivial, much
harder to do and to understand than it would otherwise be.

>  I don't know of a decent/standard DTD for novels out there.

Hah! That's perhaps the reason I like reST so much.  Right now I'm 
using it for technical documentation at work, but the reason I got into 
the work I'm in is because I was so frustrated with word processors and 
proprietary formats that I've put my creative writing on hold for 
several years to work on tools.

One of my upcoming projects is to pull one of my unfinished novels out 
and serialize it on my weblog using reST.  I really like the way I can 
more or less forget about the tool and focus on writing--it's almost as 
good as a typewriter that way!

Of course, a typewriter never gives you compile errors.  That's a major 
problem with XML and currently with reST.  I have little hope of seeing 
it solved in XML, but I think we can and should make an effort in reST 
to make errors rarer, clearer, and more easily found/fixed.  A casual 
user should never have to see a python stack trace, for instance.

Fortunately, what's there is rich enough and stable enough to think 
about things like catching all the exceptions.  And it may only be that 
I see a lot of exceptions because I'm working on a) very long and 
complex documents, and b) actively changing the guts of the system.

TTFN

--Dethe