#489 Issues with the Docutils Doctree
There are a number of discrepancies between the Docutils Generic DTD
and the implementation in Docutils code.
footnote
docutils.dtd: (label?, (%body.elements;)+)
→ Label optional, content required; (not changed since 2002-04-20).
reStructureText Markup Specification:
Each footnote consists of an explicit markup start (".. "), a left
square bracket, the footnote label, a right square bracket, and
whitespace, followed by indented body elements.
The footnote class in docutils.nodes is a subclass of Labeled,
whose docstring says: "Contains a label as its first element."
The rST parser requires a label but allows empty footnotes
(cf. test/test_writers/test_latex2e.py).
citation
docutils.dtd: (label, (%body.elements;)+)
→ Label required, content required; (not changed since 2002-04-20).
reStructureText Markup Specification:
Citations are identical to footnotes except that they use only
non-numeric labels …
The rST parser allows empty citations (cf. test_rst/test_citations.py).
figure
docutils.dtd: (image, ((caption, legend?) | legend))
→ caption or legend required; (not changed since 2002-04-20).
A "figure" consists of image data (including image options), an optional
caption (a single paragraph), and an optional legend (arbitrary body
elements). For page-based output media, figures might float to a different
position if this helps the page layout.
The rST parser allows figures without caption or legend.
Docutils HTML and LaTeX writers use a different layout for figures vs.
images. They can handle figures without caption/legend.
Suggestion
- Make footnote label compulsory`.
- Let rST report a warning for empty footnote and citation.
Remove tests with empty footnote and citation. - Allow figures without caption/legend in the Docutils Generic DTD.
(Change in Docutils 1.0, announce in 0.22.)
Questions
Are there a use cases for
* footnotes without label,
* footnotes without content,
* citations without content?
Commit [r9780] announces the change to mandatory labels for footnote and label in Docutils 1.0.
Commit [r9781] implements a rST parser warning for empty footnotes and citations.
The rST parser will warn before figures with no caption nor legend [r9984]
Related
Commit: [r9780]
Commit: [r9781]
Commit: [r9984]
Last edit: Günter Milde 2024-11-18
All open decisions are solved.
Backwards-incompatible changes are announced and will be implemented over the next releases.
Diff:
A new problem: System messages in
<line_block>s.According to the Docutils Generic DTD,
<line_block>s may contain<line>s and nested<line_block>s, nothing else.The file
test/test_parsers/test_rst/test_line_blocks.pycontainsa test case stating that "System messages can appear in place of lines."
This is also the current behaviour of the rST parser.
To solve this discrepancy, there are two alternatives:
a) Change the DTD and the Document Tree documentation to add this special case. The attached patch implements this approach
+1 simpler to implement
-1 more complex rules for the "Docutils Document Model" (Doctree).
b) Change the rST parser to place system messages after
<line_block>elements.+1 simpler "Docutils Document Model"
-1 change in rST parser behaviour.
The test case was added in [r7638] in response to [bugs:#157] which fixed the reported symptom but not the cause -- the generation of an invalid doctree.
It turns out to be a rST parser problem affecting all elements supporting phrasing content, e.g.,
<field_name>and<rubric>.One consequence is the generation of invalid HTML for, e.g., a rubric with a :name: option value that is a duplicate of another external reference target. This would not be solved by approach a).
Related
Bugs:
#157Commit: [r7638]
Last edit: Günter Milde 2 days ago
Fixed in [r10104].
Related
Commit: [r10104]