Menu

#94 Should docutils whine about nesting simple body elements?

Default
open-fixed
nobody
None
5
2024-06-06
2023-02-09
No

Context:

This call to nested_parse adds a Paragraph node to a Paragraph node, this look forbidden by the doc, and it also look to misbehave sphinx-side, when translating the document, where we completly loose the nested paragraph once translated.

It renders properly though when not translated.

The linked nested_parse returns:

<paragraph classes="availability">
    <pending_xref refdoc="index" refdomain="std" refexplicit="True" reftarget="availability" reftype="ref" refwarn="True">
        <inline classes="xref std std-ref">
            Availability
    : 
    Unix, not Emscripten, not WASI.
    <paragraph>
        Hello world I'm the content of the "availability" directive.

If it's really something that should not be done, maybe some kind of warning at build time could help debugging those issues?

Discussion

  • Günter Milde

    Günter Milde - 2023-04-06

    Nesting paragraphs in paragraphs is indeed a violation of the Docutils document model docutils.dtd.
    Unfortunately, this is just one example of an "infinite" number of ways you can build invalid documents -- testing for all sorts of violations by custom code may seriously affect performance.

    You may consider exporting a test document to XML and test for validity against the docutils.dtd.

     
  • Günter Milde

    Günter Milde - 2023-04-18

    Ticket moved from /p/docutils/bugs/466/

     
  • Günter Milde

    Günter Milde - 2023-05-11

    Unfortunately, this is just one example of an "infinite" number of ways you can build invalid documents -- testing for all sorts of violations by custom code may seriously affect performance.

    However, a transform testing for conformance could be sensible. It may walk over the document tree and for each node check that the parent node is an instance of the well-defined, small set of allowed parent nodes.
    Ideas and patches are welcome.

     
  • Günter Milde

    Günter Milde - 2024-06-06
    • status: open --> open-fixed
    • Group: --> Default
     
  • Günter Milde

    Günter Milde - 2024-06-06

    In Docutils 0.22 (since [r9732]), you can validate a Document Tree element (nodes.Element instance) and its children by calling its validate() method.
    There is also a "transform" that checks a complete document after parsing and reports validation problems as WARNING system messages. It can be activated with the validate configuration setting.

    The new "xml" parser validates the parsing result by default, so if you save the source

    <paragraph classes="availability">
        <inline classes="xref std std-ref">Availability:</inline>
        Unix, not WASI.
        <paragraph>Content of the "availability" directive.</paragraph>
    </paragraph>
    

    to a file foo.xml, say, and run

    docutils --parser=xml --writer=pseudoxml foo.xml
    

    the result is

    <document source="/tmp/foo.xml">
        <paragraph classes="availability">
    
            <inline classes="xref std std-ref">
                Availability:
    
            Unix, not WASI.
            <paragraph>
                Content of the "availability" directive.
    
        <section classes="system-messages">
            <title>
                Docutils System Messages
            <system_message level="2" line="4" source="/tmp/foo.xml" type="WARNING">
                <paragraph>
                    Element <paragraph classes="availability"> invalid:
                      Child element <paragraph> not allowed at this position.
    

    The original example would also complain about the unknown node <pending_xref> as this is an extension by Sphinx.

     

    Related

    Commit: [r9732]


Log in to post a comment.

Want the latest updates on software, tech news, and AI?
Get latest updates about software, tech news, and AI from SourceForge directly in your inbox once a month.