[Docutils-checkins] SF.net SVN: docutils:[10390] trunk/docutils

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

Revision: 10390
          http://sourceforge.net/p/docutils/code/10390
Author:   milde
Date:     2026-07-22 20:59:04 +0000 (Wed, 22 Jul 2026)
Log Message:
-----------
The `<footnote>` element's first child (`<label>`) is now mandatory.

The rST parser always only created footnotes with label.
The "doctree" element reference says
"The <footnote> element is used for labelled notes ...".

Modified Paths:
--------------
    trunk/docutils/HISTORY.rst
    trunk/docutils/RELEASE-NOTES.rst
    trunk/docutils/docs/ref/doctree.rst
    trunk/docutils/docs/ref/docutils.dtd
    trunk/docutils/docutils/nodes.py
    trunk/docutils/test/test_nodes.py

Modified: trunk/docutils/HISTORY.rst
===================================================================
--- trunk/docutils/HISTORY.rst	2026-07-21 17:55:03 UTC (rev 10389)
+++ trunk/docutils/HISTORY.rst	2026-07-22 20:59:04 UTC (rev 10390)
@@ -19,6 +19,7 @@
 
 * docs/ref/docutils.dtd
 
+  - The <footnote> element's first child (<label>) is now mandatory.
   - Use the ``%tbl.table.att`` parameter entity instead of ``%bodyatt``
     to customize the <table> element's attribute list.
 

Modified: trunk/docutils/RELEASE-NOTES.rst
===================================================================
--- trunk/docutils/RELEASE-NOTES.rst	2026-07-21 17:55:03 UTC (rev 10389)
+++ trunk/docutils/RELEASE-NOTES.rst	2026-07-22 20:59:04 UTC (rev 10390)
@@ -46,9 +46,6 @@
 Document Tree / Docutils DTD
 ----------------------------
 
-* The <footnote> element's first child (<label>) will become mandatory
-  in Docutils 1.0.
-
 * Inline `\<target>`_ elements and <target> elements with content will be
   deprecated in Docutils 1.0 and invalid in Docutils 2.0.
   The "rst" parser will use <inline> elements for inline targets
@@ -207,6 +204,7 @@
 
 Document Tree / Docutils DTD:
   - Drop the `name` attribute from <reference> nodes.
+  - The <footnote> element's first child (<label>) is now mandatory.
   - Use the ``%tbl.table.att`` parameter entity instead of ``%bodyatt``
     to customize the <table> element's attribute list in Docutils 1.0.
 

Modified: trunk/docutils/docs/ref/doctree.rst
===================================================================
--- trunk/docutils/docs/ref/doctree.rst	2026-07-21 17:55:03 UTC (rev 10389)
+++ trunk/docutils/docs/ref/doctree.rst	2026-07-22 20:59:04 UTC (rev 10390)
@@ -2049,14 +2049,14 @@
 :Parents:    all elements employing `%body.elements`_ or
              `%structure.model`_ in their content models
 
-:Children:   <footnote> elements begin with an optional [#]_ `\<label>`_
+:Children:   <footnote> elements begin with a `\<label>`_ [#]_
              and contain `body elements`_::
 
-                 (label?, (%body.elements;)+)
+                 (label, (%body.elements;)+)
 
 :Attributes: the `common attributes`_ plus auto_ and backrefs_.
 
-.. [#] The footnote label will become mandatory in Docutils 1.0.
+.. [#] The footnote label was optional in Docutils < 1.0.
 
 Examples
 --------

Modified: trunk/docutils/docs/ref/docutils.dtd
===================================================================
--- trunk/docutils/docs/ref/docutils.dtd	2026-07-21 17:55:03 UTC (rev 10389)
+++ trunk/docutils/docs/ref/docutils.dtd	2026-07-22 20:59:04 UTC (rev 10390)
@@ -515,7 +515,7 @@
 <!ELEMENT admonition (title, (%body.elements;)+)>
 <!ATTLIST admonition %basic.atts;>
 
-<!ELEMENT footnote (label?, (%body.elements;)+)>
+<!ELEMENT footnote (label, (%body.elements;)+)>
 <!ATTLIST footnote
     %basic.atts;
     %backrefs.att;

Modified: trunk/docutils/docutils/nodes.py
===================================================================
--- trunk/docutils/docutils/nodes.py	2026-07-21 17:55:03 UTC (rev 10389)
+++ trunk/docutils/docutils/nodes.py	2026-07-22 20:59:04 UTC (rev 10390)
@@ -2536,9 +2536,9 @@
 class footnote(General, BackLinkable, Element, Labeled, Targetable):
     """Labelled note providing additional context (footnote or endnote)."""
     valid_attributes: Final = Element.valid_attributes + ('auto', 'backrefs')
-    content_model: Final = ((label, '?'), (Body, '+'))
-    # (label?, (%body.elements;)+)
-    # The label will become required in Docutils 1.0.
+    content_model: Final = ((label, '.'), (Body, '+'))
+    # (label, (%body.elements;)+)
+    # The label was optional in Docutils < 1.0.
 
 
 class citation(General, BackLinkable, Element, Labeled, Targetable):

Modified: trunk/docutils/test/test_nodes.py
===================================================================
--- trunk/docutils/test/test_nodes.py	2026-07-21 17:55:03 UTC (rev 10389)
+++ trunk/docutils/test/test_nodes.py	2026-07-22 20:59:04 UTC (rev 10390)
@@ -766,15 +766,11 @@
         note.append(nodes.enumerated_list())
         self.assertEqual(note.validate_content(), [])
 
-        # footnote: (label?, (%body.elements;)+)
-        # TODO: use case for footnote without label (make it required?)
-        #       rST parser can generate footnotes without body elements!
-        footnote = nodes.footnote('', hint)
+        # footnote: (label, (%body.elements;)+)
+        footnote = nodes.footnote('', nodes.label('', '1'), hint)
         self.assertEqual(footnote.validate_content(), [])
 
         # citation: (label, (%body.elements;)+)
-        # TODO: rST parser allows empty citation
-        #       (see test_rst/test_citations.py). Is this sensible?
         citation = nodes.citation('', hint)
         with self.assertRaisesRegex(nodes.ValidationError,
                                     'Expecting child of type <label>,'

This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.