#74 syntax for ending a section

[Ximin Luo]

In reST syntax currently sections and subsections are closed implicitly by the opening of the next section. This is fine for plain documents, but applications building on top of reST extend it with directives that might insert additional content. There is currently no syntax to tell reST that this directive belongs in a parent section instead of the current section. (You can create a new section at any level, but often the user wants the directive to belong to the existing parent section.)

See https://github.com/sphinx-doc/sphinx/issues/8518 for a concrete use-case.

[Günter Milde]

Ticket moved from /p/docutils/bugs/411/

Can't be converted:

• _milestone:

[Günter Milde]

While it bites at times, this restriction is not a bug but a feature it shares with printed text and markup formats like LaTeX.

In your use case, the first included file should start with a section heading of the same level as "Intro" or you should insert a heading for the "a/* pages" before the Sphinx ".. toctree::" directive.

[Ximin Luo]

This feature would be useful for LaTeX as well as a parsed-printed-text format that expands directives.

In my sphinx example, I do not want to have to artifically add extra sections, since that is not what I want the structure to be. Telling the user to do something different from what they originally want, is not a "feature", it's the absence of a feature. In particular, the autogenerated TOC entries in other parts of the output, will look weird and artificial, which it is.

I would like the structure to be:

• Chapter A
  ** Intro
  ** A/subpage 1
  ** A/subpage 2

where the subpage sections are generated automatically by the directive.

There is no syntax at the moment to do this, because there is no way to tell docutils the structure should be:

• Chapter A
  ** Intro
• (content inserted by directive, belonging to "Chapter A")

instead of:

• Chapter A
  ** Intro
  ** (content inserted by directive, belonging to "Intro")

What actually is the technical challenge in supporting this? It is possible in all other parsers that I can think of.

[engelbert gruber]

On Tue, 8 Dec 2020 at 06:01, Ximin Luo infinity0x@users.sourceforge.net
wrote:

This feature would be useful for LaTeX as well as a parsed-printed-text
format that expands directives.

In my sphinx example, I do not want to have to artifically add extra
sections, since that is not what I want the structure to be. Telling the
user to do something different from what they originally want, is not a
"feature", it's the absence of a feature. In particular, the autogenerated
TOC entries in other parts of the output, will look weird and artificial,
which it is.

I would like the structure to be:

• Chapter A

• Intro * A/subpage 1
  ** A/subpage 2

where the subpage sections are generated automatically by the directive.

There is no syntax at the moment to do this, because there is no way to
tell docutils the structure should be:

• Chapter A
  ** Intro
• (content inserted by directive, belonging to "Chapter A")

how would the display of the content change ?
how would the reader recognize "ahh i am back at chapter level" ?
maybe indentation, then "**Intro" is more of a quote or subdocument

is there a construct in typesetting (as there is none in LaTeX i assume
there isn't)
restructred text is a (to me) not a markup but a presentation format (it is
really close
to old RFC textformats) and typewriter letters, so how to present this
going up the toc-level

maybe use a tool like longtables in LaTeX, you have a table-head and a
table-head-continued and
a table-foot-tobecontinued and a table-foot,
table::

"col1" | "col2" | ...
rows | ...
"table continued on next page" <-- the table-foot for but the last one

-- page break
" continued from previous page"
"col1" | "col2" | ...
rows | ...
----------- <--- table end

assuming i write for a human reader i would put a line like "(end of
Intro)" or "(back to ...)" into the text
it helps understanding.

all the best

instead of:

• Chapter A

• Intro * (content inserted by directive, belonging to "Intro")

What actually is the technical challenge in supporting this? It is
possible in all other parsers that I can think of.

---

• [feature-requests:#74] syntax for ending a section*

Status: open
Group:
Created: Sun Dec 06, 2020 09:45 PM UTC by Ximin Luo
Last Updated: Mon Dec 07, 2020 02:24 PM UTC
Owner: nobody

In reST syntax currently sections and subsections are closed implicitly by
the opening of the next section. This is fine for plain documents, but
applications building on top of reST extend it with directives that might
insert additional content. There is currently no syntax to tell reST that
this directive belongs in a parent section instead of the current section.
(You can create a new section at any level, but often the user wants the
directive to belong to the existing parent section.)

See https://github.com/sphinx-doc/sphinx/issues/8518 for a concrete
use-case.

---

Sent from sourceforge.net because you indicated interest in
https://sourceforge.net/p/docutils/feature-requests/74/

To unsubscribe from further messages, please visit
https://sourceforge.net/auth/subscriptions/

[Günter Milde]

Thank you for the clarification. The special case you mention may be catered for.

RestructuredText has no generic markup construct for

Chapter A
==========
Intro
-----
something that belongs to Intro

Content that belongs to Chapter A but not to Intro and is not a section.

and the Docutils doctree specification defines:

Docutils section elements are a recursive structure;
a section may contain other section elements, without limit.
Paragraphs and other body elements may occur before a section, but not after it.

https://docutils.sourceforge.io/docs/ref/doctree.html#section

because this would not make sense in printed output --- there is no typographical convention to signify to the reader that a section is closed (other than starting the next section).

Your particular use case is a bit different:

I would like the structure to be:

 * Chapter A
 ** Intro
 **  A/subpage 1
 **  A/subpage 2

where the subpage sections are generated automatically by the directive.

Appending <section> nodes as children to the "Chapter A" <section> after the "Intro" <section> would generate a valid document tree.

As everything except a section header or a <section>-generating directive will
result in an invalid document tree, I do not support some a new syntax construct for ending a section.

Instead, the <section>-generating directive could define a directive option
that can be used to specify whether the generated <section> node should be nested in the current section (becoming a sub-section) or appended to the current section (becoming the next section of the same level).

This is something that must be handled by the downstream application (Sphinx or Sphinx extension) that defines this directive -- maybe via a pending node and a transform.

If there is no need to have "Intro" in the ToC, you may use an "abstract" or "topic" directive instead of a section for the Introduction.

[Ximin Luo]

As everything except a section header or a <section>-generating directive will
result in an invalid document tree, I do not support some a new syntax construct for ending a section.

Instead, the <section>-generating directive could define a directive option
that can be used to specify whether the generated <section> node should be nested in the current section (becoming a sub-section) or appended to the current section (becoming the next section of the same level).

Thanks for the detailed explanation! The validity rule makes sense now and I can understand why you don't wish to add this feature. I will pass this onto the sphinx developers in that ticket.