Re: closing a header block

Dear Sidney,

On 2021-05-27, Sidney Cadot wrote:

>> This is not only impossible (with standard rST syntax), it is also an
>> invalid Doctils document tree.
>> https://docutils.sourceforge.io/docs/ref/docutils.dtd
>> https://docutils.sourceforge.io/docs/ref/doctree.html#element-hierarchy

> Ok, that settles it. The restriction seems strange and somewhat arbitrary
> to my programmer's eye, but it is there alright.

With more input and searching in the Docutils sources, I have to correct
myself on both accounts. Details below.

> > >> 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?)

While your second example would be an invalid Docutils document, there
is no need to have a valid document tree before the parsing and
transformations are completed.

In other words, a transient document tree state like

    <document source="/tmp/simple.rst">
        <section ids="first-section" names="first\ section">
            <title>First section</title>
            <paragraph>First lorem ipsum</paragraph>
        </section>
     ← place next element here!

is not invalid per se. it depends on what would be the next element:

* if the next element is <section level="1"> or <section level="2">, fine.
  
* if the next element is *not* a <section> or a <section> with incompatible
  level (outside 1, ..., level_of_the_closed_section + 1), the final
  document tree is invalid.

> > >> 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?

This should be possible -- directives can do "anything" that is possible in
Python:

As a new section can close the preceding section, there must be a way to
do this programatically. The solution is described in the docstring for
docutils.parser.rst.states.check_subsection():
   
     Check for a valid subsection header.  Return 1 (true) or None (false).

     When a new section is reached that isn't a subsection of the current
     section, back up the line count (use ``previous_line(-x)``), then
     ``raise EOFError``.  The current StateMachine will finish, then the
     calling StateMachine can re-examine the title.  This will work its way
     back up the calling chain until the correct section level isreached.

     @@@ Alternative: Evaluate the title, store the title info & level, and
     back up the chain until that level is reached.  Store in memo? Or
     return in results?

     :Exception: `EOFError` when a sibling or supersection encountered.

It should be possible to "close" a section by a directive raising
`EOFError` and the following rST examples would generate valid documents::


   A section
   ---------
   
   .. close-section::
   
   Another section
   ---------------
   
as well as ::   

   A section
   ---------

   .. close-section::
   
   .. directive-that-generates-a-section-with-compatible-level::
   
OTOH, such a directive will certainly not become part of the Docutils,
because input like ::

   A section
   ---------
   
   Section content

   .. close-section::

   Anything other than the preceding examples.
   
would generate an invalid document.


Therfore, my suggestion would be to incorporate the closing into the 
"directive-that-generates-a-section-with-compatible-level", e.g. so that you
may write, e.g, ::

   A section
   ---------
   
   A subsection
   ~~~~~~~~~~~~

   Subsection content.
   
   .. directive-that-generates-a-section-with-compatible-level::
   
      :section-level: 1

   
Caveats:
  * This is not part of the API but an implementation detail that may
    change in future.
  * I did not test.
  * I don't know about side-effects.



> A similar request was filed to the issue tracker.
>> https://sourceforge.net/p/docutils/feature-requests/74
>> It turned out to be about an intermediate structure (adding sections by a
>> directive). In this case, the resulting doctree would be valid but telling
>> the section-adding-directive where to add these sections seems a better
>> solution than changing rST syntax or adding a section-closing directive in
>> Docutils.


> Yes, that seems very much related to what I was thinking about.

> As it turns out handling this stuff fully at the sphinx level has its own
> set of challenges. Especially the toctree stuff and how it interacts with
> the section headers seems quite badly designed I am sorry to say, to the
> point that the general recommendation seems to be: don't use them in the
> same document -- which is annoying (and hard to defend from a usability
> perspective). I had hoped that some alternative solution with help from the
> docutils level could be useful; but I guess this will need to be fully
> fixed at the sphinx level after all.

I am not familiar with the toctree and Sphinx extensions, so I cannot
recommend here besides the general adwise to balance the gain in usability
with added complexity.

I hope this helps a bit,

Günter



_______________________________________________
Docutils-users mailing list
[email protected]
https://lists.sourceforge.net/lists/listinfo/docutils-users

Please use "Reply All" to reply to the list.