[Docutils-users] closing a header block

[Sidney C. <si...@ji...>]

Hello all,

I am using docutils through Sphinx, and I am running into an issue there,
which I think should best be solved in the RsT parsing stage. Ideally, this
could be addressed by a directive, or perhaps there is some other way that
any of you can point me to. Anyway here's the issue:

When parsing RsT, nested sections are created by the RsT. It will add (or
change) hierarchical levels when it encounters heading lines. And a
hierarchical level is valid up to the next header line.

(If my superficial understanding of the RsT source is correct, this is
mostly handled in the docutils.parsers.rst.RSTState.check_subsection()
method.)

Okay. While this model is easy to understand and use, it does leave some
types of reasonable document structures out of reach. In particular, if I
want to "pop" a heading level to the next higher (or any higher) level
without introducing a new header, I am stuck.

As an example, suppose I have this text:




*section level 1===========*


*First lorem ipsum etc etc.*





*Section level 2--------------------Second lorem ipsum etc etc.*

*Alea iacta est!*
Now in the current parser, the "Alea iacta est" paragraph will sit at
section level #2. In pseudo-XML, the parse tree will be:


*<section level="1">*

*    <p>First lorem ipsum etc. etc.</p>*
*    <section level="2">*

*        <p>Second lorem ipsum etc. etc.</p>*

*        <p>Alea iacta est!</p>*

*    </section>*
*</section>*

What I want to do however is end the "section level 2" before "Alea iacta
est", and resume parsing section level 1.

So I want my parse tree to be (again in pseudo-xml):


*<section level="1">*

*    <p>First lorem ipsum etc. etc.</p>*
*    <section level="2">*

*        <p>Second lorem ipsum etc. etc.</p>*

*    </section>*

*    <p>Alea iacta est!</p>*

*</section>*
I have a few questions....

First, is this already somehow possible? Is there some syntax that directs
the parser to produce the second parse tree?

Second, if not: is there a fundamental reason why the second parse-tree
would be incompatible with the document model of RsT? (If that's the case,
why?)

Third, if it is possible in principle, but not yet in practice, is there a
way to implement this without touching the parser; say, by adding a
docutils Directive? E.g. something that would work like this?




*section level 1===========*


*First lorem ipsum etc etc.*





*Section level 2--------------------Second lorem ipsum etc etc.*

*.. pop-heading-level*

*    :levels: 1*


*Alea iacta est!*

Any insight into this will be much appreciated.

Kind regards, Sidney