docutils-develop

[Docutils-develop] [docutils:bugs] #489 Issues with the Docutils Doctree

[Günter M. <mi...@us...>]

---

**[bugs:#489] Issues with the Docutils Doctree**

**Status:** open
**Created:** Tue Jun 11, 2024 12:13 PM UTC by Günter Milde
**Last Updated:** Tue Jun 11, 2024 12:13 PM UTC
**Owner:** nobody


There are a number of discrepancies between the [Docutils Generic DTD][docutils.dtd]
and the implementation in Docutils code.

footnote
--------

[docutils.dtd][docutils.dtd]: `(label?, (%body.elements;)+)`
→ Label **optional**, content **required**; (not changed since 2002-04-20).

[reStructureText Markup Specification][rST spec]:
> 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](https://docutils.sourceforge.io/docutils/nodes.py) 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][docutils.dtd]: `(label, (%body.elements;)+)`
→ Label **required**, content **required**; (not changed since 2002-04-20).

[reStructureText Markup Specification][rST spec]:
> 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][docutils.dtd]: `(image, ((caption, legend?) | legend))`
→ caption or legend **required**; (not changed since 2002-04-20).

[reStructuredText Directives](https://docutils.sourceforge.io/docs/ref/rst/directives.html#figure)

> 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?

[docutils.dtd]: https://docutils.sourceforge.io/docs/ref/docutils.dtd
[rST spec]: https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html



---

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.

[Docutils-develop] Waiting for feedback about issues with the Docutils Doctree [#489]

[Guenter M. <mi...@us...>]

Dear Docutils Developers,

I still hope to get some feedback on what to do with the discrepancies of

* user documentation
* Docutils Generic Document Type Description (docutils.dtd), and
* "rst" parser behaviour.


Footnotes and Citations
  may be specified **without content** in rST without the parser complaining.
  
  According to documentation and docutils.dtd content is required.
  
  → Is there any use-case for empty footnotes or citations?
  
Footnote label
  is optional according to docutils.dtd
  
  According to user documentation, a label is required. 
  The "rst" parser requires a label, too.

  → Is there any use-case for a footnote without label?


Figures
  require a caption or legend according to docutils.dtd.

  The "rst" parser and the documentation allow figures without caption or
  legend.

  → OK to Allow figures without caption/legend in the Docutils Generic DTD?


See also https://sourceforge.net/p/docutils/bugs/489/


Günter

Re: [Docutils-develop] Waiting for feedback about issues with the Docutils Doctree [#489]

[Alan <ala...@gm...>]

Since I have not seen any developer feedback,
here is some user feedback.

- citations without content: I've never seen it
- footnotes without content or without "label": I've never seen it
- figures without caption/legend: no "legend" is reasonably common, but no
caption is extremely rare and is a need met by `image` (I believe)

Cheers, Alan Isaac



On Mon, Jun 17, 2024 at 12:45 PM Guenter Milde via Docutils-develop <
doc...@li...> wrote:

> Dear Docutils Developers,
>
> I still hope to get some feedback on what to do with the discrepancies of
>
> * user documentation
> * Docutils Generic Document Type Description (docutils.dtd), and
> * "rst" parser behaviour.
>
>
> Footnotes and Citations
>   may be specified **without content** in rST without the parser
> complaining.
>
>   According to documentation and docutils.dtd content is required.
>
>   → Is there any use-case for empty footnotes or citations?
>
> Footnote label
>   is optional according to docutils.dtd
>
>   According to user documentation, a label is required.
>   The "rst" parser requires a label, too.
>
>   → Is there any use-case for a footnote without label?
>
>
> Figures
>   require a caption or legend according to docutils.dtd.
>
>   The "rst" parser and the documentation allow figures without caption or
>   legend.
>
>   → OK to Allow figures without caption/legend in the Docutils Generic DTD?
>
>
> See also https://sourceforge.net/p/docutils/bugs/489/
>
>
> Günter
>
>
>
> _______________________________________________
> Docutils-develop mailing list
> Doc...@li...
> https://lists.sourceforge.net/lists/listinfo/docutils-develop
>
> Please use "Reply All" to reply to the list.
>

Re: [Docutils-develop] Waiting for feedback about issues with the Docutils Doctree [#489]

[Karl O. P. <ko...@ka...>]

On Thu, 20 Jun 2024 13:22:31 -0400
Alan <ala...@gm...> wrote:

> Since I have not seen any developer feedback,
> here is some user feedback.
> 
> - citations without content: I've never seen it
> - footnotes without content or without "label": I've never seen it
> - figures without caption/legend: no "legend" is reasonably common,
> but no caption is extremely rare and is a need met by `image` (I
> believe)

Figures with no caption would still show up in the TOCs list
of figures.  (Or where ever that list shows up.) At least
in docbook.  I think.  Although I don't know how useful that'd
be since no description would be listed.  I suppose it'd have a figure
number, which is not entirely useless.

Further, I've not tried it and didn't go to the DTD or the
specs and actually look.  So take all this with a big
grain of salt.

Anyway, the big difference between figures and images,
in my mind, is that figures tend to appear in some sort
of listing somewhere and images don't.

Regards,

Karl <ko...@ka...>
Free Software:  "You don't pay back, you pay forward."
                 -- Robert A. Heinlein

Re: [Docutils-develop] Waiting for feedback about issues with the Docutils Doctree [#489]

[Guenter M. <mi...@us...>]

Dear Alan, Karl, and Docutils developers,

On 2024-06-20, Karl O. Pinc wrote:
> On Thu, 20 Jun 2024 Alan <ala...@gm...> wrote:

Thanks for the feedback.

It seems there is an emerging consensus regarding footnotes and citations.

Changing the "document tree" description (docutils.dtd) will not prevent
the creation of footnotes/labels without label or content.
The only immediately visibly change for users would be that

   docutils --validate a-document-with-faulty-footnote.rst
   
would generate an "invalid element" warning. 
  Also, it would make clear that there is no longer a guarantee that these
constructs work with Docutils. (We may remove some test cases.)

Developers of writers or plug-ins would gain from a simpler and consistent
documentation. Their task becomes easier, as they do no longer have to make
sure the new component supports footnotes/citations without label or content.
(In the long term, this may also lead to missing support for these
constructs in the Docutils writers.)

>> - citations without content: I've never seen it
>> - footnotes without content or without "label": I've never seen it


Which leaves figures:

>> - figures without caption/legend: no "legend" is reasonably common,
>>   but no caption is extremely rare and is a need met by `image` (I
>>   believe)

> Figures with no caption would still show up in the TOCs list
> of figures.  (Or whereever that list shows up.) At least
> in docbook.  I think.  Although I don't know how useful that'd
> be since no description would be listed.  I suppose it'd have a figure
> number, which is not entirely useless.
...
> Anyway, the big difference between figures and images,
> in my mind, is that figures tend to appear in some sort
> of listing somewhere and images don't.

Also, figures tend to "flow" to a suitable position in page-based media.

Let's have a look at the current behaviour with various writers:

Input::

  .. image:: docs/user/images/default.png

  .. figure:: docs/user/images/default.png

HTML5 
  just uses a <figure> wrapper (like XML and pseudoXML)::

    <img alt="docs/user/images/default.png" src="docs/user/images/default.png" />
    <figure>
    <img alt="docs/user/images/default.png" src="docs/user/images/default.png" />
    </figure>

  The effect depends on CSS styling: a <figure> may float or get a figure
  number. With the default styles, a figure is set with wider margins on
  both sides. The figure number (cf. `numbered figures`__) is only shown
  if there is a caption but this is an CSS implementation detail.

  __ https://docutils.sourceforge.io/test/functional/expected/standalone_rst_html5.html#numbered-figures)
  
LaTeX
  wraps a figure in a figure float and centre-aligns it::
  
    \includegraphics{docs/user/images/default.png}

    \begin{figure}
    \noindent\makebox[\linewidth][c]{\includegraphics{docs/user/images/default.png}}\end{figure}

  As a result, a figure will usually move to a suitable place on the top of
  a page. 

  However, a figure without caption does not get a figure number and is not
  included in the List of Figures.¹
  
  ¹ A list of figures is not supported by Docutils but can be inserted
    with raw LaTeX. 
  
ODT
  uses a figure frame with empty caption field for the figure.

  However, a figure without caption will not get a figure number and not
  be listed in the List of Figures.¹
  
  ¹ A list of figures is not supported by Docutils but can be inserted
    in the LibreOfficeWriter.

A use case would be an illustration with the caption already included in
the image file, that should flow in LaTeX and/or use a consistent CSS
figure-layout in HTML.

It seems a rare case and support is patchy, so it is, IMO, 
be OK if validation issues a warning. 

* Should the rST user documentation 
  https://docutils.sourceforge.io/docs/ref/rst/directives.html#figure
  be updated/expanded to warn that missing both caption and legend results
  in an invalid <figure> element (suggestions on how to formulate this are
  welcome)?
  
* Should the rST parser report a warning or an error in addition to the
  warning with "--validate"?  

Günter

[Docutils-develop] [docutils:bugs] #489 Issues with the Docutils Doctree

[Günter M. <mi...@us...>]

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 labels.

TODO: allow figures without caption/legend?


---

**[bugs:#489] Issues with the Docutils Doctree**

**Status:** open
**Created:** Tue Jun 11, 2024 12:13 PM UTC by Günter Milde
**Last Updated:** Tue Jun 11, 2024 12:13 PM UTC
**Owner:** nobody


There are a number of discrepancies between the [Docutils Generic DTD][docutils.dtd]
and the implementation in Docutils code.

footnote
--------

[docutils.dtd][docutils.dtd]: `(label?, (%body.elements;)+)`
→ Label **optional**, content **required**; (not changed since 2002-04-20).

[reStructureText Markup Specification][rST spec]:
> 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](https://docutils.sourceforge.io/docutils/nodes.py) 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][docutils.dtd]: `(label, (%body.elements;)+)`
→ Label **required**, content **required**; (not changed since 2002-04-20).

[reStructureText Markup Specification][rST spec]:
> 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][docutils.dtd]: `(image, ((caption, legend?) | legend))`
→ caption or legend **required**; (not changed since 2002-04-20).

[reStructuredText Directives](https://docutils.sourceforge.io/docs/ref/rst/directives.html#figure)

> 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?

[docutils.dtd]: https://docutils.sourceforge.io/docs/ref/docutils.dtd
[rST spec]: https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html



---

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.

[Docutils-develop] [docutils:bugs] #489 Issues with the Docutils Doctree

[Günter M. <mi...@us...>]

- **status**: open --> closed-fixed
- **Comment**:

All open decisions are solved. 
Backwards-incompatible changes are announced and will be implemented over the next releases.



---

**[bugs:#489] Issues with the Docutils Doctree**

**Status:** closed-fixed
**Created:** Tue Jun 11, 2024 12:13 PM UTC by Günter Milde
**Last Updated:** Sun Jul 28, 2024 10:52 AM UTC
**Owner:** nobody


There are a number of discrepancies between the [Docutils Generic DTD][docutils.dtd]
and the implementation in Docutils code.

footnote
--------

[docutils.dtd][docutils.dtd]: `(label?, (%body.elements;)+)`
→ Label **optional**, content **required**; (not changed since 2002-04-20).

[reStructureText Markup Specification][rST spec]:
> 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](https://docutils.sourceforge.io/docutils/nodes.py) 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][docutils.dtd]: `(label, (%body.elements;)+)`
→ Label **required**, content **required**; (not changed since 2002-04-20).

[reStructureText Markup Specification][rST spec]:
> 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][docutils.dtd]: `(image, ((caption, legend?) | legend))`
→ caption or legend **required**; (not changed since 2002-04-20).

[reStructuredText Directives](https://docutils.sourceforge.io/docs/ref/rst/directives.html#figure)

> 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?

[docutils.dtd]: https://docutils.sourceforge.io/docs/ref/docutils.dtd
[rST spec]: https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html



---

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.

[Docutils-develop] [docutils:bugs] #489 Issues with the Docutils Doctree

[Günter M. <mi...@us...>]

- **status**: closed-fixed --> open
- Attachments has changed:

Diff:

~~~~

--- old
+++ new
@@ -0,0 +1 @@
+0001-Doctree-amendment-System-messages-can-appear-in-plac.patch (5.5 kB; text/x-patch)

~~~~

- **Comment**:

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.py`` contains
a 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.






---

**[bugs:#489] Issues with the Docutils Doctree**

**Status:** open
**Created:** Tue Jun 11, 2024 12:13 PM UTC by Günter Milde
**Last Updated:** Mon Nov 18, 2024 12:58 PM UTC
**Owner:** nobody
**Attachments:**

- [0001-Doctree-amendment-System-messages-can-appear-in-plac.patch](https://sourceforge.net/p/docutils/bugs/489/attachment/0001-Doctree-amendment-System-messages-can-appear-in-plac.patch) (5.5 kB; text/x-patch)


There are a number of discrepancies between the [Docutils Generic DTD][docutils.dtd]
and the implementation in Docutils code.

footnote
--------

[docutils.dtd][docutils.dtd]: `(label?, (%body.elements;)+)`
→ Label **optional**, content **required**; (not changed since 2002-04-20).

[reStructureText Markup Specification][rST spec]:
> 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](https://docutils.sourceforge.io/docutils/nodes.py) 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][docutils.dtd]: `(label, (%body.elements;)+)`
→ Label **required**, content **required**; (not changed since 2002-04-20).

[reStructureText Markup Specification][rST spec]:
> 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][docutils.dtd]: `(image, ((caption, legend?) | legend))`
→ caption or legend **required**; (not changed since 2002-04-20).

[reStructuredText Directives](https://docutils.sourceforge.io/docs/ref/rst/directives.html#figure)

> 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?

[docutils.dtd]: https://docutils.sourceforge.io/docs/ref/docutils.dtd
[rST spec]: https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html



---

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.

[Docutils-develop] [docutils:bugs] Re: #489 Issues with the Docutils Doctree

[Günter M. <mi...@us...>]

It turns out to be a rST parser problem affecting all elements supporting the "text model" (i.e accepting text and inline elements but no body elements) like `<field_name>` and `<rubric>`. 
As a consequence, the HTML writers generate invalid HTML for, e.g., a rubric with a :name: option value that is a duplicate of another external reference target.

The test case was added in [r7638] in response to [bugs:#157]. However, the commit fixed the a symptom, not the cause.



---

**[bugs:#489] Issues with the Docutils Doctree**

**Status:** open
**Created:** Tue Jun 11, 2024 12:13 PM UTC by Günter Milde
**Last Updated:** Wed Apr 23, 2025 10:49 AM UTC
**Owner:** nobody
**Attachments:**

- [0001-Doctree-amendment-System-messages-can-appear-in-plac.patch](https://sourceforge.net/p/docutils/bugs/489/attachment/0001-Doctree-amendment-System-messages-can-appear-in-plac.patch) (5.5 kB; text/x-patch)


There are a number of discrepancies between the [Docutils Generic DTD][docutils.dtd]
and the implementation in Docutils code.

footnote
--------

[docutils.dtd][docutils.dtd]: `(label?, (%body.elements;)+)`
→ Label **optional**, content **required**; (not changed since 2002-04-20).

[reStructureText Markup Specification][rST spec]:
> 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](https://docutils.sourceforge.io/docutils/nodes.py) 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][docutils.dtd]: `(label, (%body.elements;)+)`
→ Label **required**, content **required**; (not changed since 2002-04-20).

[reStructureText Markup Specification][rST spec]:
> 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][docutils.dtd]: `(image, ((caption, legend?) | legend))`
→ caption or legend **required**; (not changed since 2002-04-20).

[reStructuredText Directives](https://docutils.sourceforge.io/docs/ref/rst/directives.html#figure)

> 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?

[docutils.dtd]: https://docutils.sourceforge.io/docs/ref/docutils.dtd
[rST spec]: https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html



---

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.

[Docutils-develop] [docutils:bugs] #489 Issues with the Docutils Doctree

[Günter M. <mi...@us...>]

- **status**: open --> open-fixed
- **Comment**:

Fixed in [r10104].



---

**[bugs:#489] Issues with the Docutils Doctree**

**Status:** open-fixed
**Created:** Tue Jun 11, 2024 12:13 PM UTC by Günter Milde
**Last Updated:** Fri Apr 25, 2025 10:50 AM UTC
**Owner:** nobody
**Attachments:**

- [0001-Doctree-amendment-System-messages-can-appear-in-plac.patch](https://sourceforge.net/p/docutils/bugs/489/attachment/0001-Doctree-amendment-System-messages-can-appear-in-plac.patch) (5.5 kB; text/x-patch)


There are a number of discrepancies between the [Docutils Generic DTD][docutils.dtd]
and the implementation in Docutils code.

footnote
--------

[docutils.dtd][docutils.dtd]: `(label?, (%body.elements;)+)`
→ Label **optional**, content **required**; (not changed since 2002-04-20).

[reStructureText Markup Specification][rST spec]:
> 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](https://docutils.sourceforge.io/docutils/nodes.py) 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][docutils.dtd]: `(label, (%body.elements;)+)`
→ Label **required**, content **required**; (not changed since 2002-04-20).

[reStructureText Markup Specification][rST spec]:
> 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][docutils.dtd]: `(image, ((caption, legend?) | legend))`
→ caption or legend **required**; (not changed since 2002-04-20).

[reStructuredText Directives](https://docutils.sourceforge.io/docs/ref/rst/directives.html#figure)

> 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?

[docutils.dtd]: https://docutils.sourceforge.io/docs/ref/docutils.dtd
[rST spec]: https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html



---

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.

[Docutils-develop] [docutils:bugs] #489 Issues with the Docutils Doctree

[Günter M. <mi...@us...>]

- **status**: open-fixed --> closed-fixed
- **Comment**:

The bug is fixed in Docutils 0.22 released 2025-07-29.




---

**[bugs:#489] Issues with the Docutils Doctree**

**Status:** closed-fixed
**Created:** Tue Jun 11, 2024 12:13 PM UTC by Günter Milde
**Last Updated:** Fri Apr 25, 2025 01:15 PM UTC
**Owner:** nobody
**Attachments:**

- [0001-Doctree-amendment-System-messages-can-appear-in-plac.patch](https://sourceforge.net/p/docutils/bugs/489/attachment/0001-Doctree-amendment-System-messages-can-appear-in-plac.patch) (5.5 kB; text/x-patch)


There are a number of discrepancies between the [Docutils Generic DTD][docutils.dtd]
and the implementation in Docutils code.

footnote
--------

[docutils.dtd][docutils.dtd]: `(label?, (%body.elements;)+)`
→ Label **optional**, content **required**; (not changed since 2002-04-20).

[reStructureText Markup Specification][rST spec]:
> 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](https://docutils.sourceforge.io/docutils/nodes.py) 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][docutils.dtd]: `(label, (%body.elements;)+)`
→ Label **required**, content **required**; (not changed since 2002-04-20).

[reStructureText Markup Specification][rST spec]:
> 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][docutils.dtd]: `(image, ((caption, legend?) | legend))`
→ caption or legend **required**; (not changed since 2002-04-20).

[reStructuredText Directives](https://docutils.sourceforge.io/docs/ref/rst/directives.html#figure)

> 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?

[docutils.dtd]: https://docutils.sourceforge.io/docs/ref/docutils.dtd
[rST spec]: https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html



---

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.