[Docutils-develop] structural inside body (was Re: Boxes)

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

[Beni Cherniavsky]
> That brings me to the deeper question.  Why can't a
> topic/blockquote/etc. contain headings?

Quick answer: complexity and precedence.  It would make the document
model too complex.  And I know of no serious document model that
allows such a construct.  I don't consider HTML "serious": it is (or
has become) a loose presentation markup.

> My feeling for a blockquote or any other contstruct delimited by
> increased indentation is that it should be able to contain whatever
> the top-level document can contain:

The entire point of the "topic" element is that it is a terminal
structural node; it can't contain further structure (sections, topics,
etc.).  "Topic" is analogous to DocBook's "simplesect", but actually
usable in more places: "simplesect" can only be the last elements of a
structural container.

The case of a "sidebar" is a bit different:

[David Goodger]
> I would suggest an element structure like this (for addition to
> spec/docutils.dtd)::
> 
>     <!ELEMENT sidebar (title, subtitle?, (%body.elements;)+)>
>     <!ATTLIST sidebar %basic.atts;>

Sidebars are like mini-documents within a document.  I almost added
something like "sidebars may eventually expand to allow structural
elements", but thought "keep it simple for now".  Even if we do allow
structural elements, I can't see adding more than one level, which may
rule out adding "section" to the model (it's recursive).  In any case,
I'd rather start simple and wait for a valid use case before making it
complex.

[Beni Cherniavsky]
>       - True, this is rare that you need complex things inside
>         blockquotes.  It's not the intened use.  But sometimes you
>         need just that.  And for some things, like titles [1]_,
>         nesting would be more natural than adding specific options
>         (that you must remember!) to every directive...
...
>       .. [1] Perhaps it even makes sense to make the mapping from
>              heading style to level inside each blockquote
>              independent from the mapping of the outer document.

You begin to see some of the complexity issues!  Are they worth it?

>       - Disclaimer: I haven't tried out how much these constructs
>         work.  I just talk from my understanding of the spec which
>         seems to imply that the document consists of 4 levels, so
>         that lower levels can't contain higher-level constructs:
> 
>         1. sections/transitions
>         2. body elements
>         3. physical paragraphs
>         4. inline markup

That's fair.  I call (1) "structural elements", and consider
paragraphs (3) to be just one instance of (2).  I divide body elements
into two types: simple, and compound (contain other body elements or
subelements).  And the spec doesn't just imply this; it's explicit.
See <http://docutils.sf.net/spec/doctree.html#element-hierarchy> (the
diagram needs to be updated a bit).

>         I can live with the restrictions on 2 in 3 and 3 and 4 but I
>         don't see much point in forbidding 1 inside 2.

Where do we draw the line?  Do we allow sections inside tables?
Although being an "organic" invention and therefore potentially
riddled with exceptions, documents do tend to follow the
structural-body-inline hierarchy.  I want to keep the Docutils
document model as simple as possible.

-- David Goodger    http://starship.python.net/~goodger

Programmer/sysadmin for hire: http://starship.python.net/~goodger/cv