[Docutils-develop] [docutils:bugs] Re: #511 Problems with nested parsing and sections.

assuming the included document. is complete, has a consistent title
hierarchy
  means first title-style is top, next is 2nd asf

standard use case is to include the document at a position where
it's top level is one below the current in the including document

e.g.

  section l1
  ==========

  section l2
  ----------

  .. included doc

    section l3
    ==========

    section l4
    ----------

  .. including doc

  section l2
  ----------

is there a use case for including and setting a different level, absolute
or relative ?


On Fri, 29 Aug 2025 at 23:25, Günter Milde <mi...@us...>
wrote:

> An alternative idea: nested parse uses the document-wide title style
> hierarchy if the "node" argument is left at its default value. The result
> of the nested parsing is directly added to the document (at the "current"
> node). Sections are appended according to their level.
>
> Attachments:
>
>    - 0001-Support-nested-parsing-with-document-wide-section-ti.patch
>    <https://sourceforge.net/p/docutils/bugs/_discuss/thread/4184882201/2af4/attachment/0001-Support-nested-parsing-with-document-wide-section-ti.patch>
>    (11.8 kB; text/x-patch)
>
> ------------------------------
>
> *[bugs:#511] <https://sourceforge.net/p/docutils/bugs/511/> Problems with
> nested parsing and sections.*
>
> *Status:* pending-remind
> *Created:* Tue Aug 26, 2025 10:13 AM UTC by Günter Milde
> *Last Updated:* Tue Aug 26, 2025 10:38 AM UTC
> *Owner:* nobody
> *Attachments:*
>
>    - old_nested_parsing.py
>    <https://sourceforge.net/p/docutils/bugs/511/attachment/old_nested_parsing.py>
>    (7.5 kB; text/x-python)
>
> In Docutils <= 0.22, parsing a nested content block with
> docutils.parsers.rst.state.RSTState.nested_parse() uses the document-wide
> "title style hierarchy".
>
> With Docutils <=0.21, this method can *loose complete sections* without
> warning when the match_titles argument is True and the nested content
> block contains sections with a title style that matches a lower section
> level than the current section level (try the attached test with a Docutils
> version below 0.22).
>
> Docutils itself does not use nested_parse() with match_titles True and
> did not test.
> However, the feature is used by Sphinx and several Sphinx extensions (cf.
> [bugs:#508] <https://sourceforge.net/p/docutils/bugs/508/>, [bugs#509],
> and https://github.com/sphinx-doc/sphinx/issues/13845).
>
> The new section parsing algorithm introduced in Docutils 0.22 fixes the
> data loss, but sections with a title style that matches a lower section
> level than the current section level are attached in wrong order: After the
> nested parsing is complete, the calling parser continues where it left of,
> messing the order of elements in the doctree (try the attached test with
> [r10204] <https://sourceforge.net/p/docutils/code/10204/>).
>
> This was fixed in [r10206]
> <https://sourceforge.net/p/docutils/code/10206/> at the expense of
> dropping support for document-wide title styles in nested parsing.
> As a result, the Sphinx "only" directive (which uses a new section style
> hierarchy with later re-attachment of the first section) now fails:
> https://github.com/sphinx-doc/sphinx/issues/13845#issuecomment-3209397215.
> ------------------------------
>
> Sent from sourceforge.net because you indicated interest in
> https://sourceforge.net/p/docutils/bugs/511/
>
> To unsubscribe from further messages, please visit
> https://sourceforge.net/auth/subscriptions/
>



---

**[bugs:#511] Problems with nested parsing and sections.**

**Status:** pending-remind
**Created:** Tue Aug 26, 2025 10:13 AM UTC by Günter Milde
**Last Updated:** Fri Aug 29, 2025 09:25 PM UTC
**Owner:** nobody
**Attachments:**

- [old_nested_parsing.py](https://sourceforge.net/p/docutils/bugs/511/attachment/old_nested_parsing.py) (7.5 kB; text/x-python)


In Docutils <= 0.22, parsing a nested content block with `docutils.parsers.rst.state.RSTState.nested_parse()` uses the document-wide "title style hierarchy".

With Docutils <=0.21, this method can **loose complete sections** without warning when the `match_titles` argument is True and the nested content block contains sections with a title style that matches a lower section level than the current section level (try the attached test with a Docutils version below 0.22).

Docutils itself does not use `nested_parse()` with `match_titles` True and did not test.
However, the feature is used by Sphinx and several Sphinx extensions (cf. [bugs:#508], [bugs#509], and  https://github.com/sphinx-doc/sphinx/issues/13845).

The new section parsing algorithm introduced in Docutils 0.22 fixes the data loss, but  sections with a title style that matches a lower section level than the current section level are attached in wrong order: After the nested parsing is complete, the calling parser continues where it left of, messing the order of elements in the doctree (try the attached test with [r10204]).

This was fixed in [r10206] at the expense of dropping support for document-wide title styles in nested parsing. 
As a result, the Sphinx "only" directive (which uses a new section style hierarchy with later re-attachment of the first section) now fails: https://github.com/sphinx-doc/sphinx/issues/13845#issuecomment-3209397215.


---

Sent from sourceforge.net because doc...@li... is subscribed to https://sourceforge.net/p/docutils/bugs/

To unsubscribe from further messages, a project admin can change settings at https://sourceforge.net/p/docutils/admin/bugs/options.  Or, if this is a mailing list, you can unsubscribe from the mailing list.