From: Guenter M. <mi...@us...> - 2021-06-18 09:40:56
|
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 |