Re: [Docutils-develop] Section may not end with a transition?

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

[David Goodger]
 >>> I don't understand the semantic role of the
 >>> line.  What does it mean?

[Jarno Elonen]
 >> It separates two sub-documents (the statement and a differing
 >> opinion).

[Felix Wiemann]
 > What is bad about that?  If you have several headings per part, that
 > would IMO be a valid reason to use a transition at the end of a
 > section.
 >
 > Even if the transition is rendered as a vertical gap, it still makes
 > sense.

At first I thought, sure, we could loosen the document model and rip
out the code that prevents such usage.  No big loss.

But on further reflection, I realized that the real problem is that in
the example given,

     Heading 1
     =========
     foo

     Heading 2
     =========
     foo2

     -------------------

     Heading 3
     =========
     bar

     Heading 4
     =========
     bar2

the parse tree would look like this:

     <document>
         <section>
             <title>
                 Heading 1
             <paragraph>
                 foo
         <section>
             <title>
                 Heading 2
             <paragraph>
                 foo2
             <transition>
         <section>
             <title>
                 Heading 3
             <paragraph>
                 bar
         <section>
             <title>
                 Heading 4
             <paragraph>
                 bar2

Notice where the <transition> ends up?  It's *not* between sections,
it's in the second section ("Heading 2").  To make it clearer, I'll
replace <title>s and <paragraph>s with "...":

     <document>
         <section>
             ...
         <section>
             ...
             <transition>
         <section>
             ...
         <section>
             ...

A transition, by definition, must come between two things.  It cannot
begin or end a section.  So the document model would be wrong!

The intention seems to be this:

     <document>
         <section>
         <section>
         <transition>
         <section>
         <section>

That might make sense, but there's no way to tell the parser that the
transition should be one level higher in the document tree.  We could
add a directive, say "section-transition" [*]_, which could end the
previous section and insert a transition.  A section would *have* to
follow such a directive though.

.. [*] Or a "section-end" directive, followed by a regular transition
    construct.

 >>> Such usage would be abuse.  It's only an accident that a
 >>> transition renders as a horizontal rule in HTML.  In other output,
 >>> it may render as a large vertical gap or as three asterisks ("* *
 >>> *").
 >
 > What about simply documentating that?

It is: <http://docutils.sf.net/spec/doctree.html#transition>.

 > I think that it is not a good idea to detain the user from doing
 > that, if he really needs it.

But it's wrong, and it makes no sense to allow it.

-- 
David Goodger                               http://python.net/~goodger
For hire: http://python.net/~goodger/cv