Re: closing a header block

Hi David,

> Why do this? What is the purpose?
> What would this "popped" section mean? What does it represent?

It is a continuation of a previous section that was interrupted by a
subsection.

This is not something that is usually encountered in rendered text (if at
all).

The reason it would be useful is that it allows tree transform operations
to have a better understanding of the structure of a document, and to adopt
their behavior on the "level" they reside at. The specific use-case for me
is the toctree directive in sphinx. It is not strange to have it as the
last directive on an RsT page:

Main heading
==========

Bla bla

Subheading
=========

Bla bla

Subsubheading
===========

Bla bla bla

.. toctree::


In this example, the toctree directive is processed at to lowest-level
subtree level in the parse tree:

<sec main><sec sub><sec subsub>TOCTREE</sec></sec></sec>

Whereas I would want to be able to achieve this:

<sec main><sec sub><sec subsub></sec></sec>TOCTREE</sec>

SoI want the toctree directive to be executed at a level of my choosing,
rather than at the level induced by its incidental place after an unknown
number of sub-heading levels.

There is a quite a bit of discussion about this on the sphinx side; the
current recommended practice is to either have subheadings in a page; or a
toctree; but not both. Which, frankly, is silly.

People are trying to solve this by patching up the 'toctree' semantics.
However, I feel the core of the problem is that the toctree directive
(especially at the end of the page) defaults to the last-active heading
level; I cannot currently have it there and associate it to a higher (most
often: the topmost) indentation level.

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

That's a presentation matter. It is conceivable to make a presentation
where the body texts at different levels have a different color, or
different indentation. In that case, having this ability would matter. But
that is pretty far fetched of course. It is not something that happens
(often, if at all) in typesetting.

Presentation isn't my main concern though. Having the ability for tree
transforms and directives to correctly known the sub-heading nesting
structure of a document seems useful enough, and that is hard to do now,
especially at the end of a document where the nesting level is just
whatever is active at the time.

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

The workaround does not do what I ask though; it introduces a new section;
it doesn't continue the previously open section.
Also, It introduces another heading (even if its text is empty) which I
don't want. I may be able to patch around that in HTML with CSS; but not in
other back-ends.

Now I may not be able to convince you that what I try to do is useful; but
I am still interested to find out if it is *possible*, eg with a custom
directive, and how I would go about that. Any pointers by you or anyone
else would be appreciated.

Best, Sidney






On Thu, May 27, 2021 at 3:53 AM David Goodger <[email protected]> wrote:

> 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 <[email protected]> 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
>> [email protected]
>> https://lists.sourceforge.net/lists/listinfo/docutils-users
>>
>> Please use "Reply All" to reply to the list.
>>
>