> I'm currently writing a formatter class
> that creates a Docutils document tree using a sequence of calls like th=
> formatter.paragraph(1) # open new paragraph
> formatter.text('This is a ')
> formatter.emphasis(1) # open emphasized text
> formatter.emphasis(0) # close emphasized text
> formatter.text(' text.)
> formatter.paragraph(0) # close paragraph
> which will result in the following doctree:
> This is a
> This is for compatibility with existing MoinMoin parsers.
> The problem is that the calls above may not always give a valid doctree=
> My implementation must be very robust, though, so I want to recover=20
> from cases like this:
> formatter.text('some text')
> formatter.paragraph(1) # ugh, the line_block isn't closed yet
> In this case, I'd like to recognize that the line block cannot contain =
> paragraph and automatically close it.
That smells like the wrong approach. Rather than automatically doing any=
it would be better to raise an exception and fix the offending code.
> Recognizing this is a problem, though, because I cannot tell from the=20
> base classes of line_block (General, Element) that it may only contain =
> Part nodes.
> So, I'd like to mark up all nodes that contain part nodes with some
> special base class, just like TextElement is the base class for all
> nodes that contain Text and Inline nodes.
No such invariant holds though. There are exceptions: block_quote contai=
regular body elements (paragraphs etc.) *and* attribution elements, which=
> Do you think that this is the right way to do it?=20
It would offer very limited validation functionality. I doubt if adding =
"recovery" code is worthwhile. Better to spend the time ensuring your do=
generation code is correct, and add unit tests.
But adding a new category base class to docutils.nodes wouldn't hurt anyt=
so as long as that's the limit of the change to Docutils, go ahead -- I d=
care either way.
> Any suggestions for the name of the base class? "Composite"?
They're called "Compound" in docs/ref/doctree.txt, but there is now a "co=
element, so this name could be confusing. "Composite" would be fine. Fo=
list of applicable elements, see
David Goodger <http://python.net/~goodger>