[Doc-SIG] How to traverse a document object

[David Goodger]

Paul Moore wrote:
> a. I'm inserting new methods into the node classes, which is a little
>    presumptuous of me.

If you insert methods from outside the module, yes, you *would* be
presumptuous. If you edit the nodes.py module and submit a patch,
though, you'll be a contributing developer!

> b. I need to know the class names of the node classes, which seems to
>    be too tied to implementation specifics.

The document tree is meant to be an specific document/DTD/schema
implementation only, not a generic DOM.

> Nevertheless, its a pretty good tree walking model. It might be nice
> to have this in the node classes, except that there may not be a
> single "correct" walk order (a bit like the normal preorder,
> postorder, inorder issues).

I don't know how you'd do inorder with document trees. ;-)

It's most useful to have a hook on the way in and on the way out of an
element. I'm sure we can come up with a useful set of methods, perhaps
without having to reinvent the wheel, using polymorphism and without
resorting to magic. SAX comes to mind. Suggestions, references, and/or
patches welcome.

> .. [Offtopic] I would normally indent this list if I was writing
>    "plain" (ie, no markup) text. I'm not sure what effect such
>    indentation would have on reST. I get the impression I'd get an
>    extra "blockquote" element that I didn't want.

Correct.

>    Is this harmful?

Depends on what you mean by "harmful". :-)

>    Can it be avoided? In "plain" text, I *really* prefer the look
>    of lists when they are indented.

A transform could be written that looks for a block quote containing
only a list, and extracts the list from within the block quote. The
spec could be changed to specify that this will happen. But what if we
*want* a list inside a block quote? How else would we write it?

>    Even more offtopic - is this indented enough to be part of the
>    footnote? I think the indentation rules need more
>    clarification... [I did a test, and it is included...]

Yes. OK, the nitty gritties of the indentation rules should be spelled
out better. Added to the to-do.

> Sorry, this has all turned into a bit of a brain-dump. But that's
> probably because I'm feeling that I'm having to invent something
> that I expected to be part of the basic infrastructure.

Great value for the money though!

> Is it simply that no-one's got to the point of needing this
> implemented yet?

In my case, yes. I haven't tackled the output end yet.

What are you trying to do exactly? My interest is half-piqued. Provide
me a bit of stimulus and it may become fully-piqued.

> Thanks for listening,

Any time. Cheaper than psychotherapy.

-- 
David Goodger    goodger@users.sourceforge.net    Open-source projects:
 - Python Docstring Processing System: http://docstring.sourceforge.net
 - reStructuredText: http://structuredtext.sourceforge.net
 - The Go Tools Project: http://gotools.sourceforge.net