Re: [Docutils-users] closing a header block

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

I suspect that you may need a sidebar or topic in place of your section
level 2: https://docutils.sourceforge.io/docs/ref/rst/directives.html#topic
Or maybe a rubric:
https://docutils.sourceforge.io/docs/ref/rst/directives.html#rubric

IMHO, a "popped" section is meaningless and you don't need it.

Some questions come to mind:

Why do this? What is the purpose?

What would this "popped" section mean? What does it represent?

How would this be represented on the screen or page? How would the reader
*know* that the section level had been "popped"?

Have you ever seen this in the real world? Please show us an example or
three.

If you absolutely insist, if you must "pop" the section level, here's an
ugly workaround:

Level 1
=======

Level 2
----------

\
====


That last title is a backslash followed by a space. It produces a level-1
section with no title. You could make it explicit with a title of "title
omitted", apply a class to it, add some CSS, and have it disappear
completely.
Use at your own risk.

David Goodger
<https://david.goodger.org>


On Wed, May 26, 2021 at 3:55 PM Sidney Cadot <si...@ji...> wrote:

> 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
>
> _______________________________________________
> Docutils-users mailing list
> Doc...@li...
> https://lists.sourceforge.net/lists/listinfo/docutils-users
>
> Please use "Reply All" to reply to the list.
>