Menu

#60 Allow definition_list_item to have multiple terms

Default
open-fixed
nobody
None
5
2024-08-31
2019-01-03
No

In HTML spec, definition list accepts multiple terms in a item. This patch allows doctree model to have multiple terms as children of definition_list_item also.
https://www.w3.org/TR/html52/grouping-content.html#the-dl-element

In sphinx, a custom directive named "glossary" allows multiple terms for one definition_list_item.
https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#glossary

1 Attachments

Related

Patches: #95

Discussion

  • Günter Milde

    Günter Milde - 2021-11-12

    Do you mean:

    --- a/docutils/docs/ref/docutils.dtd
    +++ b/docutils/docs/ref/docutils.dtd
    @@ -397,7 +397,7 @@ Eventual replacement for docinfo? -->
     <!ELEMENT definition_list (definition_list_item+)>
     <!ATTLIST definition_list %basic.atts;>
    
    -<!ELEMENT definition_list_item (term, classifier*, definition)>
    +<!ELEMENT definition_list_item (term+, classifier*, definition)>
     <!ATTLIST definition_list_item %basic.atts;>
    
     <!ELEMENT term %text.model;>
    

    (plus the matching change in docs/ref/doctree.txt) ?

    We would need to check, that all writers can handle the case

    <definition_list>
        <definition_list_item>
            <term>term 1</term>
            <term>term 2</term>
            <definition>
                <paragraph>Definition of both terms.</paragraph>
            </definition>
        </definition_list_item>
    </definition_list>
    

    No problem for HTML5, XML, pseudoXML, ODT, and LaTeX.

    Currently fails with "html5" writer, the "html4" writer produces invalid output (missing </dt>). The "manpage" writer does not fail, however the second term becomes part of the common definition (at least visibly) in the man output.

    If implemented, this could be coupled with an input convention with empty comment:

    term 1
        ..
    term 2
       Definition of both terms.
    
     

    Last edit: Günter Milde 2023-12-12
  • Günter Milde

    Günter Milde - 2023-12-12

    A test script to generate output with a "hand-crafted" document tree with extra term in a definition list.

    Currently fails with "html5" writer, the "html4" writer produces invalid output (missing </dt>). The "manpage" writer does not fail, however the second term becomes part of the common definition (at least visibly) in the man output.
    LaTeX needs a bit of adaption, too.
    This may also break 3rd-party writers like the PDF (reportlab) writer from rst2pdf or the various Sphinx writers.

     

    Last edit: Günter Milde 2023-12-12
  • Günter Milde

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

    Günter Milde - 2024-06-07

    Commit [r9747] changes the DTD, documentation, and nodes.definition_list_item.content_model to allow multiple terms for one definition.

     

    Related

    Commit: [r9747]

  • Günter Milde

    Günter Milde - 2024-08-31

    A possible syntax for reStructuredText input of multi-term definition lists is proposed in [patches:#95].

     

    Related

    Patches: #95


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.
OSZAR »