SF.net SVN: docutils:[10084 ] trunk/docutils

Revision: 10084
          http://sourceforge.net/p/docutils/code/10084
Author:   milde
Date:     2025-04-14 08:53:31 +0000 (Mon, 14 Apr 2025)
Log Message:
-----------
Fix content model of `<figure>` elements.

If an "image" or "figure" directive is used with the "target" option,
the image is nested in a `<reference>` element (to make it {U+201C}clickable{U+201D}).
Therefore, the first child element of a figure may be a `<reference>`
(with nested `<image>`).

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

Modified: trunk/docutils/HISTORY.rst
===================================================================
--- trunk/docutils/HISTORY.rst	2025-04-13 15:12:34 UTC (rev 10083)
+++ trunk/docutils/HISTORY.rst	2025-04-14 08:53:31 UTC (rev 10084)
@@ -33,6 +33,8 @@
 
   - Allow multiple <term> elements in a <definition_list_item>.
     Fixes feature-request #60
+  - The first element in a <figure> may also be a <reference>
+    (with nested "clickable" <image>).
 
 * docutils/core.py
 

Modified: trunk/docutils/RELEASE-NOTES.rst
===================================================================
--- trunk/docutils/RELEASE-NOTES.rst	2025-04-13 15:12:34 UTC (rev 10083)
+++ trunk/docutils/RELEASE-NOTES.rst	2025-04-14 08:53:31 UTC (rev 10084)
@@ -229,6 +229,8 @@
 Document Tree / Docutils DTD
   - Allow multiple <term> elements in a `\<definition_list_item>`__
     (third-party writers may need adaption).
+  - The first element in a <figure> may also be a <reference>
+    (with nested "clickable" <image>).
 
   __ docs/ref/doctree.html#definition-list-item
 
@@ -377,7 +379,7 @@
   - Use the same CSV format for the ``:header:`` option and the main data
     of the "csv-table_" directive.
 
-  - New option "loading" for the `"image" directive`_.
+  - New option "loading" for the "image_" directive.
     Sets the new attribute loading__ of the <image> doctree element.
 
   __ docs/ref/doctree.html#loading
@@ -443,7 +445,6 @@
 
 .. _input encoding: docs/api/publisher.html#encodings
 .. _csv-table: docs/ref/rst/directives.html#csv-table
-.. _"image" directive: docs/ref/rst/directives.html#image
 .. _root_prefix: docs/user/config.html#root-prefix
 .. _sources: docs/user/config.html#sources
 
@@ -820,7 +821,7 @@
 
 * docutils/docs/ref/docutils.dtd:
 
-  - Enable validation of Docutils XML documents against the DTD:
+  - Enable validation of Docutils XML documents against the DTD.
 
 * docutils/parsers/rst/:
 

Modified: trunk/docutils/docs/ref/docutils.dtd
===================================================================
--- trunk/docutils/docs/ref/docutils.dtd	2025-04-13 15:12:34 UTC (rev 10083)
+++ trunk/docutils/docs/ref/docutils.dtd	2025-04-14 08:53:31 UTC (rev 10084)
@@ -552,7 +552,7 @@
 <!ELEMENT pending EMPTY>
 <!ATTLIST pending %basic.atts;>
 
-<!ELEMENT figure (image, ((caption, legend?) | legend)) >
+<!ELEMENT figure ((image|reference), ((caption, legend?) | legend)) >
 <!ATTLIST figure
     %basic.atts;
     %align-h.att;

Modified: trunk/docutils/docutils/nodes.py
===================================================================
--- trunk/docutils/docutils/nodes.py	2025-04-13 15:12:34 UTC (rev 10083)
+++ trunk/docutils/docutils/nodes.py	2025-04-14 08:53:31 UTC (rev 10084)
@@ -561,7 +561,7 @@
                  '+' (one or more), '*' (zero or more).
 
     NOTE: The default describes the empty element. Derived classes should
-    update this value to match teir content model.
+    update this value to match their content model.
 
     Provisional.
     """
@@ -2135,6 +2135,11 @@
     # ((%body.elements;)+, attribution?)
 
 
+class reference(General, Inline, Referential, TextElement):
+    valid_attributes: Final = Element.valid_attributes + (
+        'anonymous', 'name', 'refid', 'refname', 'refuri')
+
+
 # Lists
 # -----
 #
@@ -2340,7 +2345,7 @@
 class figure(General, Element):
     """A formal figure, generally an illustration, with a title."""
     valid_attributes: Final = Element.valid_attributes + ('align', 'width')
-    content_model: Final = ((image, '.'),
+    content_model: Final = (((image, reference), '.'),
                             (caption, '?'),
                             (legend, '?'),
                             )
@@ -2568,11 +2573,6 @@
 class title_reference(Inline, TextElement): pass
 
 
-class reference(General, Inline, Referential, TextElement):
-    valid_attributes: Final = Element.valid_attributes + (
-        'anonymous', 'name', 'refid', 'refname', 'refuri')
-
-
 class footnote_reference(Inline, Referential, PureTextElement):
     valid_attributes: Final = Element.valid_attributes + (
         'auto', 'refid', 'refname')

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