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

Revision: 10371
          http://sourceforge.net/p/docutils/code/10371
Author:   milde
Date:     2026-06-23 17:20:41 +0000 (Tue, 23 Jun 2026)
Log Message:
-----------
HTML5 writer: More robust handling of figure captions.

The content models of "figure" elements in the Doctree and HTML differ, so
we cannot easily map a `<caption>` to a `<figcaption>`.
Use the same conditions for opening and closing tag of a HTML `<figcaption>`
element, so that the tags are balanced also in case of invalid `<figure>`
child elements (e.g. a `<system-message>`).
(cf. https://docutils.sourceforge.io/docs/ref/doctree.html#caption,
https://html.spec.whatwg.org/multipage/grouping-content.html#the-figcaption-element)

Modified Paths:
--------------
    trunk/docutils/HISTORY.rst
    trunk/docutils/docutils/writers/html5_polyglot/__init__.py

Modified: trunk/docutils/HISTORY.rst
===================================================================
--- trunk/docutils/HISTORY.rst	2026-06-23 14:59:27 UTC (rev 10370)
+++ trunk/docutils/HISTORY.rst	2026-06-23 17:20:41 UTC (rev 10371)
@@ -121,6 +121,7 @@
   - Use more specific CSS selectors for styling <aside> elements to avoid
     problems with other elements using "topic" as class value, e.g. a docinfo
     item "topic" in Enhancement Reports.
+  - More robust handling of figure captions.
 
 * docutils/writers/latex2e/__init__.py
 

Modified: trunk/docutils/docutils/writers/html5_polyglot/__init__.py
===================================================================
--- trunk/docutils/docutils/writers/html5_polyglot/__init__.py	2026-06-23 14:59:27 UTC (rev 10370)
+++ trunk/docutils/docutils/writers/html5_polyglot/__init__.py	2026-06-23 17:20:41 UTC (rev 10371)
@@ -151,9 +151,10 @@
     def depart_authors(self, node) -> None:
         self.depart_docinfo_item()
 
-    # use the <figcaption> semantic tag.
+    # Wrap in a <figcaption> semantic tag (together with optional <legend>).
     def visit_caption(self, node) -> None:
-        if isinstance(node.parent, nodes.figure):
+        if isinstance(node.parent, nodes.figure
+                      ) and node.parent.children.index(node) == 1:
             self.body.append(self.starttag(node, 'figcaption'))
         self.body.append('<p>')
 
@@ -211,7 +212,9 @@
         self.body.append(self.starttag(node, 'figure', **atts))
 
     def depart_figure(self, node) -> None:
-        if len(node) > 1:
+        # <caption> and <legend> in position 1 start a <figcaption>
+        if len(node) > 1 and isinstance(node.children[1],
+                                        (nodes.caption, nodes.legend)):
             self.body.append('</figcaption>\n')
         self.body.append('</figure>\n')
 
@@ -279,7 +282,7 @@
 
     # place inside HTML5 <figcaption> element (together with caption)
     def visit_legend(self, node) -> None:
-        if not isinstance(node.previous_sibling(), nodes.caption):
+        if node.parent.children.index(node) == 1:
             self.body.append('<figcaption>\n')
         self.body.append(self.starttag(node, 'div', CLASS='legend'))
 

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