Menu
▾
▴
docutils-checkins — SVN checkin messages, auto-generated.
You can subscribe to this list here.
| 2002 |
Jan
|
Feb
|
Mar
|
Apr
(106) |
May
(215) |
Jun
(104) |
Jul
(290) |
Aug
(351) |
Sep
(245) |
Oct
(289) |
Nov
(184) |
Dec
(113) |
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 2003 |
Jan
(179) |
Feb
(88) |
Mar
(77) |
Apr
(70) |
May
(107) |
Jun
(288) |
Jul
(115) |
Aug
(67) |
Sep
(91) |
Oct
(34) |
Nov
(31) |
Dec
(61) |
| 2004 |
Jan
(54) |
Feb
(17) |
Mar
(102) |
Apr
(152) |
May
(178) |
Jun
(377) |
Jul
(136) |
Aug
(37) |
Sep
(196) |
Oct
(142) |
Nov
(119) |
Dec
(58) |
| 2005 |
Jan
(51) |
Feb
(76) |
Mar
(220) |
Apr
(132) |
May
(134) |
Jun
(230) |
Jul
(142) |
Aug
(58) |
Sep
(71) |
Oct
(76) |
Nov
(129) |
Dec
(117) |
| 2006 |
Jan
(94) |
Feb
(30) |
Mar
(97) |
Apr
(63) |
May
(63) |
Jun
(62) |
Jul
(23) |
Aug
(40) |
Sep
(47) |
Oct
(40) |
Nov
(23) |
Dec
(21) |
| 2007 |
Jan
(57) |
Feb
(65) |
Mar
(77) |
Apr
(23) |
May
(118) |
Jun
(127) |
Jul
(87) |
Aug
(33) |
Sep
(26) |
Oct
(8) |
Nov
(4) |
Dec
(25) |
| 2008 |
Jan
(16) |
Feb
(18) |
Mar
(16) |
Apr
(4) |
May
(22) |
Jun
(20) |
Jul
(38) |
Aug
(14) |
Sep
(18) |
Oct
(68) |
Nov
(16) |
Dec
(95) |
| 2009 |
Jan
(28) |
Feb
(16) |
Mar
(8) |
Apr
(44) |
May
(35) |
Jun
(41) |
Jul
(63) |
Aug
(40) |
Sep
(38) |
Oct
(41) |
Nov
(17) |
Dec
(9) |
| 2010 |
Jan
(9) |
Feb
(3) |
Mar
(71) |
Apr
(20) |
May
(15) |
Jun
(16) |
Jul
(33) |
Aug
(13) |
Sep
(39) |
Oct
(30) |
Nov
(25) |
Dec
(20) |
| 2011 |
Jan
(213) |
Feb
(252) |
Mar
(24) |
Apr
(24) |
May
(20) |
Jun
(21) |
Jul
(37) |
Aug
(18) |
Sep
(28) |
Oct
(65) |
Nov
(22) |
Dec
(48) |
| 2012 |
Jan
(35) |
Feb
(39) |
Mar
(17) |
Apr
(9) |
May
(37) |
Jun
(31) |
Jul
(23) |
Aug
(14) |
Sep
(16) |
Oct
(15) |
Nov
(5) |
Dec
(43) |
| 2013 |
Jan
(15) |
Feb
(19) |
Mar
(26) |
Apr
(13) |
May
(9) |
Jun
(11) |
Jul
(32) |
Aug
(9) |
Sep
(6) |
Oct
|
Nov
(13) |
Dec
(5) |
| 2014 |
Jan
(2) |
Feb
(3) |
Mar
(1) |
Apr
|
May
(2) |
Jun
(4) |
Jul
(18) |
Aug
|
Sep
|
Oct
(3) |
Nov
(4) |
Dec
(2) |
| 2015 |
Jan
(3) |
Feb
(25) |
Mar
(49) |
Apr
(28) |
May
(13) |
Jun
(2) |
Jul
(2) |
Aug
(14) |
Sep
(9) |
Oct
(6) |
Nov
|
Dec
(2) |
| 2016 |
Jan
(2) |
Feb
(1) |
Mar
|
Apr
|
May
(12) |
Jun
|
Jul
(17) |
Aug
(7) |
Sep
(3) |
Oct
(2) |
Nov
(5) |
Dec
(28) |
| 2017 |
Jan
(11) |
Feb
(6) |
Mar
(10) |
Apr
(10) |
May
(34) |
Jun
(32) |
Jul
(15) |
Aug
(28) |
Sep
(8) |
Oct
(10) |
Nov
(14) |
Dec
(2) |
| 2018 |
Jan
(8) |
Feb
|
Mar
|
Apr
|
May
|
Jun
(5) |
Jul
(7) |
Aug
|
Sep
(1) |
Oct
|
Nov
(15) |
Dec
|
| 2019 |
Jan
|
Feb
(7) |
Mar
(2) |
Apr
(2) |
May
(2) |
Jun
(2) |
Jul
(48) |
Aug
(73) |
Sep
(22) |
Oct
(8) |
Nov
(16) |
Dec
(26) |
| 2020 |
Jan
(30) |
Feb
(13) |
Mar
(15) |
Apr
(6) |
May
(1) |
Jun
(3) |
Jul
(12) |
Aug
(18) |
Sep
(18) |
Oct
(5) |
Nov
(9) |
Dec
(16) |
| 2021 |
Jan
(13) |
Feb
(17) |
Mar
(19) |
Apr
(70) |
May
(43) |
Jun
(27) |
Jul
(18) |
Aug
(15) |
Sep
(16) |
Oct
(37) |
Nov
(38) |
Dec
(11) |
| 2022 |
Jan
(73) |
Feb
(18) |
Mar
(36) |
Apr
(6) |
May
(8) |
Jun
(33) |
Jul
(22) |
Aug
|
Sep
(6) |
Oct
(71) |
Nov
(91) |
Dec
(26) |
| 2023 |
Jan
(12) |
Feb
(5) |
Mar
(5) |
Apr
(34) |
May
(29) |
Jun
(27) |
Jul
(3) |
Aug
(17) |
Sep
(11) |
Oct
(4) |
Nov
(34) |
Dec
(7) |
| 2024 |
Jan
(16) |
Feb
(27) |
Mar
(60) |
Apr
(57) |
May
(55) |
Jun
(50) |
Jul
(36) |
Aug
(108) |
Sep
(27) |
Oct
(33) |
Nov
(15) |
Dec
(14) |
| 2025 |
Jan
(2) |
Feb
(7) |
Mar
(49) |
Apr
(51) |
May
(35) |
Jun
(34) |
Jul
(10) |
Aug
(32) |
Sep
(27) |
Oct
(1) |
Nov
(13) |
Dec
(12) |
| 2026 |
Jan
(16) |
Feb
(6) |
Mar
(8) |
Apr
(14) |
May
(19) |
Jun
(36) |
Jul
(11) |
Aug
|
Sep
|
Oct
|
Nov
|
Dec
|
|
From: <mi...@us...> - 2026-07-16 10:43:58
|
Revision: 10388
http://sourceforge.net/p/docutils/code/10388
Author: milde
Date: 2026-07-16 10:43:55 +0000 (Thu, 16 Jul 2026)
Log Message:
-----------
Fix anonymous hyperlinks to "clickable" images.
Images with :target: option are wrapped in a `<reference>`
to the specified target.
Anonymous links to the image were redirected to the image's target (sic!).
Propagation of internal targets to the next "suitable" element now transfers
"ids" and "names" to the `<image>`, not the wrapping `<reference>`.
Modified Paths:
--------------
trunk/docutils/HISTORY.rst
trunk/docutils/docutils/transforms/references.py
trunk/docutils/test/test_transforms/test_hyperlinks.py
Modified: trunk/docutils/HISTORY.rst
===================================================================
--- trunk/docutils/HISTORY.rst 2026-07-16 10:43:46 UTC (rev 10387)
+++ trunk/docutils/HISTORY.rst 2026-07-16 10:43:55 UTC (rev 10388)
@@ -108,10 +108,13 @@
the `unknown_reference_resolvers` hook.
- 3 new transforms, `MatchReferences`, `ReportDanglingReferences`,
and `ReportUnreferencedLinks` obsolete `DanglingReferences`.
+ - "lazy IDs": Handle hyperlink targets without ID;
+ if required, generate and set one.
- Add INFO system_message if a <target> cannot be propagated
to the next node.
- - "lazy IDs": Handle hyperlink targets without ID;
- if required, generate and set one.
+ - Fix anonymous hyperlinks to "clickable" images: "Propagation" of a
+ <target> in front of a "clickable" image now transfers "ids" and
+ "names" to the `<image>`, not the wrapping `<reference>`.
* docutils/transforms/universal.py
Modified: trunk/docutils/docutils/transforms/references.py
===================================================================
--- trunk/docutils/docutils/transforms/references.py 2026-07-16 10:43:46 UTC (rev 10387)
+++ trunk/docutils/docutils/transforms/references.py 2026-07-16 10:43:55 UTC (rev 10388)
@@ -148,6 +148,11 @@
if (isinstance(candidate, (nodes.Invisible, nodes.Targetable))
and not isinstance(candidate, nodes.target)):
return None
+ # If the next element is a "clickable" image (a <reference>
+ # wrapped around an <image>), return the <image>
+ if (isinstance(candidate, nodes.reference) and len(candidate) == 1
+ and isinstance(candidate[0], nodes.image)):
+ return candidate[0]
return candidate
def is_internal(self, node: nodes.Node) -> bool:
Modified: trunk/docutils/test/test_transforms/test_hyperlinks.py
===================================================================
--- trunk/docutils/test/test_transforms/test_hyperlinks.py 2026-07-16 10:43:46 UTC (rev 10387)
+++ trunk/docutils/test/test_transforms/test_hyperlinks.py 2026-07-16 10:43:55 UTC (rev 10388)
@@ -1041,15 +1041,13 @@
<target ids="external" names="external" refuri="http://uri">
<target ids="indirect" names="indirect" refuri="http://uri">
<target refid="internal">
- <reference ids="internal" names="internal" refuri="http://uri">
- <image uri="picture.png">
<reference refuri="http://uri">
+ <image ids="internal" names="internal" uri="picture.png">
+ <reference refuri="http://uri">
<image uri="picture.png">
<reference refid="internal">
<image uri="picture.png">
"""],
-# TODO: Anonymous links to a "clickable image should go
-# to the image, not the image's click-target!
["""\
.. _img1:
.. image:: pic1.png
@@ -1062,18 +1060,18 @@
Named link to img1_ with target and anonymous links to
the targetless img2__ and
-img3__ with target (sic!).
+img3__ with target.
""",
"""\
<document source="test data">
<target refid="img1">
- <reference ids="img1" names="img1" refuri="uri1.html">
- <image uri="pic1.png">
+ <reference refuri="uri1.html">
+ <image ids="img1" names="img1" uri="pic1.png">
<target anonymous="1" refid="target-1">
<image ids="target-1" uri="pic2.png">
<target anonymous="1" refid="target-2">
- <reference ids="target-2" refuri="uri3.html">
- <image uri="pic3.png">
+ <reference refuri="uri3.html">
+ <image ids="target-2" uri="pic3.png">
<paragraph>
Named link to \n\
<reference refid="img1">
@@ -1083,9 +1081,9 @@
<reference anonymous="1" refid="target-1">
img2
and
- <reference anonymous="1" refuri="uri3.html">
+ <reference anonymous="1" refid="target-2">
img3
- with target (sic!).
+ with target.
"""],
["""\
__
@@ -1093,7 +1091,7 @@
.. image:: pic1.png
:target: uri1.html
-Two anonymous__ links to an `image with target`__ (sic!).
+Two anonymous__ links to an `image with target`__.
.. _named:
__
@@ -1100,7 +1098,7 @@
.. image:: pic2.png
:target: uri2.html
-Named_ and anonymous__ link to an image with target (sic!).
+Named_ and anonymous__ link to an image with target.
__
.. _named link:
@@ -1107,44 +1105,44 @@
.. image:: pic3.png
:target: uri3.html
-Anonymous__ and `named link`_ to an image with target (sic!).
+Anonymous__ and `named link`_ to an image with target.
""",
"""\
<document source="test data">
<target anonymous="1" refid="target-1">
<target anonymous="1" refid="target-2">
- <reference ids="target-2 target-1" refuri="uri1.html">
- <image uri="pic1.png">
+ <reference refuri="uri1.html">
+ <image ids="target-2 target-1" uri="pic1.png">
<paragraph>
Two \n\
- <reference anonymous="1" refuri="uri1.html">
+ <reference anonymous="1" refid="target-2">
anonymous
links to an \n\
- <reference anonymous="1" refuri="uri1.html">
+ <reference anonymous="1" refid="target-2">
image with target
- (sic!).
+ .
<target refid="named">
<target anonymous="1" refid="target-3">
- <reference ids="target-3 named" names="named" refuri="uri2.html">
- <image uri="pic2.png">
+ <reference refuri="uri2.html">
+ <image ids="target-3 named" names="named" uri="pic2.png">
<paragraph>
<reference refid="named">
Named
and \n\
- <reference anonymous="1" refuri="uri2.html">
+ <reference anonymous="1" refid="target-3">
anonymous
- link to an image with target (sic!).
+ link to an image with target.
<target anonymous="1" refid="target-4">
<target refid="named-link">
- <reference ids="named-link target-4" names="named\\ link" refuri="uri3.html">
- <image uri="pic3.png">
+ <reference refuri="uri3.html">
+ <image ids="named-link target-4" names="named\\ link" uri="pic3.png">
<paragraph>
- <reference anonymous="1" refuri="uri3.html">
+ <reference anonymous="1" refid="named-link">
Anonymous
and \n\
<reference refid="named-link">
named link
- to an image with target (sic!).
+ to an image with target.
"""],
["""\
.. __: http://full
@@ -1477,10 +1475,10 @@
<document source="test data">
<target names="external" refuri="http://uri">
<target names="indirect" refuri="http://uri">
- <target refname="internal">
- <reference ids="internal" names="internal" refuri="http://uri">
- <image uri="picture.png">
+ <target refid="internal">
<reference refuri="http://uri">
+ <image ids="internal" names="internal" uri="picture.png">
+ <reference refuri="http://uri">
<image uri="picture.png">
<reference refid="internal">
<image uri="picture.png">
@@ -1499,18 +1497,18 @@
Named link to img1_ with target and anonymous links to
the targetless img2__ and
-img3__ with target (sic!).
+img3__ with target.
""",
"""\
<document source="test data">
- <target refname="img1">
- <reference ids="img1" names="img1" refuri="uri1.html">
- <image uri="pic1.png">
+ <target refid="img1">
+ <reference refuri="uri1.html">
+ <image ids="img1" names="img1" uri="pic1.png">
<target anonymous="1" refid="image-1">
<image ids="image-1" uri="pic2.png">
- <target anonymous="1" refid="reference-1">
- <reference ids="reference-1" refuri="uri3.html">
- <image uri="pic3.png">
+ <target anonymous="1" refid="image-2">
+ <reference refuri="uri3.html">
+ <image ids="image-2" uri="pic3.png">
<paragraph>
Named link to \n\
<reference refid="img1">
@@ -1520,9 +1518,9 @@
<reference anonymous="1" refid="image-1">
img2
and
- <reference anonymous="1" refuri="uri3.html">
+ <reference anonymous="1" refid="image-2">
img3
- with target (sic!).
+ with target.
"""],
["""\
__
@@ -1530,7 +1528,7 @@
.. image:: pic1.png
:target: uri1.html
-Two anonymous__ links to an `image with target`__ (sic!).
+Two anonymous__ links to an `image with target`__.
.. _named:
__
@@ -1537,7 +1535,7 @@
.. image:: pic2.png
:target: uri2.html
-Named_ and anonymous__ link to an image with target (sic!).
+Named_ and anonymous__ link to an image with target.
__
.. _named link:
@@ -1544,44 +1542,44 @@
.. image:: pic3.png
:target: uri3.html
-Anonymous__ and `named link`_ to an image with target (sic!).
+Anonymous__ and `named link`_ to an image with target.
""",
"""\
<document source="test data">
<target anonymous="1">
- <target anonymous="1" refid="reference-1">
- <reference ids="reference-1" refuri="uri1.html">
- <image uri="pic1.png">
+ <target anonymous="1" refid="image-1">
+ <reference refuri="uri1.html">
+ <image ids="image-1" uri="pic1.png">
<paragraph>
Two \n\
- <reference anonymous="1" refuri="uri1.html">
+ <reference anonymous="1" refid="image-1">
anonymous
links to an \n\
- <reference anonymous="1" refuri="uri1.html">
+ <reference anonymous="1" refid="image-1">
image with target
- (sic!).
- <target refname="named">
- <target anonymous="1" refname="named">
- <reference ids="named" names="named" refuri="uri2.html">
- <image uri="pic2.png">
+ .
+ <target refid="named">
+ <target anonymous="1" refid="named">
+ <reference refuri="uri2.html">
+ <image ids="named" names="named" uri="pic2.png">
<paragraph>
<reference refid="named">
Named
and \n\
- <reference anonymous="1" refuri="uri2.html">
+ <reference anonymous="1" refid="named">
anonymous
- link to an image with target (sic!).
+ link to an image with target.
<target anonymous="1" refname="named link">
- <target refname="named link">
- <reference ids="named-link" names="named\\ link" refuri="uri3.html">
- <image uri="pic3.png">
+ <target refid="named-link">
+ <reference refuri="uri3.html">
+ <image ids="named-link" names="named\\ link" uri="pic3.png">
<paragraph>
- <reference anonymous="1" refuri="uri3.html">
+ <reference anonymous="1" refid="named-link">
Anonymous
and \n\
<reference refid="named-link">
named link
- to an image with target (sic!).
+ to an image with target.
"""],
["""\
.. __: http://full
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
|
From: <mi...@us...> - 2026-07-16 10:43:49
|
Revision: 10387
http://sourceforge.net/p/docutils/code/10387
Author: milde
Date: 2026-07-16 10:43:46 +0000 (Thu, 16 Jul 2026)
Log Message:
-----------
Simplify logic in AnonymousHyperlinks transform.
No change to the behaviour.
Modified Paths:
--------------
trunk/docutils/docutils/transforms/references.py
Modified: trunk/docutils/docutils/transforms/references.py
===================================================================
--- trunk/docutils/docutils/transforms/references.py 2026-07-16 10:43:33 UTC (rev 10386)
+++ trunk/docutils/docutils/transforms/references.py 2026-07-16 10:43:46 UTC (rev 10387)
@@ -218,20 +218,18 @@
ref['refuri'] = target['refuri']
ref.resolved = True
break
- else:
- if not target['ids']:
- if 'refid' in target: # propagated target
- target = self.document.ids[target['refid']]
- elif 'refname' in target: # indirect target
- target = self.document.names[target['refname']]
- elif next_node := self.next_suitable_node(target):
- target = next_node
- else:
- self.document.set_id(target)
- continue
+ if target['ids']:
ref['refid'] = target['ids'][0]
self.document.note_refid(ref)
break
+ if 'refid' in target: # propagated target
+ target = self.document.ids[target['refid']]
+ elif 'refname' in target: # indirect target
+ target = self.document.names[target['refname']]
+ elif next_node := self.next_suitable_node(target):
+ target = next_node
+ else:
+ self.document.set_id(target)
class IndirectHyperlinks(Transform):
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
|
From: <mi...@us...> - 2026-07-16 10:43:42
|
Revision: 10386
http://sourceforge.net/p/docutils/code/10386
Author: milde
Date: 2026-07-16 10:43:33 +0000 (Thu, 16 Jul 2026)
Log Message:
-----------
Fix issue with inline targets containing substring "refname" or "refuri".
`nodes.Node.next_node()` may return a `nodes.Text` instance
where ``if "refname" in node`` does not test for attributes but
the substring "refname" in the text content.
This led to `<target names="%refname.att">%refname.att</target>`
beeing wrongly identified as an indirect target and a subsequent
AssertionError because the corresponding `<reference>` did not get
a "refid" attribute.
Adding a check makes `PropagateTargets.next_suitable_target()`
return None if called with a non-empty start target.
For added robustness, `PropagateTargets.is_internal()` checks if
the given argument is a `nodes.Element` instance.
Modified Paths:
--------------
trunk/docutils/docutils/nodes.py
trunk/docutils/docutils/transforms/references.py
trunk/docutils/docutils/writers/_html_base.py
trunk/docutils/test/test_nodes.py
Modified: trunk/docutils/docutils/nodes.py
===================================================================
--- trunk/docutils/docutils/nodes.py 2026-07-16 10:43:24 UTC (rev 10385)
+++ trunk/docutils/docutils/nodes.py 2026-07-16 10:43:33 UTC (rev 10386)
@@ -688,6 +688,9 @@
def __contains__(self, key: str | Node) -> bool:
# Test for both, children and attributes with operator ``in``.
+ #
+ # Caution: Document Tree traversal also returns Text nodes where
+ # ``in`` looks for substrings in the text content.
if isinstance(key, str):
return key in self.attributes
return key in self.children
Modified: trunk/docutils/docutils/transforms/references.py
===================================================================
--- trunk/docutils/docutils/transforms/references.py 2026-07-16 10:43:24 UTC (rev 10385)
+++ trunk/docutils/docutils/transforms/references.py 2026-07-16 10:43:33 UTC (rev 10386)
@@ -133,8 +133,11 @@
target['names'] = []
def next_suitable_node(self, target: nodes.Element) -> nodes.Element:
- if not isinstance(target, nodes.target):
- return None # only <target> ids/names are propagated
+ # Return the next suitable element for the transfer of the
+ # "names" and "ids" attributes from an empty "internal" <target>
+ # (target propagation).
+ if not isinstance(target, nodes.target) or len(target):
+ return None
candidate = target.next_node(ascend=True)
# skip system messages (may be removed by universal.FilterMessages)
while isinstance(candidate, nodes.system_message):
@@ -147,8 +150,10 @@
return None
return candidate
- def is_internal(self, node: nodes.Element) -> bool:
- # Return True, if `node` is an internal hyperlink target.
+ def is_internal(self, node: nodes.Node) -> bool:
+ # Return True, if `node` is a potential internal hyperlink target.
+ if not isinstance(node, nodes.Element):
+ return False
if 'refid' in node or 'refname' in node or 'refuri' in node:
return False # node is indirect or external target
# check destination of chained targets:
Modified: trunk/docutils/docutils/writers/_html_base.py
===================================================================
--- trunk/docutils/docutils/writers/_html_base.py 2026-07-16 10:43:24 UTC (rev 10385)
+++ trunk/docutils/docutils/writers/_html_base.py 2026-07-16 10:43:33 UTC (rev 10386)
@@ -1526,7 +1526,7 @@
atts['classes'].append('external')
else:
assert 'refid' in node, \
- 'References must have "refuri" or "refid" attribute.'
+ f'Reference without "refuri" or "refid" attribute: {node}'
atts['href'] = '#' + node['refid']
atts['classes'].append('internal')
if len(node) == 1 and isinstance(node[0], nodes.image):
Modified: trunk/docutils/test/test_nodes.py
===================================================================
--- trunk/docutils/test/test_nodes.py 2026-07-16 10:43:24 UTC (rev 10385)
+++ trunk/docutils/test/test_nodes.py 2026-07-16 10:43:33 UTC (rev 10386)
@@ -94,6 +94,14 @@
e[0][1] += nodes.Text('some text')
e += nodes.Element()
e += nodes.Element()
+ # Tree Index testlist
+ # <Element> e
+ # <Element> e[0] skip
+ # <Element> e[0][0]
+ # <TextElement> e[0][1] skip
+ # <Text> e[0][1][0]
+ # <Element> e[1] skip
+ # <Element> e[2]
self.testlist = [e[0], e[0][1], e[1]]
compare = [(e, e[0][0]),
(e[0], e[0][0]),
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
|
From: <mi...@us...> - 2026-07-16 10:43:26
|
Revision: 10385
http://sourceforge.net/p/docutils/code/10385
Author: milde
Date: 2026-07-16 10:43:24 +0000 (Thu, 16 Jul 2026)
Log Message:
-----------
"lazy IDs": handle "chained" targets.
Recursively test the next nodes of a to-be-propagated target; only set IDs
if it is an explicit internal target.
Modified Paths:
--------------
trunk/docutils/HISTORY.rst
trunk/docutils/RELEASE-NOTES.rst
trunk/docutils/docutils/transforms/references.py
trunk/docutils/test/test_transforms/test_hyperlinks.py
Modified: trunk/docutils/HISTORY.rst
===================================================================
--- trunk/docutils/HISTORY.rst 2026-07-16 10:43:14 UTC (rev 10384)
+++ trunk/docutils/HISTORY.rst 2026-07-16 10:43:24 UTC (rev 10385)
@@ -99,18 +99,18 @@
* docutils/transforms/parts.py:
- - `Contents.build_contents()`: ensure sections have an ID and prefer
- IDs from external targets with "lazy IDs" (`legacy_ids`_ False).
+ - "lazy IDs": `Contents.build_contents()` ensures sections have an ID
+ and prefers IDs from external targets if `legacy_ids`_ is False.
* docutils/transforms/references.py
- `IndirectHyperlinks.resolve_indirect_target()` no longer calls
- `unknown_reference_resolvers` and only sets IDs if required.
+ the `unknown_reference_resolvers` hook.
- 3 new transforms, `MatchReferences`, `ReportDanglingReferences`,
and `ReportUnreferencedLinks` obsolete `DanglingReferences`.
- Add INFO system_message if a <target> cannot be propagated
to the next node.
- - support "lazy IDs": Handle hyperlink targets without ID;
+ - "lazy IDs": Handle hyperlink targets without ID;
if required, generate and set one.
* docutils/transforms/universal.py
Modified: trunk/docutils/RELEASE-NOTES.rst
===================================================================
--- trunk/docutils/RELEASE-NOTES.rst 2026-07-16 10:43:14 UTC (rev 10384)
+++ trunk/docutils/RELEASE-NOTES.rst 2026-07-16 10:43:24 UTC (rev 10385)
@@ -233,11 +233,9 @@
rST parser:
- Warn if a `"figure"`_ directive is missing both caption and legend.
- - Don't generate identifiers for indirect or external targets
- (unless legacy_ids_ is True).
- - Generate identifiers for implicit targets (mainly sections) only if
- there is a cross-link to the target [#cross-links]_ and no "explicit"
- identifier (unless legacy_ids_ is True).
+ - "lazy IDs": Generate target ids_ in transforms -- after parsing and
+ only if required in the output document.
+ Keep behaviour backwards compatible with the legacy_ids_ setting.
HTML5 writer:
- Use normal font size and colour for informal titles of type "rubric".
@@ -298,6 +296,7 @@
"`section self-links <section_self_link_>`_" added by the HTML5
writer.
+
Release 0.23 (2026-05-27)
=========================
@@ -1609,8 +1608,9 @@
.. _Docutils Document Model:
.. _Docutils XML: docs/ref/doctree.html
.. _"colwidth" attribute: docs/ref/doctree.html#colwidth
+.. _<doctest_block>: docs/ref/doctree.html#doctest-block
.. _identifier: docs/ref/doctree.html#identifiers
-.. _<doctest_block>: docs/ref/doctree.html#doctest-block
+.. _ids: docs/ref/doctree.html#ids
.. _reference names: docs/ref/doctree.html#reference-names
.. _<target>: docs/ref/doctree.html#target
Modified: trunk/docutils/docutils/transforms/references.py
===================================================================
--- trunk/docutils/docutils/transforms/references.py 2026-07-16 10:43:14 UTC (rev 10384)
+++ trunk/docutils/docutils/transforms/references.py 2026-07-16 10:43:24 UTC (rev 10385)
@@ -69,7 +69,7 @@
if node is None or not self.document.nametypes[name]:
continue
# Skip external or indirect targets:
- if 'refid' in node or 'refname' in node or 'refuri' in node:
+ if not self.is_internal(node):
continue
self.document.set_id(node)
# Now propatate internal <target>s:
@@ -80,15 +80,8 @@
or 'refname' in target
or 'refuri' in target):
continue
- next_node = target.next_node(ascend=True)
- # skip system messages (may be removed by universal.FilterMessages)
- while isinstance(next_node, nodes.system_message):
- next_node = next_node.next_node(ascend=True, descend=False)
- # Do not move names and ids into Invisibles (we'd lose the
- # attributes) or different Targetables (e.g. footnotes).
- if (next_node is None
- or isinstance(next_node, (nodes.Invisible, nodes.Targetable))
- and not isinstance(next_node, nodes.target)):
+ next_node = self.next_suitable_node(target)
+ if next_node is None:
self.document.reporter.info(
f'Cannot propagate target "{" ".join(target["names"])}" '
'to next element', base_node=target)
@@ -135,13 +128,37 @@
self.document.note_refname(target)
elif next_node['names']:
target['refname'] = next_node['names'][0]
- else:
+ elif 'anonymous' not in next_node:
target['refid'] = self.document.set_id(next_node)
target['names'] = []
+ def next_suitable_node(self, target: nodes.Element) -> nodes.Element:
+ if not isinstance(target, nodes.target):
+ return None # only <target> ids/names are propagated
+ candidate = target.next_node(ascend=True)
+ # skip system messages (may be removed by universal.FilterMessages)
+ while isinstance(candidate, nodes.system_message):
+ candidate = candidate.next_node(ascend=True, descend=False)
+ # Do not move names and ids into Invisibles (we'd lose the
+ # attributes) or Targetables (<citation>, <footnote>).
+ # Other <target>s are OK. TODO: why no citations and footnotes?
+ if (isinstance(candidate, (nodes.Invisible, nodes.Targetable))
+ and not isinstance(candidate, nodes.target)):
+ return None
+ return candidate
-class AnonymousHyperlinks(Transform):
+ def is_internal(self, node: nodes.Element) -> bool:
+ # Return True, if `node` is an internal hyperlink target.
+ if 'refid' in node or 'refname' in node or 'refuri' in node:
+ return False # node is indirect or external target
+ # check destination of chained targets:
+ if next_node := self.next_suitable_node(node):
+ return self.is_internal(next_node)
+ return True
+
+class AnonymousHyperlinks(PropagateTargets):
+
"""
Link anonymous references to targets. Given::
@@ -186,6 +203,7 @@
msg.add_backref(prbid)
ref.replace_self(prb)
return
+
for ref, target in zip(anonymous_refs, anonymous_targets):
if ref.hasattr('refid') or ref.hasattr('refuri'):
continue
@@ -201,6 +219,8 @@
target = self.document.ids[target['refid']]
elif 'refname' in target: # indirect target
target = self.document.names[target['refname']]
+ elif next_node := self.next_suitable_node(target):
+ target = next_node
else:
self.document.set_id(target)
continue
@@ -1032,8 +1052,8 @@
naming = target['ids'][0]
else:
# Propagated target: "ids" and "names" attributes moved
- # to the node indicated by "refid" or "refname".
- naming = target.get('refid') or target.get('refname', '???')
+ # to the node indicated by "refname" or "refid".
+ naming = target.get('refname') or target.get('refid', '???')
self.document.reporter.info(
f'Hyperlink target "{naming}" is not referenced.',
base_node=target)
Modified: trunk/docutils/test/test_transforms/test_hyperlinks.py
===================================================================
--- trunk/docutils/test/test_transforms/test_hyperlinks.py 2026-07-16 10:43:14 UTC (rev 10384)
+++ trunk/docutils/test/test_transforms/test_hyperlinks.py 2026-07-16 10:43:24 UTC (rev 10385)
@@ -1300,8 +1300,8 @@
<reference refuri="URI">
target2
, not the Title.
- <target refid="target1">
- <target ids="target1" names="target2 target1" refuri="URI">
+ <target refuri="URI">
+ <target names="target2 target1" refuri="URI">
<section names="title">
<title>
Title
@@ -1401,8 +1401,8 @@
""",
"""\
<document source="test data">
- <target refid="chained">
- <target ids="chained" names="external\\ hyperlink chained" refuri="http://uri">
+ <target refuri="http://uri">
+ <target names="external\\ hyperlink chained" refuri="http://uri">
<paragraph>
<reference refuri="http://uri">
External hyperlink
@@ -1450,7 +1450,7 @@
<document source="test data">
<target names="external\\ hyperlink" refuri="http://uri">
<target refuri="http://uri">
- <target ids="chained" names="indirect\\ hyperlink chained" refuri="http://uri">
+ <target names="indirect\\ hyperlink chained" refuri="http://uri">
<paragraph>
<reference refuri="http://uri">
Chained
@@ -1477,7 +1477,7 @@
<document source="test data">
<target names="external" refuri="http://uri">
<target names="indirect" refuri="http://uri">
- <target refid="internal">
+ <target refname="internal">
<reference ids="internal" names="internal" refuri="http://uri">
<image uri="picture.png">
<reference refuri="http://uri">
@@ -1503,7 +1503,7 @@
""",
"""\
<document source="test data">
- <target refid="img1">
+ <target refname="img1">
<reference ids="img1" names="img1" refuri="uri1.html">
<image uri="pic1.png">
<target anonymous="1" refid="image-1">
@@ -1548,9 +1548,9 @@
""",
"""\
<document source="test data">
- <target anonymous="1" refid="target-1">
- <target anonymous="1" refid="target-1">
- <reference ids="target-1" refuri="uri1.html">
+ <target anonymous="1">
+ <target anonymous="1" refid="reference-1">
+ <reference ids="reference-1" refuri="uri1.html">
<image uri="pic1.png">
<paragraph>
Two \n\
@@ -1560,8 +1560,8 @@
<reference anonymous="1" refuri="uri1.html">
image with target
(sic!).
- <target refid="named">
- <target anonymous="1" refid="named">
+ <target refname="named">
+ <target anonymous="1" refname="named">
<reference ids="named" names="named" refuri="uri2.html">
<image uri="pic2.png">
<paragraph>
@@ -1572,7 +1572,7 @@
anonymous
link to an image with target (sic!).
<target anonymous="1" refname="named link">
- <target refid="named-link">
+ <target refname="named link">
<reference ids="named-link" names="named\\ link" refuri="uri3.html">
<image uri="pic3.png">
<paragraph>
@@ -1590,20 +1590,23 @@
.. _external: http://indirect.external
__ external_
__
+__
`Full syntax anonymous external hyperlink reference`__,
`chained anonymous external reference`__,
`simplified syntax anonymous external hyperlink reference`__,
`indirect anonymous hyperlink reference`__,
-`internal anonymous hyperlink reference`__.
+`internal anonymous hyperlink reference`__,
+`second internal anonymous hyperlink reference`__.
""",
"""\
<document source="test data">
<target anonymous="1" refuri="http://full">
- <target anonymous="1" refid="target-1">
- <target anonymous="1" ids="target-1" refuri="http://simplified">
+ <target anonymous="1">
+ <target anonymous="1" refuri="http://simplified">
<target names="external" refuri="http://indirect.external">
<target anonymous="1" refuri="http://indirect.external">
+ <target anonymous="1">
<target anonymous="1" refid="paragraph-1">
<paragraph ids="paragraph-1">
<reference anonymous="1" refuri="http://full">
@@ -1620,6 +1623,9 @@
,
<reference anonymous="1" refid="paragraph-1">
internal anonymous hyperlink reference
+ ,
+ <reference anonymous="1" refid="paragraph-1">
+ second internal anonymous hyperlink reference
.
"""],
["""\
@@ -1630,8 +1636,8 @@
""",
"""\
<document source="test data">
- <target refid="chained">
- <target anonymous="1" ids="chained" names="chained" refuri="http://anonymous">
+ <target refuri="http://anonymous">
+ <target anonymous="1" names="chained" refuri="http://anonymous">
<paragraph>
<reference anonymous="1" refuri="http://anonymous">
Anonymous
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
|
From: <mi...@us...> - 2026-07-16 10:43:18
|
Revision: 10384
http://sourceforge.net/p/docutils/code/10384
Author: milde
Date: 2026-07-16 10:43:14 +0000 (Thu, 16 Jul 2026)
Log Message:
-----------
"lazy IDs": postpone generation of IDs for anonymous targets.
Generate IDs for explicit targets after parsing is complete:
`nodes.document.note_explicit_target()` only generates an ID for the target,
if the "legacy_ids" setting is True.
The `transforms.references.PropagateTargets` transform now can also
propagate targets without reference name or ID and sets an ID on the
destination of the propagation if required.
This is a precondition for a future check whether the destination of
to-be-propagated anonymous targets is an external or indirect target
that does not require an ID.
Anonymous internal targets now re-use an existing ID or get an auto-ID
based on the tagname of the target element
Modified Paths:
--------------
trunk/docutils/HISTORY.rst
trunk/docutils/docutils/nodes.py
trunk/docutils/docutils/transforms/references.py
trunk/docutils/test/test_transforms/test_hyperlinks.py
Modified: trunk/docutils/HISTORY.rst
===================================================================
--- trunk/docutils/HISTORY.rst 2026-07-15 18:57:56 UTC (rev 10383)
+++ trunk/docutils/HISTORY.rst 2026-07-16 10:43:14 UTC (rev 10384)
@@ -47,9 +47,9 @@
- Remove "name" from `reference.valid_attributes`.
- Remove the internal attribute `Targetable.indirect_reference_name`.
- - "lazy IDs": `document.note_explicit_target()` and
- `document.note_anonymous_target()` generate identifiers for indirect
- or external targets only if the `legacy_ids`_ setting is True.
+ - "lazy IDs":
+ `document.note_explicit_target()` and `document.note_anonymous_target()`
+ generate identifiers only if the `legacy_ids`_ setting is True.
* docutils/parsers/__init__.py
Modified: trunk/docutils/docutils/nodes.py
===================================================================
--- trunk/docutils/docutils/nodes.py 2026-07-15 18:57:56 UTC (rev 10383)
+++ trunk/docutils/docutils/nodes.py 2026-07-16 10:43:14 UTC (rev 10384)
@@ -2192,8 +2192,7 @@
self.note_refname(target)
def note_anonymous_target(self, target: target) -> None:
- if (getattr(self.settings, "legacy_ids", True)
- or 'refuri' not in target and 'refname' not in target):
+ if getattr(self.settings, "legacy_ids", True):
self.set_id(target)
def note_autofootnote(self, footnote: footnote) -> None:
Modified: trunk/docutils/docutils/transforms/references.py
===================================================================
--- trunk/docutils/docutils/transforms/references.py 2026-07-15 18:57:56 UTC (rev 10383)
+++ trunk/docutils/docutils/transforms/references.py 2026-07-16 10:43:14 UTC (rev 10384)
@@ -43,7 +43,7 @@
Given the following nodes::
<target names="internal1">
- <target anonymous="1" ids="id1">
+ <target anonymous="1">
<target names="internal2">
<paragraph>
This is a test.
@@ -53,9 +53,9 @@
to the paragraph itself::
<target refid="internal1">
- <target anonymous="1" refid="id1">
+ <target anonymous="1" refid="internal1">
<target refid="internal2">
- <paragraph ids="internal2 id1 internal1" names="internal2 internal1">
+ <paragraph ids="internal2 internal1" names="internal2 internal1">
This is a test.
"""
@@ -124,13 +124,20 @@
next_node, nodes.caption):
target.parent.remove(target)
continue
- # Set refid to point to the first former ID of target
- # which is now an ID of next_node.
- target['refid'] = target['ids'][0]
+ # Set refid or refname to point to the next_node.
# Clear ids and names; they have been moved to next_node.
- target['ids'] = []
+ if target['ids']:
+ target['refid'] = target['ids'][0]
+ self.document.note_refid(target)
+ target['ids'] = []
+ elif target['names']:
+ target['refname'] = target['names'][0]
+ self.document.note_refname(target)
+ elif next_node['names']:
+ target['refname'] = next_node['names'][0]
+ else:
+ target['refid'] = self.document.set_id(next_node)
target['names'] = []
- self.document.note_refid(target)
class AnonymousHyperlinks(Transform):
Modified: trunk/docutils/test/test_transforms/test_hyperlinks.py
===================================================================
--- trunk/docutils/test/test_transforms/test_hyperlinks.py 2026-07-15 18:57:56 UTC (rev 10383)
+++ trunk/docutils/test/test_transforms/test_hyperlinks.py 2026-07-16 10:43:14 UTC (rev 10384)
@@ -1506,10 +1506,10 @@
<target refid="img1">
<reference ids="img1" names="img1" refuri="uri1.html">
<image uri="pic1.png">
- <target anonymous="1" refid="target-1">
- <image ids="target-1" uri="pic2.png">
- <target anonymous="1" refid="target-2">
- <reference ids="target-2" refuri="uri3.html">
+ <target anonymous="1" refid="image-1">
+ <image ids="image-1" uri="pic2.png">
+ <target anonymous="1" refid="reference-1">
+ <reference ids="reference-1" refuri="uri3.html">
<image uri="pic3.png">
<paragraph>
Named link to \n\
@@ -1517,7 +1517,7 @@
img1
with target and anonymous links to
the targetless \n\
- <reference anonymous="1" refid="target-1">
+ <reference anonymous="1" refid="image-1">
img2
and
<reference anonymous="1" refuri="uri3.html">
@@ -1549,8 +1549,8 @@
"""\
<document source="test data">
<target anonymous="1" refid="target-1">
- <target anonymous="1" refid="target-2">
- <reference ids="target-2 target-1" refuri="uri1.html">
+ <target anonymous="1" refid="target-1">
+ <reference ids="target-1" refuri="uri1.html">
<image uri="pic1.png">
<paragraph>
Two \n\
@@ -1561,8 +1561,8 @@
image with target
(sic!).
<target refid="named">
- <target anonymous="1" refid="target-3">
- <reference ids="target-3 named" names="named" refuri="uri2.html">
+ <target anonymous="1" refid="named">
+ <reference ids="named" names="named" refuri="uri2.html">
<image uri="pic2.png">
<paragraph>
<reference refid="named">
@@ -1571,9 +1571,9 @@
<reference anonymous="1" refuri="uri2.html">
anonymous
link to an image with target (sic!).
- <target anonymous="1" refid="target-4">
+ <target anonymous="1" refname="named link">
<target refid="named-link">
- <reference ids="named-link target-4" names="named\\ link" refuri="uri3.html">
+ <reference ids="named-link" names="named\\ link" refuri="uri3.html">
<image uri="pic3.png">
<paragraph>
<reference anonymous="1" refuri="uri3.html">
@@ -1604,8 +1604,8 @@
<target anonymous="1" ids="target-1" refuri="http://simplified">
<target names="external" refuri="http://indirect.external">
<target anonymous="1" refuri="http://indirect.external">
- <target anonymous="1" refid="target-2">
- <paragraph ids="target-2">
+ <target anonymous="1" refid="paragraph-1">
+ <paragraph ids="paragraph-1">
<reference anonymous="1" refuri="http://full">
Full syntax anonymous external hyperlink reference
,
@@ -1618,7 +1618,7 @@
<reference anonymous="1" refuri="http://indirect.external">
indirect anonymous hyperlink reference
,
- <reference anonymous="1" refid="target-2">
+ <reference anonymous="1" refid="paragraph-1">
internal anonymous hyperlink reference
.
"""],
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
|
From: <mi...@us...> - 2026-07-15 18:57:59
|
Revision: 10383
http://sourceforge.net/p/docutils/code/10383
Author: milde
Date: 2026-07-15 18:57:56 +0000 (Wed, 15 Jul 2026)
Log Message:
-----------
"lazy IDs": postpone generation of IDs for explicit targets.
Generate IDs for explicit targets after parsing is complete:
`nodes.document.note_explicit_target()` only generates an ID for the target,
if the "legacy_ids" setting is True.
The `transforms.references.PropagateTargets` transform adds IDs to
internal explicit targets (which may also be <topics> or other elements)
before "propagating" empty targets.
`transforms.references.Footnotes.number_footnote_references()`
sets IDs on footnotes with "reference name" but no ID.
This is a precondition for a future check whether the destination of
to-be-propagated targets is an external or indirect target that does
not require an ID. For example in
~~~
.. _e.g.:
.. _example: eg.html
~~~
the second target may become `<target names="example e.g." refuri="eg.html">`
instead of `<target ids="e-g" names="example e.g." refuri="eg.html">`.
Adapt tests: the output of parser tests has no IDs for explicit targets,
nor has the output of transform tests that do not run the `PropagateTargets`
transform.
Modified Paths:
--------------
trunk/docutils/docutils/nodes.py
trunk/docutils/docutils/transforms/references.py
trunk/docutils/test/test_parsers/test_rst/test_directives/test_include.py
trunk/docutils/test/test_parsers/test_rst/test_inline_markup.py
trunk/docutils/test/test_parsers/test_rst/test_targets.py
trunk/docutils/test/test_transforms/test_doctitle.py
trunk/docutils/test/test_transforms/test_hyperlinks.py
trunk/docutils/test/test_transforms/test_transitions.py
Modified: trunk/docutils/docutils/nodes.py
===================================================================
--- trunk/docutils/docutils/nodes.py 2026-07-14 13:32:05 UTC (rev 10382)
+++ trunk/docutils/docutils/nodes.py 2026-07-15 18:57:56 UTC (rev 10383)
@@ -2177,8 +2177,7 @@
def note_explicit_target(self, target: Element,
msgnode: Element|None = None) -> None:
self.note_names(target, msgnode, explicit=True)
- if (getattr(self.settings, "legacy_ids", True)
- or 'refuri' not in target and 'refname' not in target):
+ if getattr(self.settings, "legacy_ids", True):
self.set_id(target, msgnode)
def note_refname(self, node: Element) -> None:
Modified: trunk/docutils/docutils/transforms/references.py
===================================================================
--- trunk/docutils/docutils/transforms/references.py 2026-07-14 13:32:05 UTC (rev 10382)
+++ trunk/docutils/docutils/transforms/references.py 2026-07-15 18:57:56 UTC (rev 10383)
@@ -42,14 +42,15 @@
Given the following nodes::
- <target ids="internal1" names="internal1">
+ <target names="internal1">
<target anonymous="1" ids="id1">
- <target ids="internal2" names="internal2">
+ <target names="internal2">
<paragraph>
This is a test.
- `PropagateTargets` propagates the ids and names of the internal
- targets preceding the paragraph to the paragraph itself::
+ `PropagateTargets` ensures internal targets have an ID and propagates
+ the IDs and names of the internal targets preceding the paragraph
+ to the paragraph itself::
<target refid="internal1">
<target anonymous="1" refid="id1">
@@ -61,6 +62,17 @@
default_priority = 260
def apply(self) -> None:
+ # Ensure explicit internal targets ("named" elements) have an ID:
+ if not getattr(self.document.settings, "legacy_ids", True):
+ for name, node in self.document.names.items():
+ # Skip targets with duplicate or implicit names:
+ if node is None or not self.document.nametypes[name]:
+ continue
+ # Skip external or indirect targets:
+ if 'refid' in node or 'refname' in node or 'refuri' in node:
+ continue
+ self.document.set_id(node)
+ # Now propatate internal <target>s:
for target in self.document.findall(nodes.target):
# Only block-level targets without reference (like ".. _target:"):
if (len(target) or isinstance(target.parent, nodes.TextElement)
@@ -590,8 +602,9 @@
ref.replace_self(prb)
break
ref += nodes.Text(label)
- id = self.document.nameids[label]
- footnote = self.document.ids[id]
+ footnote = self.document.names[label]
+ id = (self.document.nameids.get(label)
+ or self.document.set_id(footnote))
ref['refid'] = id
self.document.note_refid(ref)
assert len(ref['ids']) == 1
Modified: trunk/docutils/test/test_parsers/test_rst/test_directives/test_include.py
===================================================================
--- trunk/docutils/test/test_parsers/test_rst/test_directives/test_include.py 2026-07-14 13:32:05 UTC (rev 10382)
+++ trunk/docutils/test/test_parsers/test_rst/test_directives/test_include.py 2026-07-15 18:57:56 UTC (rev 10383)
@@ -179,7 +179,7 @@
<section names="include\\ test">
<title>
Include Test
- <literal_block classes="test" ids="my-name" names="my\\ name" source="{include1}" xml:space="preserve">
+ <literal_block classes="test" names="my\\ name" source="{include1}" xml:space="preserve">
Inclusion 1
-----------
\n\
@@ -244,7 +244,7 @@
<document source="test data">
<paragraph>
Include code
- <literal_block classes="code test" ids="my-name" names="my\\ name" source="{include1}" xml:space="preserve">
+ <literal_block classes="code test" names="my\\ name" source="{include1}" xml:space="preserve">
Inclusion 1
-----------
\n\
Modified: trunk/docutils/test/test_parsers/test_rst/test_inline_markup.py
===================================================================
--- trunk/docutils/test/test_parsers/test_rst/test_inline_markup.py 2026-07-14 13:32:05 UTC (rev 10382)
+++ trunk/docutils/test/test_parsers/test_rst/test_inline_markup.py 2026-07-15 18:57:56 UTC (rev 10383)
@@ -1168,10 +1168,10 @@
Report duplicate refname.
<paragraph>
Explicit targets: \n\
- <target ids="file-txt" names="file.txt">
+ <target names="file.txt">
file.txt
, \n\
- <target ids="file-html" names="file.html">
+ <target names="file.html">
file.html
.
<system_message level="1" line="6" source="test data" type="INFO">
@@ -1295,10 +1295,10 @@
Duplicate refnames in references with embedded alias.
<paragraph>
Explicit targets: \n\
- <target ids="tg1" names="tg1">
+ <target names="tg1">
tg1
and \n\
- <target ids="tg2" names="tg2">
+ <target names="tg2">
tg2
.
<system_message level="1" line="6" source="test data" type="INFO">
@@ -1334,19 +1334,19 @@
"""\
<document source="test data">
<paragraph>
- <target ids="target" names="target">
+ <target names="target">
target
<paragraph>
Here is \n\
- <target ids="another-target" names="another\\ target">
+ <target names="another\\ target">
another target
in some text. And \n\
- <target ids="yet-another-target" names="yet\\ another\\ target">
+ <target names="yet\\ another\\ target">
yet
another target
, spanning lines.
<paragraph>
- <target ids="here-is-a-target" names="here\\ is\\ a\\ target">
+ <target names="here\\ is\\ a\\ target">
Here is a TaRgeT
with case and spacial difficulties.
"""],
@@ -1357,10 +1357,10 @@
<document source="test data">
<paragraph>
l'
- <target ids="target1" names="target1">
+ <target names="target1">
target1
and l\u2019
- <target ids="target2" names="target2">
+ <target names="target2">
target2
with apostrophe
"""],
@@ -1373,21 +1373,21 @@
<document source="test data">
<paragraph>
quoted '
- <target ids="target1" names="target1">
+ <target names="target1">
target1
', quoted "
- <target ids="target2" names="target2">
+ <target names="target2">
target2
",
quoted \u2018
- <target ids="target3" names="target3">
+ <target names="target3">
target3
\u2019, quoted \u201c
- <target ids="target4" names="target4">
+ <target names="target4">
target4
\u201d,
quoted \xab
- <target ids="target5" names="target5">
+ <target names="target5">
target5
\xbb
"""],
@@ -1399,19 +1399,19 @@
"""\
<document source="test data">
<paragraph>
- <target ids="target1" names="'target1'">
+ <target names="'target1'">
'target1'
with quotes, \n\
- <target ids="target2" names=""target2"">
+ <target names=""target2"">
"target2"
with quotes,
- <target ids="target3" names="\u2018target3\u2019">
+ <target names="\u2018target3\u2019">
\u2018target3\u2019
with quotes, \n\
- <target ids="target4" names="\u201ctarget4\u201d">
+ <target names="\u201ctarget4\u201d">
\u201ctarget4\u201d
with quotes,
- <target ids="target5" names="\xabtarget5\xbb">
+ <target names="\xabtarget5\xbb">
\xabtarget5\xbb
with quotes
"""],
Modified: trunk/docutils/test/test_parsers/test_rst/test_targets.py
===================================================================
--- trunk/docutils/test/test_parsers/test_rst/test_targets.py 2026-07-14 13:32:05 UTC (rev 10382)
+++ trunk/docutils/test/test_parsers/test_rst/test_targets.py 2026-07-15 18:57:56 UTC (rev 10383)
@@ -53,7 +53,7 @@
""",
"""\
<document source="test data">
- <target ids="target" names="target">
+ <target names="target">
<paragraph>
(Internal hyperlink target.)
"""],
@@ -62,7 +62,7 @@
""",
"""\
<document source="test data">
- <target ids="optional-space-before-colon" names="optional\\ space\\ before\\ colon">
+ <target names="optional\\ space\\ before\\ colon">
"""],
[r"""
External hyperlink targets:
@@ -115,9 +115,9 @@
""",
"""\
<document source="test data">
- <target ids="a-long-target-name" names="a\\ long\\ target\\ name">
- <target ids="a-target-name-including-a-colon-quoted" names="a\\ target\\ name:\\ including\\ a\\ colon\\ (quoted)">
- <target ids="a-target-name-including-a-colon-escaped" names="a\\ target\\ name:\\ including\\ a\\ colon\\ (escaped)">
+ <target names="a\\ long\\ target\\ name">
+ <target names="a\\ target\\ name:\\ including\\ a\\ colon\\ (quoted)">
+ <target names="a\\ target\\ name:\\ including\\ a\\ colon\\ (escaped)">
"""],
["""\
.. _`target: No matching backquote.
@@ -144,8 +144,8 @@
""",
"""\
<document source="test data">
- <target ids="a-very-long-target-name-split-across-lines" names="a\\ very\\ long\\ target\\ name,\\ split\\ across\\ lines">
- <target ids="and-another-with-backquotes" names="and\\ another,\\ with\\ backquotes">
+ <target names="a\\ very\\ long\\ target\\ name,\\ split\\ across\\ lines">
+ <target names="and\\ another,\\ with\\ backquotes">
"""],
["""\
External hyperlink:
@@ -265,7 +265,7 @@
<document source="test data">
<paragraph>
Duplicate indirect \n\
- <target ids="targets" names="targets">
+ <target names="targets">
targets
(same refname):
<target names="link" refname="targets">
@@ -330,7 +330,7 @@
<system_message level="1" line="6" source="test data" type="INFO">
<paragraph>
Target name overrides implicit target name "title".
- <target ids="title" names="title">
+ <target names="title">
<paragraph>
Paragraph.
"""],
@@ -376,19 +376,19 @@
<document source="test data">
<paragraph>
Duplicate explicit targets.
- <target dupnames="title" ids="title">
+ <target dupnames="title">
<paragraph>
First.
<system_message level="2" line="7" source="test data" type="WARNING">
<paragraph>
Duplicate explicit target name: "title".
- <target dupnames="title" ids="title-1">
+ <target dupnames="title">
<paragraph>
Second.
<system_message level="2" line="11" source="test data" type="WARNING">
<paragraph>
Duplicate explicit target name: "title".
- <target dupnames="title" ids="title-2">
+ <target dupnames="title">
<paragraph>
Third.
"""],
@@ -409,7 +409,7 @@
<document source="test data">
<paragraph>
Duplicate explicit/directive targets.
- <target dupnames="title" ids="title">
+ <target dupnames="title">
<paragraph>
First.
<rubric dupnames="title" ids="title-1">
@@ -471,7 +471,7 @@
<system_message level="2" line="12" source="test data" type="WARNING">
<paragraph>
Duplicate explicit target name: "target".
- <target dupnames="target" ids="target-2">
+ <target dupnames="target">
<paragraph>
Explicit internal target.
<system_message level="2" line="16" source="test data" type="WARNING">
@@ -482,10 +482,10 @@
<line>
Do not insert <system_message> element for duplicate
<line>
- <target dupnames="target" ids="target-3">
+ <target dupnames="target" ids="target-2">
target
, if this results in an invalid doctree.
- <rubric dupnames="target" ids="target-4">
+ <rubric dupnames="target" ids="target-3">
directive with target
<field_list>
<field>
@@ -496,7 +496,7 @@
with
<field>
<field_name>
- <target dupnames="target" ids="target-5">
+ <target dupnames="target" ids="target-4">
target
<field_body>
<paragraph>
Modified: trunk/docutils/test/test_transforms/test_doctitle.py
===================================================================
--- trunk/docutils/test/test_transforms/test_doctitle.py 2026-07-14 13:32:05 UTC (rev 10382)
+++ trunk/docutils/test/test_transforms/test_doctitle.py 2026-07-15 18:57:56 UTC (rev 10383)
@@ -227,7 +227,7 @@
Title
<substitution_definition names="foo">
bar
- <target ids="invisible-target" names="invisible\\ target">
+ <target names="invisible\\ target">
<paragraph>
This title should be the document title despite the
substitution_definition.
Modified: trunk/docutils/test/test_transforms/test_hyperlinks.py
===================================================================
--- trunk/docutils/test/test_transforms/test_hyperlinks.py 2026-07-14 13:32:05 UTC (rev 10382)
+++ trunk/docutils/test/test_transforms/test_hyperlinks.py 2026-07-15 18:57:56 UTC (rev 10383)
@@ -1485,7 +1485,105 @@
<reference refid="internal">
<image uri="picture.png">
"""],
+# TODO: Anonymous links to a "clickable image should go
+# to the image, not the image's click-target!
["""\
+.. _img1:
+.. image:: pic1.png
+ :target: uri1.html
+__
+.. image:: pic2.png
+__
+.. image:: pic3.png
+ :target: uri3.html
+
+Named link to img1_ with target and anonymous links to
+the targetless img2__ and
+img3__ with target (sic!).
+""",
+"""\
+<document source="test data">
+ <target refid="img1">
+ <reference ids="img1" names="img1" refuri="uri1.html">
+ <image uri="pic1.png">
+ <target anonymous="1" refid="target-1">
+ <image ids="target-1" uri="pic2.png">
+ <target anonymous="1" refid="target-2">
+ <reference ids="target-2" refuri="uri3.html">
+ <image uri="pic3.png">
+ <paragraph>
+ Named link to \n\
+ <reference refid="img1">
+ img1
+ with target and anonymous links to
+ the targetless \n\
+ <reference anonymous="1" refid="target-1">
+ img2
+ and
+ <reference anonymous="1" refuri="uri3.html">
+ img3
+ with target (sic!).
+"""],
+["""\
+__
+__
+.. image:: pic1.png
+ :target: uri1.html
+
+Two anonymous__ links to an `image with target`__ (sic!).
+
+.. _named:
+__
+.. image:: pic2.png
+ :target: uri2.html
+
+Named_ and anonymous__ link to an image with target (sic!).
+
+__
+.. _named link:
+.. image:: pic3.png
+ :target: uri3.html
+
+Anonymous__ and `named link`_ to an image with target (sic!).
+""",
+"""\
+<document source="test data">
+ <target anonymous="1" refid="target-1">
+ <target anonymous="1" refid="target-2">
+ <reference ids="target-2 target-1" refuri="uri1.html">
+ <image uri="pic1.png">
+ <paragraph>
+ Two \n\
+ <reference anonymous="1" refuri="uri1.html">
+ anonymous
+ links to an \n\
+ <reference anonymous="1" refuri="uri1.html">
+ image with target
+ (sic!).
+ <target refid="named">
+ <target anonymous="1" refid="target-3">
+ <reference ids="target-3 named" names="named" refuri="uri2.html">
+ <image uri="pic2.png">
+ <paragraph>
+ <reference refid="named">
+ Named
+ and \n\
+ <reference anonymous="1" refuri="uri2.html">
+ anonymous
+ link to an image with target (sic!).
+ <target anonymous="1" refid="target-4">
+ <target refid="named-link">
+ <reference ids="named-link target-4" names="named\\ link" refuri="uri3.html">
+ <image uri="pic3.png">
+ <paragraph>
+ <reference anonymous="1" refuri="uri3.html">
+ Anonymous
+ and \n\
+ <reference refid="named-link">
+ named link
+ to an image with target (sic!).
+"""],
+["""\
.. __: http://full
__
__ http://simplified
Modified: trunk/docutils/test/test_transforms/test_transitions.py
===================================================================
--- trunk/docutils/test/test_transforms/test_transitions.py 2026-07-14 13:32:05 UTC (rev 10382)
+++ trunk/docutils/test/test_transforms/test_transitions.py 2026-07-15 18:57:56 UTC (rev 10383)
@@ -198,7 +198,7 @@
<system_message level="2" line="3" source="test data" type="WARNING">
<paragraph>
Transition at the end of the document.
- <target ids="anchor" names="anchor">
+ <target names="anchor">
<substitution_definition names="substitution\\ reference">
is invisible
"""],
@@ -316,7 +316,7 @@
<footer>
<paragraph>
will move away
- <target ids="anchor" names="anchor">
+ <target names="anchor">
<substitution_definition names="substitution\\ reference">
is invisible
<transition classes="classy">
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
|
From: <mi...@us...> - 2026-07-14 13:32:08
|
Revision: 10382
http://sourceforge.net/p/docutils/code/10382
Author: milde
Date: 2026-07-14 13:32:05 +0000 (Tue, 14 Jul 2026)
Log Message:
-----------
"lazy IDs": Don't generate IDs for external and indirect targets.
External and indirect targets have a "refuri", "refname" or "refid"
attribute that is transferred to all references to this target
(by the `IndirectHyperlinks` transform for named targets and by the
`AnonymousHyperlinks` transform for anonymouns targets).
The target's ID is not required and not shown in the output.
The change keeps the "identifier" namespace clean.
Example: The reference names "topic" and "<topic>" both map to the ID "topic".
With "legacy_ids", the section title in the following sample
would get the ID "topic-1":
~~~
.. _<topic>: ../doctree.html#topic
Topic
=====
:Doctree Element: `\<topic>`_
~~~
Modified Paths:
--------------
trunk/docutils/HISTORY.rst
trunk/docutils/RELEASE-NOTES.rst
trunk/docutils/docs/ref/rst/directives.rst
trunk/docutils/docs/user/config.rst
trunk/docutils/docutils/nodes.py
trunk/docutils/docutils/parsers/__init__.py
trunk/docutils/docutils/transforms/references.py
trunk/docutils/test/data/help/docutils.rst
trunk/docutils/test/data/help/rst2html.rst
trunk/docutils/test/data/help/rst2latex.rst
trunk/docutils/test/functional/expected/standalone_rst_pseudoxml.txt
trunk/docutils/test/test_parsers/test_rst/test_directives/test_include.py
trunk/docutils/test/test_parsers/test_rst/test_targets.py
trunk/docutils/test/test_transforms/test_hyperlinks.py
Modified: trunk/docutils/HISTORY.rst
===================================================================
--- trunk/docutils/HISTORY.rst 2026-07-14 13:31:29 UTC (rev 10381)
+++ trunk/docutils/HISTORY.rst 2026-07-14 13:32:05 UTC (rev 10382)
@@ -47,6 +47,9 @@
- Remove "name" from `reference.valid_attributes`.
- Remove the internal attribute `Targetable.indirect_reference_name`.
+ - "lazy IDs": `document.note_explicit_target()` and
+ `document.note_anonymous_target()` generate identifiers for indirect
+ or external targets only if the `legacy_ids`_ setting is True.
* docutils/parsers/__init__.py
Modified: trunk/docutils/RELEASE-NOTES.rst
===================================================================
--- trunk/docutils/RELEASE-NOTES.rst 2026-07-14 13:31:29 UTC (rev 10381)
+++ trunk/docutils/RELEASE-NOTES.rst 2026-07-14 13:32:05 UTC (rev 10382)
@@ -233,6 +233,8 @@
rST parser:
- Warn if a `"figure"`_ directive is missing both caption and legend.
+ - Don't generate identifiers for indirect or external targets
+ (unless legacy_ids_ is True).
- Generate identifiers for implicit targets (mainly sections) only if
there is a cross-link to the target [#cross-links]_ and no "explicit"
identifier (unless legacy_ids_ is True).
Modified: trunk/docutils/docs/ref/rst/directives.rst
===================================================================
--- trunk/docutils/docs/ref/rst/directives.rst 2026-07-14 13:31:29 UTC (rev 10381)
+++ trunk/docutils/docs/ref/rst/directives.rst 2026-07-14 13:32:05 UTC (rev 10382)
@@ -57,6 +57,7 @@
`specific admonitions`_.
+.. _specific admonitions:
.. _attention:
.. _caution:
.. _danger:
@@ -760,7 +761,7 @@
See Epigraph_ above for an analogous example.
-.. compound:
+.. _compound:
Compound Paragraph
==================
@@ -1152,8 +1153,7 @@
Document Parts
----------------
-.. A ``_contents:`` hyperlink here became id "contents-1"
- (name clash with the generated ToC)
+.. _contents:
Table of Contents
=================
@@ -1795,6 +1795,7 @@
A URI reference to a raw data file to be included.
+.. _class:
.. _class directive:
.. _rst-class:
@@ -2257,8 +2258,7 @@
:alt: example picture
:class: large-pics
- is the recommended syntax alternative to a preceding
- `class directive`_ ::
+ is the recommended syntax alternative to a preceding "class_" directive ::
.. class:: large-pics
.. image:: bild.png
Modified: trunk/docutils/docs/user/config.rst
===================================================================
--- trunk/docutils/docs/user/config.rst 2026-07-14 13:31:29 UTC (rev 10381)
+++ trunk/docutils/docs/user/config.rst 2026-07-14 13:32:05 UTC (rev 10382)
@@ -799,9 +799,10 @@
Keep element identifiers_ compatible to Docutils ≤ 0.22.
If "legacy_ids" is False or with the command line option ``--lazy-ids``,
-the generation of identifiers_ from the `reference names`_ of
-`implicit targets`_ is done after parsing is complete and only
-if required by an internal cross-link [#cross-link]_.
+no identifiers_ are generated for `external <external targets_>`__ and
+`indirect targets`_. The generation of identifiers_ from the
+`reference names`_ of `implicit targets`_ is done after parsing is
+complete and only if required by an internal cross-link [#cross-link]_.
An existing identifier from an `explicit target`_ is re-used instead of
generating an additional identifier for the "implicit" reference name.
@@ -2689,6 +2690,7 @@
.. _explicit target:
.. _explicit targets: ../ref/rst/restructuredtext.html#explicit-hyperlink-targets
.. _explicit internal target: ../ref/rst/restructuredtext.html#internal-hyperlink-targets
+.. _external targets: ../ref/rst/restructuredtext.html#external-hyperlink-targets
.. _field lists: ../ref/rst/restructuredtext.html#field-lists
.. _field names: ../ref/rst/restructuredtext.html#field-names
.. _footnotes: ../ref/rst/restructuredtext.html#footnotes
@@ -2697,6 +2699,7 @@
.. _implicit hyperlink targets:
.. _implicit target:
.. _implicit targets: ../ref/rst/restructuredtext.html#implicit-hyperlink-targets
+.. _indirect targets: ../ref/rst/restructuredtext.html#indirect-hyperlink-targets
.. _interpreted text role: ../ref/rst/restructuredtext.html#interpreted-text
.. _inline markup recognition rules:
../ref/rst/restructuredtext.html#inline-markup-recognition-rules
Modified: trunk/docutils/docutils/nodes.py
===================================================================
--- trunk/docutils/docutils/nodes.py 2026-07-14 13:31:29 UTC (rev 10381)
+++ trunk/docutils/docutils/nodes.py 2026-07-14 13:32:05 UTC (rev 10382)
@@ -2177,7 +2177,9 @@
def note_explicit_target(self, target: Element,
msgnode: Element|None = None) -> None:
self.note_names(target, msgnode, explicit=True)
- self.set_id(target, msgnode)
+ if (getattr(self.settings, "legacy_ids", True)
+ or 'refuri' not in target and 'refname' not in target):
+ self.set_id(target, msgnode)
def note_refname(self, node: Element) -> None:
self.refnames.setdefault(node['refname'], []).append(node)
@@ -2191,7 +2193,9 @@
self.note_refname(target)
def note_anonymous_target(self, target: target) -> None:
- self.set_id(target)
+ if (getattr(self.settings, "legacy_ids", True)
+ or 'refuri' not in target and 'refname' not in target):
+ self.set_id(target)
def note_autofootnote(self, footnote: footnote) -> None:
self.set_id(footnote)
Modified: trunk/docutils/docutils/parsers/__init__.py
===================================================================
--- trunk/docutils/docutils/parsers/__init__.py 2026-07-14 13:31:29 UTC (rev 10381)
+++ trunk/docutils/docutils/parsers/__init__.py 2026-07-14 13:32:05 UTC (rev 10382)
@@ -51,7 +51,8 @@
['--legacy-ids'],
{'action': 'store_true', 'default': True,
'validator': frontend.validate_boolean}),
- ('Generate IDs for implicit targets only if required.',
+ ('Generate IDs for implicit targets only if required; '
+ 'no IDs for external and indirect targets.',
['--lazy-ids'],
{'dest': 'legacy_ids', 'action': 'store_false'}),
('Validate the document tree after parsing.',
@@ -101,7 +102,7 @@
'xml': 'docutils.parsers.docutils_xml',
# 3rd-party Markdown parsers
'myst': 'myst_parser.docutils_',
- # 'pycmark': works out of the box
+ # 'pycmark': works out of the box (with `legacy_ids`)
# dispatcher for 3rd-party Markdown parsers
'commonmark': 'docutils.parsers.commonmark_wrapper',
'markdown': 'docutils.parsers.commonmark_wrapper',
Modified: trunk/docutils/docutils/transforms/references.py
===================================================================
--- trunk/docutils/docutils/transforms/references.py 2026-07-14 13:31:29 UTC (rev 10381)
+++ trunk/docutils/docutils/transforms/references.py 2026-07-14 13:32:05 UTC (rev 10382)
@@ -178,8 +178,12 @@
break
else:
if not target['ids']:
- # Propagated target.
- target = self.document.ids[target['refid']]
+ if 'refid' in target: # propagated target
+ target = self.document.ids[target['refid']]
+ elif 'refname' in target: # indirect target
+ target = self.document.names[target['refname']]
+ else:
+ self.document.set_id(target)
continue
ref['refid'] = target['ids'][0]
self.document.note_refid(ref)
@@ -254,13 +258,17 @@
reftarget = self.document.ids.get(refid)
else:
reftarget = self.document.names.get(refname)
- refid = self.document.nameids.get(refname)
- if reftarget and not refid:
- refid = self.document.set_id(reftarget)
+ if getattr(self.document.settings, "legacy_ids", True):
+ refid = self.document.nameids.get(refname)
if not reftarget:
self.nonexistent_indirect_target(target)
return
- reftarget.note_referenced_by(id=refid)
+
+ if refid:
+ reftarget.note_referenced_by(id=refid)
+ else:
+ reftarget.note_referenced_by(name=refname)
+
if (isinstance(reftarget, nodes.target)
and not reftarget.resolved
and reftarget.hasattr('refname')):
@@ -277,12 +285,12 @@
elif reftarget.hasattr('refid'):
target['refid'] = reftarget['refid']
self.document.note_refid(target)
- elif reftarget['ids']:
+ else: # internal target
+ if not refid:
+ refid = self.document.set_id(reftarget)
target['refid'] = refid
self.document.note_refid(target)
- else:
- self.nonexistent_indirect_target(target)
- return
+ # Mark target as resolved:
if refname is not None:
del target['refname']
target.resolved = True
@@ -1003,9 +1011,9 @@
elif target['ids']:
naming = target['ids'][0]
else:
- # Hack: Propagated targets always have their refid
- # attribute set.
- naming = target['refid']
+ # Propagated target: "ids" and "names" attributes moved
+ # to the node indicated by "refid" or "refname".
+ naming = target.get('refid') or target.get('refname', '???')
self.document.reporter.info(
f'Hyperlink target "{naming}" is not referenced.',
base_node=target)
Modified: trunk/docutils/test/data/help/docutils.rst
===================================================================
--- trunk/docutils/test/data/help/docutils.rst 2026-07-14 13:31:29 UTC (rev 10381)
+++ trunk/docutils/test/data/help/docutils.rst 2026-07-14 13:32:05 UTC (rev 10382)
@@ -90,7 +90,8 @@
Maximal number of characters in an input line.
(default 10 000)
--legacy-ids Keep IDs backwards compatible. (default)
---lazy-ids Generate IDs for implicit targets only if required.
+--lazy-ids Generate IDs for implicit targets only if required; no
+ IDs for external and indirect targets.
--validate Validate the document tree after parsing.
--no-validation Do not validate the document tree. (default)
Modified: trunk/docutils/test/data/help/rst2html.rst
===================================================================
--- trunk/docutils/test/data/help/rst2html.rst 2026-07-14 13:31:29 UTC (rev 10381)
+++ trunk/docutils/test/data/help/rst2html.rst 2026-07-14 13:32:05 UTC (rev 10382)
@@ -91,7 +91,8 @@
Maximal number of characters in an input line.
(default 10 000)
--legacy-ids Keep IDs backwards compatible. (default)
---lazy-ids Generate IDs for implicit targets only if required.
+--lazy-ids Generate IDs for implicit targets only if required; no
+ IDs for external and indirect targets.
--validate Validate the document tree after parsing.
--no-validation Do not validate the document tree. (default)
Modified: trunk/docutils/test/data/help/rst2latex.rst
===================================================================
--- trunk/docutils/test/data/help/rst2latex.rst 2026-07-14 13:31:29 UTC (rev 10381)
+++ trunk/docutils/test/data/help/rst2latex.rst 2026-07-14 13:32:05 UTC (rev 10382)
@@ -91,7 +91,8 @@
Maximal number of characters in an input line.
(default 10 000)
--legacy-ids Keep IDs backwards compatible. (default)
---lazy-ids Generate IDs for implicit targets only if required.
+--lazy-ids Generate IDs for implicit targets only if required; no
+ IDs for external and indirect targets.
--validate Validate the document tree after parsing.
--no-validation Do not validate the document tree. (default)
Modified: trunk/docutils/test/functional/expected/standalone_rst_pseudoxml.txt
===================================================================
--- trunk/docutils/test/functional/expected/standalone_rst_pseudoxml.txt 2026-07-14 13:31:29 UTC (rev 10381)
+++ trunk/docutils/test/functional/expected/standalone_rst_pseudoxml.txt 2026-07-14 13:32:05 UTC (rev 10382)
@@ -497,8 +497,8 @@
<reference refid="subtitle">
subtitle
.
- <target anonymous="1" ids="target-1" refuri="http://www.python.org/">
- <target anonymous="1" ids="target-2" refuri="https://docutils.sourceforge.io/">
+ <target anonymous="1" refuri="http://www.python.org/">
+ <target anonymous="1" refuri="https://docutils.sourceforge.io/">
<paragraph>
The default role for interpreted text is
<title_reference>
@@ -1054,7 +1054,7 @@
<reference anonymous="1" refid="label">
hyperlink reference
.
- <target anonymous="1" ids="target-3" refid="label">
+ <target anonymous="1" refid="label">
<footnote auto="1" backrefs="footnote-reference-2" ids="footnote-2" names="3">
<label>
3
@@ -1142,7 +1142,7 @@
<footnote_reference auto="1" ids="footnote-reference-11" refid="footnote-6">
5
".
- <target ids="python" names="python" refuri="http://www.python.org/">
+ <target names="python" refuri="http://www.python.org/">
<paragraph>
Targets may be indirect and anonymous. Thus
<reference anonymous="1" refid="another-target">
@@ -1152,7 +1152,7 @@
<reference refid="another-target">
Targets
section.
- <target anonymous="1" ids="target-4" refid="another-target">
+ <target anonymous="1" refid="another-target">
<paragraph>
Here's a
<problematic ids="problematic-2" refid="system-message-4">
@@ -1265,7 +1265,7 @@
<footnote_reference auto="1" ids="footnote-reference-16" refid="footnote-9">
8
.
- <target anonymous="1" ids="target-5" refuri="https://docutils.sourceforge.io/docs/ref/rst/directives.html">
+ <target anonymous="1" refuri="https://docutils.sourceforge.io/docs/ref/rst/directives.html">
<section ids="document-parts" names="document\ parts">
<title auto="1" refid="toc-entry-43">
<generated classes="sectnum">
@@ -1627,7 +1627,7 @@
And, by the way...
<paragraph>
You can make up your own admonition too.
- <target ids="docutils" names="docutils" refuri="https://docutils.sourceforge.io/">
+ <target names="docutils" refuri="https://docutils.sourceforge.io/">
<section ids="topics-sidebars-and-rubrics" names="topics,\ sidebars,\ and\ rubrics">
<title auto="1" refid="toc-entry-47">
<generated classes="sectnum">
@@ -2004,7 +2004,7 @@
<inline classes="ln">
2
.. footer:: Document footer
- <target ids="pygments" names="pygments" refuri="http://pygments.org/">
+ <target names="pygments" refuri="http://pygments.org/">
<section ids="meta" names="meta">
<title auto="1" refid="toc-entry-53">
<generated classes="sectnum">
@@ -2019,7 +2019,7 @@
9
is used to specify metadata to be stored in,
e.g., HTML META tags or ODT file properties.
- <target anonymous="1" ids="target-6" refuri="https://docutils.sourceforge.io/docs/ref/rst/directives.html#metadata">
+ <target anonymous="1" refuri="https://docutils.sourceforge.io/docs/ref/rst/directives.html#metadata">
<section ids="substitution-definitions" names="substitution\ definitions">
<title auto="1" refid="toc-entry-34">
<generated classes="sectnum">
Modified: trunk/docutils/test/test_parsers/test_rst/test_directives/test_include.py
===================================================================
--- trunk/docutils/test/test_parsers/test_rst/test_directives/test_include.py 2026-07-14 13:31:29 UTC (rev 10381)
+++ trunk/docutils/test/test_parsers/test_rst/test_directives/test_include.py 2026-07-14 13:32:05 UTC (rev 10382)
@@ -44,7 +44,7 @@
settings = get_default_settings(Parser)
settings.warning_stream = ''
settings.halt_level = 5
- settings.legacy_ids = False
+ settings.legacy_ids = False # except for pycmark (see below)
for name, cases in totest.items():
if name == 'with transforms':
continue # see test_publish() below
@@ -55,7 +55,10 @@
self.skipTest('no markdown parser available')
if name == 'include_parsed_code' and not with_pygments:
self.skipTest('syntax highlight requires pygments')
- document = new_document('test data', settings.copy())
+ mysettings = settings.copy()
+ if name == 'include_markdown':
+ mysettings.legacy_ids = True # keep pycmark happy
+ document = new_document('test data', mysettings)
parser.parse(case_input, document)
output = document.pformat()
self.assertEqual(case_expected, output)
@@ -1567,7 +1570,7 @@
<document source="test data">
<paragraph>
Include Markdown source.
- <section depth="1">
+ <section depth="1" ids="section-1">
<title>
Title 1
<paragraph>
Modified: trunk/docutils/test/test_parsers/test_rst/test_targets.py
===================================================================
--- trunk/docutils/test/test_parsers/test_rst/test_targets.py 2026-07-14 13:31:29 UTC (rev 10381)
+++ trunk/docutils/test/test_parsers/test_rst/test_targets.py 2026-07-14 13:32:05 UTC (rev 10382)
@@ -86,11 +86,11 @@
<document source="test data">
<paragraph>
External hyperlink targets:
- <target ids="one-liner" names="one-liner" refuri="http://structuredtext.sourceforge.net">
- <target ids="starts-on-this-line" names="starts-on-this-line" refuri="http://structuredtext.sourceforge.net">
- <target ids="entirely-below" names="entirely-below" refuri="http://structuredtext.sourceforge.net">
- <target ids="escaped-whitespace" names="escaped-whitespace" refuri="http://example.org/a path with spaces.html">
- <target ids="not-indirect" names="not-indirect" refuri="uri_">
+ <target names="one-liner" refuri="http://structuredtext.sourceforge.net">
+ <target names="starts-on-this-line" refuri="http://structuredtext.sourceforge.net">
+ <target names="entirely-below" refuri="http://structuredtext.sourceforge.net">
+ <target names="escaped-whitespace" refuri="http://example.org/a path with spaces.html">
+ <target names="not-indirect" refuri="uri_">
"""],
["""\
Indirect hyperlink targets:
@@ -103,8 +103,8 @@
<document source="test data">
<paragraph>
Indirect hyperlink targets:
- <target ids="target1" names="target1" refname="reference">
- <target ids="target2" names="target2" refname="phrase-link reference">
+ <target names="target1" refname="reference">
+ <target names="target2" refname="phrase-link reference">
"""],
["""\
.. _a long target name:
@@ -156,7 +156,7 @@
<document source="test data">
<paragraph>
External hyperlink:
- <target ids="target" names="target" refuri="http://www.python.org/">
+ <target names="target" refuri="http://www.python.org/">
"""],
["""\
.. _email: jd...@ex...
@@ -166,8 +166,8 @@
""",
"""\
<document source="test data">
- <target ids="email" names="email" refuri="mailto:jd...@ex...">
- <target ids="multi-line-email" names="multi-line\\ email" refuri="mailto:jd...@ex...">
+ <target names="email" refuri="mailto:jd...@ex...">
+ <target names="multi-line\\ email" refuri="mailto:jd...@ex...">
"""],
["""\
Malformed target:
@@ -189,7 +189,7 @@
malformed hyperlink target.
<paragraph>
Target beginning with an underscore:
- <target ids="target" names="_target" refuri="OK">
+ <target names="_target" refuri="OK">
"""],
["""\
Duplicate external targets (different URIs):
@@ -202,11 +202,11 @@
<document source="test data">
<paragraph>
Duplicate external targets (different URIs):
- <target dupnames="target" ids="target" refuri="first">
+ <target dupnames="target" refuri="first">
<system_message level="2" line="5" source="test data" type="WARNING">
<paragraph>
Duplicate explicit target name: "target".
- <target dupnames="target" ids="target-1" refuri="second">
+ <target dupnames="target" refuri="second">
"""],
["""\
Duplicate external targets (same URIs):
@@ -219,11 +219,11 @@
<document source="test data">
<paragraph>
Duplicate external targets (same URIs):
- <target ids="target" names="target" refuri="first">
+ <target names="target" refuri="first">
<system_message level="1" line="5" source="test data" type="INFO">
<paragraph>
Duplicate name "target" for external target "first".
- <target dupnames="target" ids="target-1" refuri="first">
+ <target dupnames="target" refuri="first">
"""],
["""\
Duplicate external targets (embedded/explicit, same URIs):
@@ -250,7 +250,7 @@
<system_message level="1" line="7" source="test data" type="INFO">
<paragraph>
Duplicate name "example" for external target "example.rst".
- <target dupnames="example" ids="example-1" refuri="example.rst">
+ <target dupnames="example" refuri="example.rst">
"""],
["""\
Duplicate indirect _`targets` (same refname):
@@ -268,11 +268,11 @@
<target ids="targets" names="targets">
targets
(same refname):
- <target ids="link" names="link" refname="targets">
+ <target names="link" refname="targets">
<system_message level="1" line="5" source="test data" type="INFO">
<paragraph>
Duplicate name "link" for external target "targets".
- <target dupnames="link" ids="link-1" refname="targets">
+ <target dupnames="link" refname="targets">
<paragraph>
do not conflict. The reference name can be used in a \n\
<reference refname="link">
@@ -477,15 +477,15 @@
<system_message level="2" line="16" source="test data" type="WARNING">
<paragraph>
Duplicate explicit target name: "target".
- <target dupnames="target" ids="target-3" refuri="Explicit_external_target">
+ <target dupnames="target" refuri="Explicit_external_target">
<line_block>
<line>
Do not insert <system_message> element for duplicate
<line>
- <target dupnames="target" ids="target-4">
+ <target dupnames="target" ids="target-3">
target
, if this results in an invalid doctree.
- <rubric dupnames="target" ids="target-5">
+ <rubric dupnames="target" ids="target-4">
directive with target
<field_list>
<field>
@@ -496,7 +496,7 @@
with
<field>
<field_name>
- <target dupnames="target" ids="target-6">
+ <target dupnames="target" ids="target-5">
target
<field_body>
<paragraph>
@@ -523,8 +523,8 @@
<system_message level="2" line="3" source="test data" type="WARNING">
<paragraph>
malformed hyperlink target.
- <target ids="escaped-colon" names="escaped\\ colon:" refuri="OK">
- <target ids="unescaped-colon-quoted" names="unescaped\\ colon,\\ quoted:" refuri="OK">
+ <target names="escaped\\ colon:" refuri="OK">
+ <target names="unescaped\\ colon,\\ quoted:" refuri="OK">
"""],
])
@@ -768,7 +768,7 @@
<document source="test data">
<paragraph>
Anonymous external hyperlink target:
- <target anonymous="1" ids="target-1" refuri="http://w3c.org/">
+ <target anonymous="1" refuri="http://w3c.org/">
"""],
["""\
Anonymous external hyperlink target:
@@ -779,7 +779,7 @@
<document source="test data">
<paragraph>
Anonymous external hyperlink target:
- <target anonymous="1" ids="target-1" refuri="http://w3c.org/">
+ <target anonymous="1" refuri="http://w3c.org/">
"""],
["""\
Anonymous indirect hyperlink target:
@@ -790,7 +790,7 @@
<document source="test data">
<paragraph>
Anonymous indirect hyperlink target:
- <target anonymous="1" ids="target-1" refname="reference">
+ <target anonymous="1" refname="reference">
"""],
["""\
Anonymous external hyperlink target, not indirect:
@@ -803,8 +803,8 @@
<document source="test data">
<paragraph>
Anonymous external hyperlink target, not indirect:
- <target anonymous="1" ids="target-1" refuri="uri_">
- <target anonymous="1" ids="target-2" refuri="thisURIendswithanunderscore_">
+ <target anonymous="1" refuri="uri_">
+ <target anonymous="1" refuri="thisURIendswithanunderscore_">
"""],
["""\
Anonymous indirect hyperlink targets:
@@ -817,8 +817,8 @@
<document source="test data">
<paragraph>
Anonymous indirect hyperlink targets:
- <target anonymous="1" ids="target-1" refname="reference">
- <target anonymous="1" ids="target-2" refname="a very long reference">
+ <target anonymous="1" refname="reference">
+ <target anonymous="1" refname="a very long reference">
"""],
["""\
Mixed anonymous & named indirect hyperlink targets:
@@ -839,19 +839,19 @@
<document source="test data">
<paragraph>
Mixed anonymous & named indirect hyperlink targets:
- <target anonymous="1" ids="target-1" refname="reference">
- <target anonymous="1" ids="target-2" refname="reference">
- <target anonymous="1" ids="target-3" refname="reference">
- <target ids="target1" names="target1" refname="reference">
+ <target anonymous="1" refname="reference">
+ <target anonymous="1" refname="reference">
+ <target anonymous="1" refname="reference">
+ <target names="target1" refname="reference">
<system_message level="2" line="7" source="test data" type="WARNING">
<paragraph>
Explicit markup ends without a blank line; unexpected unindent.
<paragraph>
no blank line
- <target ids="target2" names="target2" refname="reference">
- <target anonymous="1" ids="target-4" refname="reference">
- <target anonymous="1" ids="target-5" refname="reference">
- <target anonymous="1" ids="target-6" refname="reference">
+ <target names="target2" refname="reference">
+ <target anonymous="1" refname="reference">
+ <target anonymous="1" refname="reference">
+ <target anonymous="1" refname="reference">
<system_message level="2" line="13" source="test data" type="WARNING">
<paragraph>
Explicit markup ends without a blank line; unexpected unindent.
Modified: trunk/docutils/test/test_transforms/test_hyperlinks.py
===================================================================
--- trunk/docutils/test/test_transforms/test_hyperlinks.py 2026-07-14 13:31:29 UTC (rev 10381)
+++ trunk/docutils/test/test_transforms/test_hyperlinks.py 2026-07-14 13:32:05 UTC (rev 10382)
@@ -594,7 +594,8 @@
"""],
])
-totest['explicit hyperlinks legacy'] = ({'legacy_ids': True}, [
+# explicit internal hyperlinks are not affected by "legacy_ids"
+totest['explicit internal hyperlinks (legacy_ids)'] = ({'legacy_ids': True}, [
["""\
.. _internal hyperlink:
@@ -643,24 +644,6 @@
The results of the transform are not visible at the XML level.
"""],
["""\
-.. _chained:
-__ http://anonymous
-
-Anonymous__ and chained_ both refer to the same URI.
-""",
-"""\
-<document source="test data">
- <target refid="chained">
- <target anonymous="1" ids="target-1 chained" names="chained" refuri="http://anonymous">
- <paragraph>
- <reference anonymous="1" refuri="http://anonymous">
- Anonymous
- and \n\
- <reference refuri="http://anonymous">
- chained
- both refer to the same URI.
-"""],
-["""\
.. _a:
.. _b:
@@ -730,125 +713,209 @@
b
"""],
["""\
-.. _external hyperlink: http://uri
+Unknown reference_.
+""",
+"""\
+<document source="test data">
+ <paragraph>
+ Unknown \n\
+ <problematic ids="problematic-1" refid="system-message-1">
+ reference_
+ .
+ <system_message backrefs="problematic-1" ids="system-message-1" level="3" line="1" source="test data" type="ERROR">
+ <paragraph>
+ Unknown target name: "reference".
+"""],
+["""\
+Duplicate manual footnote labels, with reference ([1]_):
-`External hyperlink`_ reference.
+.. [1] Footnote.
+
+.. [1] Footnote.
""",
"""\
<document source="test data">
- <target ids="external-hyperlink" names="external\\ hyperlink" refuri="http://uri">
<paragraph>
- <reference refuri="http://uri">
- External hyperlink
- reference.
+ Duplicate manual footnote labels, with reference (
+ <problematic ids="footnote-reference-1" refid="system-message-1">
+ [1]_
+ ):
+ <footnote dupnames="1" ids="footnote-1">
+ <label>
+ 1
+ <paragraph>
+ Footnote.
+ <footnote dupnames="1" ids="footnote-2">
+ <label>
+ 1
+ <system_message backrefs="footnote-2" level="2" line="5" source="test data" type="WARNING">
+ <paragraph>
+ Duplicate explicit target name: "1".
+ <paragraph>
+ Footnote.
+ <system_message backrefs="footnote-reference-1" ids="system-message-1" level="3" line="1" source="test data" type="ERROR">
+ <paragraph>
+ Duplicate target name, cannot be used as a unique reference: "1".
"""],
+])
+
+totest['explicit internal hyperlinks (lazy_ids)'] = ({'legacy_ids': False},
+ # all samples compile as before
+ totest['explicit internal hyperlinks (legacy_ids)'][1])
+
+# implicit, indirect, and external hyperlinks get IDs with "legacy_ids"
+totest['various hyperlinks (legacy_ids)'] = ({'legacy_ids': True}, [
["""\
-.. _external hyperlink: http://uri
-.. _indirect target: `external hyperlink`_
+.. contents:: Table of Contents
+.. _indirect reference to the table of contents: `table of contents`_
+
+Section
+=======
+
+Testing an `indirect reference to the table of contents`_.
""",
"""\
<document source="test data">
- <target ids="external-hyperlink" names="external\\ hyperlink" refuri="http://uri">
- <target ids="indirect-target" names="indirect\\ target" refuri="http://uri">
- <system_message level="1" line="2" source="test data" type="INFO">
+ <topic classes="contents" ids="table-of-contents" names="table\\ of\\ contents">
+ <title>
+ Table of Contents
+ <bullet_list>
+ <list_item>
+ <paragraph>
+ <reference ids="toc-entry-1" refid="section">
+ Section
+ <target ids="indirect-reference-to-the-table-of-contents" names="indirect\\ reference\\ to\\ the\\ table\\ of\\ contents" refid="table-of-contents">
+ <section ids="section" names="section">
+ <title refid="toc-entry-1">
+ Section
<paragraph>
- Hyperlink target "indirect target" is not referenced.
+ Testing an \n\
+ <reference refid="table-of-contents">
+ indirect reference to the table of contents
+ .
"""],
["""\
-.. _chained:
-.. _external hyperlink: http://uri
+.. _explicit target:
-`External hyperlink`_ reference
-and a chained_ reference too.
+Title
+-----
+
+Let's reference the `explicit target`_ to avoid an irrelevant error.
""",
"""\
<document source="test data">
- <target refid="chained">
- <target ids="external-hyperlink chained" names="external\\ hyperlink chained" refuri="http://uri">
- <paragraph>
- <reference refuri="http://uri">
- External hyperlink
- reference
- and a \n\
- <reference refuri="http://uri">
- chained
- reference too.
+ <target refid="explicit-target">
+ <section ids="title explicit-target" names="title explicit\\ target">
+ <title>
+ Title
+ <paragraph>
+ Let's reference the \n\
+ <reference refid="explicit-target">
+ explicit target
+ to avoid an irrelevant error.
"""],
["""\
-.. _external hyperlink: http://uri
-.. _indirect hyperlink: `external hyperlink`_
+target1_ should be an alias of target2_, not the Title.
-`Indirect hyperlink`_ reference.
+.. _target1:
+.. _target2: URI
+
+Title
+=====
""",
"""\
<document source="test data">
- <target ids="external-hyperlink" names="external\\ hyperlink" refuri="http://uri">
- <target ids="indirect-hyperlink" names="indirect\\ hyperlink" refuri="http://uri">
<paragraph>
- <reference refuri="http://uri">
- Indirect hyperlink
- reference.
+ <reference refuri="URI">
+ target1
+ should be an alias of \n\
+ <reference refuri="URI">
+ target2
+ , not the Title.
+ <target refid="target1">
+ <target ids="target2 target1" names="target2 target1" refuri="URI">
+ <section ids="title" names="title">
+ <title>
+ Title
"""],
["""\
-.. _external hyperlink: http://uri
-.. _chained:
-.. _indirect hyperlink: `external hyperlink`_
+foo
+---
-Chained_ `indirect hyperlink`_ reference.
+With legacy_ids = True, an explicit target _`foo` overrides a
+homonymous implicit target but gets a "diambiguated" identifier.
+
+The reference foo_ points to the explicit target.
+Referencing from an external document requires the
+non-obvious fragment identifier "#foo-1".
""",
"""\
<document source="test data">
- <target ids="external-hyperlink" names="external\\ hyperlink" refuri="http://uri">
- <target refuri="http://uri">
- <target ids="indirect-hyperlink chained" names="indirect\\ hyperlink chained" refuri="http://uri">
- <paragraph>
- <reference refuri="http://uri">
- Chained
- \n\
- <reference refuri="http://uri">
- indirect hyperlink
- reference.
+ <section dupnames="foo" ids="foo">
+ <title>
+ foo
+ <system_message backrefs="foo-1" level="1" line="5" source="test data" type="INFO">
+ <paragraph>
+ Target name overrides implicit target name "foo".
+ <paragraph>
+ With legacy_ids = True, an explicit target \n\
+ <target ids="foo-1" names="foo">
+ foo
+ overrides a
+ homonymous implicit target but gets a "diambiguated" identifier.
+ <paragraph>
+ The reference \n\
+ <reference refid="foo-1">
+ foo
+ points to the explicit target.
+ Referencing from an external document requires the
+ non-obvious fragment identifier "#foo-1".
"""],
["""\
-.. __: http://full
-__
-__ http://simplified
-.. _external: http://indirect.external
-__ external_
-__
+foo
+---
-`Full syntax anonymous external hyperlink reference`__,
-`chained anonymous external reference`__,
-`simplified syntax anonymous external hyperlink reference`__,
-`indirect anonymous hyperlink reference`__,
-`internal anonymous hyperlink reference`__.
+If an implicit target precedes a homonymous explicit target _`foo`,
+the explicit target takes over the reference name but not the identifier.
+
+The reference foo_ points to the explicit target. However, referencing from
+an external document requires the non-obvious fragment identifier "#foo-1".
""",
"""\
<document source="test data">
- <target anonymous="1" ids="target-1" refuri="http://full">
- <target anonymous="1" refid="target-2">
- <target anonymous="1" ids="target-3 target-2" refuri="http://simplified">
- <target ids="external" names="external" refuri="http://indirect.external">
- <target anonymous="1" ids="target-4" refuri="http://indirect.external">
- <target anonymous="1" refid="target-5">
- <paragraph ids="target-5">
- <reference anonymous="1" refuri="http://full">
- Full syntax anonymous external hyperlink reference
- ,
- <reference anonymous="1" refuri="http://simplified">
- chained anonymous external reference
- ,
- <reference anonymous="1" refuri="http://simplified">
- simplified syntax anonymous external hyperlink reference
- ,
- <reference anonymous="1" refuri="http://indirect.external">
- indirect anonymous hyperlink reference
- ,
- <reference anonymous="1" refid="target-5">
- internal anonymous hyperlink reference
- .
+ <section dupnames="foo" ids="foo">
+ <title>
+ foo
+ <system_message backrefs="foo-1" level="1" line="5" source="test data" type="INFO">
+ <paragraph>
+ Target name overrides implicit target name "foo".
+ <paragraph>
+ If an implicit target precedes a homonymous explicit target \n\
+ <target ids="foo-1" names="foo">
+ foo
+ ,
+ the explicit target takes over the reference name but not the identifier.
+ <paragraph>
+ The reference \n\
+ <reference refid="foo-1">
+ foo
+ points to the explicit target. However, referencing from
+ an external document requires the non-obvious fragment identifier "#foo-1".
"""],
["""\
+.. _external hyperlink: http://uri
+
+`External hyperlink`_ reference.
+""",
+"""\
+<document source="test data">
+ <target ids="external-hyperlink" names="external\\ hyperlink" refuri="http://uri">
+ <paragraph>
+ <reference refuri="http://uri">
+ External hyperlink
+ reference.
+"""],
+["""\
Duplicate external target_'s (different URIs):
.. _target: first
@@ -889,29 +956,73 @@
<target dupnames="target" ids="target-1" refuri="second">
"""],
["""\
-Several__ anonymous__ hyperlinks__, but not enough targets.
+.. _chained:
+.. _external hyperlink: http://uri
-__ http://example.org
+`External hyperlink`_ reference
+and a chained_ reference too.
""",
"""\
<document source="test data">
+ <target refid="chained">
+ <target ids="external-hyperlink chained" names="external\\ hyperlink chained" refuri="http://uri">
<paragraph>
- <problematic ids="problematic-1" refid="system-message-1">
- Several__
- \n\
- <problematic ids="problematic-2" refid="system-message-1">
- anonymous__
- \n\
- <problematic ids="problematic-3" refid="system-message-1">
- hyperlinks__
- , but not enough targets.
- <target anonymous="1" ids="target-1" refuri="http://example.org">
- <system_message backrefs="problematic-1 problematic-2 problematic-3" ids="system-message-1" level="3" source="test data" type="ERROR">
+ <reference refuri="http://uri">
+ External hyperlink
+ reference
+ and a \n\
+ <reference refuri="http://uri">
+ chained
+ reference too.
+"""],
+["""\
+.. _external hyperlink: http://uri
+.. _indirect target: `external hyperlink`_
+""",
+"""\
+<document source="test data">
+ <target ids="external-hyperlink" names="external\\ hyperlink" refuri="http://uri">
+ <target ids="indirect-target" names="indirect\\ target" refuri="http://uri">
+ <system_message level="1" line="2" source="test data" type="INFO">
<paragraph>
- Anonymous hyperlink mismatch: 3 references but 1 targets.
- See "backrefs" attribute for IDs.
+ Hyperlink target "indirect target" is not referenced.
"""],
["""\
+.. _external hyperlink: http://uri
+.. _indirect hyperlink: `external hyperlink`_
+
+`Indirect hyperlink`_ reference.
+""",
+"""\
+<document source="test data">
+ <target ids="external-hyperlink" names="external\\ hyperlink" refuri="http://uri">
+ <target ids="indirect-hyperlink" names="indirect\\ hyperlink" refuri="http://uri">
+ <paragraph>
+ <reference refuri="http://uri">
+ Indirect hyperlink
+ reference.
+"""],
+["""\
+.. _external hyperlink: http://uri
+.. _chained:
+.. _indirect hyperlink: `external hyperlink`_
+
+Chained_ `indirect hyperlink`_ reference.
+""",
+"""\
+<document source="test data">
+ <target ids="external-hyperlink" names="external\\ hyperlink" refuri="http://uri">
+ <target refuri="http://uri">
+ <target ids="indirect-hyperlink chained" names="indirect\\ hyperlink chained" refuri="http://uri">
+ <paragraph>
+ <reference refuri="http://uri">
+ Chained
+ \n\
+ <reference refuri="http://uri">
+ indirect hyperlink
+ reference.
+"""],
+["""\
.. _external: http://uri
.. _indirect: external_
.. _internal:
@@ -1036,57 +1147,89 @@
to an image with target (sic!).
"""],
["""\
-Unknown reference_.
+.. __: http://full
+__
+__ http://simplified
+.. _external: http://indirect.external
+__ external_
+__
+
+`Full syntax anonymous external hyperlink reference`__,
+`chained anonymous external reference`__,
+`simplified syntax anonymous external hyperlink reference`__,
+`indirect anonymous hyperlink reference`__,
+`internal anonymous hyperlink reference`__.
""",
"""\
<document source="test data">
- <paragraph>
- Unknown \n\
- <problematic ids="problematic-1" refid="system-message-1">
- reference_
+ <target anonymous="1" ids="target-1" refuri="http://full">
+ <target anonymous="1" refid="target-2">
+ <target anonymous="1" ids="target-3 target-2" refuri="http://simplified">
+ <target ids="external" names="external" refuri="http://indirect.external">
+ <target anonymous="1" ids="target-4" refuri="http://indirect.external">
+ <target anonymous="1" refid="target-5">
+ <paragraph ids="target-5">
+ <reference anonymous="1" refuri="http://full">
+ Full syntax anonymous external hyperlink reference
+ ,
+ <reference anonymous="1" refuri="http://simplified">
+ chained anonymous external reference
+ ,
+ <reference anonymous="1" refuri="http://simplified">
+ simplified syntax anonymous external hyperlink reference
+ ,
+ <reference anonymous="1" refuri="http://indirect.external">
+ indirect anonymous hyperlink reference
+ ,
+ <reference anonymous="1" refid="target-5">
+ internal anonymous hyperlink reference
.
- <system_message backrefs="problematic-1" ids="system-message-1" level="3" line="1" source="test data" type="ERROR">
- <paragraph>
- Unknown target name: "reference".
"""],
["""\
-Duplicate manual footnote labels, with reference ([1]_):
+.. _chained:
+__ http://anonymous
-.. [1] Footnote.
+Anonymous__ and chained_ both refer to the same URI.
+""",
+"""\
+<document source="test data">
+ <target refid="chained">
+ <target anonymous="1" ids="target-1 chained" names="chained" refuri="http://anonymous">
+ <paragraph>
+ <reference anonymous="1" refuri="http://anonymous">
+ Anonymous
+ and \n\
+ <reference refuri="http://anonymous">
+ chained
+ both refer to the same URI.
+"""],
+["""\
+Several__ anonymous__ hyperlinks__, but not enough targets.
-.. [1] Footnote.
+__ http://example.org
""",
"""\
<document source="test data">
<paragraph>
- Duplicate manual footnote labels, with reference (
- <problematic ids="footnote-reference-1" refid="system-message-1">
- [1]_
- ):
- <footnote dupnames="1" ids="footnote-1">
- <label>
- 1
+ <problematic ids="problematic-1" refid="system-message-1">
+ Several__
+ \n\
+ <problematic ids="problematic-2" refid="system-message-1">
+ anonymous__
+ \n\
+ <problematic ids="problematic-3" refid="system-message-1">
+ hyperlinks__
+ , but not enough targets.
+ <target anonymous="1" ids="target-1" refuri="http://example.org">
+ <system_message backrefs="problematic-1 problematic-2 problematic-3" ids="system-message-1" level="3" source="test data" type="ERROR">
<paragraph>
- Footnote.
- <footnote dupnames="1" ids="footnote-2">
- <label>
- 1
- <system_message backrefs="footnote-2" level="2" line="5" source="test data" type="WARNING">
- <paragraph>
- Duplicate explicit target name: "1".
- <paragraph>
- Footnote.
- <system_message backrefs="footnote-reference-1" ids="system-message-1" level="3" line="1" source="test data" type="ERROR">
- <paragraph>
- Duplicate target name, cannot be used as a unique reference: "1".
+ Anonymous hyperlink mismatch: 3 references but 1 targets.
+ See "backrefs" attribute for IDs.
"""],
])
-totest['explicit hyperlinks'] = ({'legacy_ids': False},
- # all samples compile as before
- totest['explicit hyperlinks legacy'][1])
-
-totest['implicit hyperlinks legacy'] = ({'legacy_ids': True}, [
+# implicit, indirect, and external hyperlinks get *no* IDs with "lazy_ids"
+totest['various hyperlinks (lazy_ids)'] = ({'legacy_ids': False}, [
["""\
.. contents:: Table of Contents
.. _indirect reference to the table of contents: `table of contents`_
@@ -1106,7 +1249,7 @@
<paragraph>
<reference ids="toc-entry-1" refid="section">
Section
- <target ids="indirect-reference-to-the-table-of-contents" names="indirect\\ reference\\ to\\ the\\ table\\ of\\ contents" refid="table-of-contents">
+ <target names="indirect\\ reference\\ to\\ the\\ table\\ of\\ contents" refid="table-of-contents">
<section ids="section" names="section">
<title refid="toc-entry-1">
Section
@@ -1122,22 +1265,25 @@
Title
-----
-Let's reference it (`explicit target`_) to avoid an irrelevant error.
+References to the section (title_) use the ID from the `explicit target`_.
""",
"""\
<document source="test data">
<target refid="explicit-target">
- <section ids="title explicit-target" names="title explicit\\ target">
+ <section ids="explicit-target" names="title explicit\\ target">
<title>
Title
<paragraph>
- Let's reference it (
+ References to the section (
<reference refid="explicit-target">
+ title
+ ) use the ID from the \n\
+ <reference refid="explicit-target">
explicit target
- ) to avoid an irrelevant error.
+ .
"""],
["""\
-target1_ should refer to target2_, not the Title.
+target1_ should be an alias of target2_, not the Title.
.. _target1:
.. _target2: URI
@@ -1150,185 +1296,274 @@
<paragraph>
<reference refuri="URI">
target1
- should refer to \n\
+ should be an alias of \n\
<reference refuri="URI">
target2
, not the Title.
<target refid="target1">
- <target ids="target2 target1" names="target2 target1" refuri="URI">
- <section ids="title" names="title">
+ <target ids="target1" names="target2 target1" refuri="URI">
+ <section names="title">
<title>
Title
"""],
["""\
-An explicit target _`foo` overrides a homonymous implicit target.
-
foo
---
+With legacy_ids = False, an explicit target _`foo` takes over the
+reference name and identifier of a homonymous implicit target.
+
The reference foo_ points to the explicit target.
+Referencing from an external document can be done
+using the matching fragment identifier "#foo".
""",
"""\
<document source="test data">
- <paragraph>
- An explicit target \n\
- <target ids="foo" names="foo">
- foo
- overrides a homonymous implicit target.
- <section dupnames="foo" ids="foo-1">
+ <section dupnames="foo">
<title>
foo
- <system_message backrefs="foo-1" level="1" line="4" source="test data" type="INFO">
+ <system_message backrefs="foo" level="1" line="5" source="test data" type="INFO">
<paragraph>
- Duplicate implicit target name: "foo".
+ Target name overrides implicit target name "foo".
<paragraph>
+ With legacy_ids = False, an explicit target \n\
+ <target ids="foo" names="foo">
+ foo
+ takes over the
+ reference name and identifier of a homonymous implicit target.
+ <paragraph>
The reference \n\
<reference refid="foo">
foo
points to the explicit target.
+ Referencing from an external document can be done
+ using the matching fragment identifier "#foo".
"""],
["""\
-foo
----
+.. _external hyperlink: http://uri
-If an implicit target precedes a homonymous explicit target _`foo`,
-the explicit target takes over the reference name but not the identifier.
+`External hyperlink`_ reference.
+""",
+"""\
+<document source="test data">
+ <target names="external\\ hyperlink" refuri="http://uri">
+ <paragraph>
+ <reference refuri="http://uri">
+ External hyperlink
+ reference.
+"""],
+["""\
+Duplicate external target_'s (different URIs):
-The reference foo_ points to the explicit target. However, referencing from
-an external document requires the non-obvious fragment identifier "#foo-1".
+.. _target: first
+
+.. _target: second
""",
"""\
<document source="test data">
- <section dupnames="foo" ids="foo">
- <title>
- foo
- <system_message backrefs="foo-1" level="1" line="5" source="test data" type="INFO">
- <paragraph>
- Target name overrides implicit target name "foo".
+ <paragraph>
+ Duplicate external \n\
+ <problematic ids="problematic-1" refid="system-message-1">
+ target_
+ 's (different URIs):
+ <target dupnames="target" refuri="first">
+ <system_message level="2" line="5" source="test data" type="WARNING">
<paragraph>
- If an implicit target precedes a homonymous explicit target \n\
- <target ids="foo-1" names="foo">
- foo
- ,
- the explicit target takes over the reference name but not the identifier.
+ Duplicate explicit target name: "target".
+ <target dupnames="target" refuri="second">
+ <system_message backrefs="problematic-1" ids="system-message-1" level="3" line="1" source="test data" type="ERROR">
<paragraph>
- The reference \n\
- <reference refid="foo-1">
- foo
- points to the explicit target. However, referencing from
- an external document requires the non-obvious fragment identifier "#foo-1".
+ Duplicate target name, cannot be used as a unique reference: "target".
"""],
-])
-
-totest['implicit hyperlinks'] = ({'legacy_ids': False}, [
["""\
-.. contents:: Table of Contents
-.. _indirect reference to the table of contents: `table of contents`_
+Duplicate external targets (different URIs) without reference:
-Section
-=======
+.. _target: first
-Testing an `indirect reference to the table of contents`_.
+.. _target: second
""",
"""\
<document source="test data">
- <topic classes="contents" ids="table-of-contents" names="table\\ of\\ contents">
- <title>
- Table of Contents
- <bullet_list>
- <list_item>
- <paragraph>
- <reference ids="toc-entry-1" refid="section">
- Section
- <target ids="indirect-reference-to-the-table-of-contents" names="indirect\\ reference\\ to\\ the\\ table\\ of\\ contents" refid="table-of-contents">
- <section ids="section" names="section">
- <title refid="toc-entry-1">
- Section
+ <paragraph>
+ Duplicate external targets (different URIs) without reference:
+ <target dupnames="target" refuri="first">
+ <system_message level="2" line="5" source="test data" type="WARNING">
<paragraph>
- Testing an \n\
- <reference refid="table-of-contents">
- indirect reference to the table of contents
- .
+ Duplicate explicit target name: "target".
+ <target dupnames="target" refuri="second">
"""],
["""\
-.. _explicit target:
+.. _chained:
+.. _external hyperlink: http://uri
-Title
------
-
-References to the section (title_) use the ID from the `explicit target`_.
+`External hyperlink`_ reference
+and a chained_ reference too.
""",
"""\
<document source="test data">
- <target refid="explicit-target">
- <section ids="explicit-target" names="title explicit\\ target">
- <title>
- Title
+ <target refid="chained">
+ <target ids="chained" names="external\\ hyperlink chained" refuri="http://uri">
+ <paragraph>
+ <reference refuri="http://uri">
+ External hyperlink
+ reference
+ and a \n\
+ <reference refuri="http://uri">
+ chained
+ reference too.
+"""],
+["""\
+.. _external hyperlink: http://uri
+.. _indirect target: `external hyperlink`_
+""",
+"""\
+<document source="test data">
+ <target names="external\\ hyperlink" refuri="http://uri">
+ <target names="indirect\\ target" refuri="http://uri">
+ <system_message level="1" line="2" source="test data" type="INFO">
<paragraph>
- References to the section (
- <reference refid="explicit-target">
- title
- ) use the ID from the \n\
- <reference refid="explicit-target">
- explicit target
- .
+ Hyperlink target "indirect target" is not referenced.
"""],
["""\
-target1_ should refer to target2_, not the Title.
+.. _external hyperlink: http://uri
+.. _indirect hyperlink: `external hyperlink`_
-.. _target1:
-.. _target2: URI
+`Indirect hyperlink`_ reference.
+""",
+"""\
+<document source="test data">
+ <target names="external\\ hyperlink" refuri="http://uri">
+ <target names="indirect\\ hyperlink" refuri="http://uri">
+ <paragraph>
+ <reference refuri="http://uri">
+ Indirect hyperlink
+ reference.
+"""],
+["""\
+.. _external hyperlink: http://uri
+.. _chained:
+.. _indirect hyperlink: `external hyperlink`_
-Title
-=====
+Chained_ `indirect hyperlink`_ reference.
""",
"""\
<document source="test data">
+ <target names="external\\ hyperlink" refuri="http://uri">
+ <target refuri="http://uri">
+ <target ids="chained" names="indirect\\ hyperlink chained" refuri="http://uri">
<paragraph>
- <reference refuri="URI">
- target1
- should refer to \n\
- <reference refuri="URI">
- target2
- , not the Title.
- <target refid="target1">
- <target ids="target2 target1" names="target2 target1" refuri="URI">
- <section names="title">
- <title>
- Title
+ <reference refuri="http://uri">
+ Chained
+ \n\
+ <reference refuri="http://uri">
+ indirect hyperlink
+ reference.
"""],
["""\
-foo
----
+.. _external: http://uri
+.. _indirect: external_
+.. _internal:
-With legacy_ids = False, an explicit target _`foo` takes over the
-reference name and identifier of a homonymous implicit target.
+.. image:: picture.png
+ :target: external_
-The reference foo_ points to the explicit target.
-Referencing from an external document can be done
-using the matching fragment identifier "#foo".
+.. image:: picture.png
+ :target: indirect_
+
+.. image:: picture.png
+ :target: internal_
""",
"""\
<document source="test data">
- <section dupnames="foo">
- <title>
- foo
- <system_message backrefs="foo" level="1" line="5" source="test data" type="INFO">
- <paragraph>
- Target name overrides implicit target name "foo".
+ <target names="external" refuri="http://uri">
+ <target names="indirect" refuri="http://uri">
+ <target refid="internal">
+ <reference ids="internal" names="internal" refuri="http://uri">
+ <image uri="picture.png">
+ <reference refuri="http://uri">
+ <image uri="picture.png">
+ <reference refid="internal">
+ <image uri="picture.png">
+"""],
+["""\
+.. __: http://full
+__
+__ http://simplified
+.. _external: http://indirect.external
+__ external_
+__
+
+`Full syntax anonymous external hyperlink reference`__,
+`chained anonymous external reference`__,
+`simplified syntax anonymous external hyperlink reference`__,
+`indirect anonymous hyperlink reference`__,
+`internal anonymous hyperlink reference`__.
+""",
+"""\
+<document source="test data">
+ <target anonymous="1" refuri="http://full">
+ <target anonymous="1" refid="target-1">
+ <target anonymous="1" ids="target-1" refuri="http://simplified">
+ <target names="external" refuri="http://indirect.external">
+ <target anonymous="1" refuri="http://indirect.external">
+ <target anonymous="1" refid="target-2">
+ <paragraph ids="target-...
[truncated message content] |
|
From: <mi...@us...> - 2026-07-14 13:31:54
|
Revision: 10381
http://sourceforge.net/p/docutils/code/10381
Author: milde
Date: 2026-07-14 13:31:29 +0000 (Tue, 14 Jul 2026)
Log Message:
-----------
"lazy IDs": Generate "implicit" section IDs only if required.
Do not load/run the `SectionIDs` transform.
Keep it so that components/applications that want IDs on all sections
can easily add it to their `get_transforms_spec()` method.
+ Links from the ToC and "self-links" use the same ID
("explicit" ID, if available).
+ Less "noise" in the output document.
Full backwards compatibility can be achieved with setting "legacy_ids".
Modified Paths:
--------------
trunk/docutils/HISTORY.rst
trunk/docutils/RELEASE-NOTES.rst
trunk/docutils/docs/api/transforms.rst
trunk/docutils/docs/user/config.rst
trunk/docutils/docutils/parsers/__init__.py
trunk/docutils/docutils/readers/standalone.py
trunk/docutils/docutils/transforms/parts.py
trunk/docutils/docutils/transforms/references.py
trunk/docutils/docutils/writers/html5_polyglot/__init__.py
trunk/docutils/test/data/help/docutils.rst
trunk/docutils/test/data/help/rst2html.rst
trunk/docutils/test/data/help/rst2latex.rst
trunk/docutils/test/functional/expected/length_units_html5.html
trunk/docutils/test/functional/expected/misc_rst_html5.html
trunk/docutils/test/functional/expected/standalone_rst_html5.html
trunk/docutils/test/functional/expected/standalone_rst_pseudoxml.txt
trunk/docutils/test/functional/expected/standalone_rst_xetex.tex
trunk/docutils/test/functional/tests/length_units_html5.py
trunk/docutils/test/test_transforms/test_contents.py
trunk/docutils/test/test_transforms/test_hyperlinks.py
trunk/docutils/test/test_transforms/test_sectnum.py
Modified: trunk/docutils/HISTORY.rst
===================================================================
--- trunk/docutils/HISTORY.rst 2026-07-14 13:31:13 UTC (rev 10380)
+++ trunk/docutils/HISTORY.rst 2026-07-14 13:31:29 UTC (rev 10381)
@@ -51,6 +51,7 @@
* docutils/parsers/__init__.py
- Remove `recommonmark` from `PARSER_ALIASES`.
+ - Rename command line option ``--matching-ids`` to ``--lazy-ids``.
* docutils/parsers/commonmark_wrapper.py
@@ -87,11 +88,17 @@
- Update `Reader.get_transforms()` to load the three transforms
obsoleting `references.DanglingReferences` (see below).
+ - Do not load `transforms.references.SectionIDs`.
* docutils/transforms/__init__.py
- Remove `Transformer.unknown_reference_resolvers`.
+* docutils/transforms/parts.py:
+
+ - `Contents.build_contents()`: ensure sections have an ID and prefer
+ IDs from external targets with "lazy IDs" (`legacy_ids`_ False).
+
* docutils/transforms/references.py
- `IndirectHyperlinks.resolve_indirect_target()` no longer calls
@@ -100,6 +107,8 @@
and `ReportUnreferencedLinks` obsolete `DanglingReferences`.
- Add INFO system_message if a <target> cannot be propagated
to the next node.
+ - support "lazy IDs": Handle hyperlink targets without ID;
+ if required, generate and set one.
* docutils/transforms/universal.py
@@ -123,6 +132,7 @@
problems with other elements using "topic" as class value (e.g. a
docinfo item "topic" in Enhancement Reports).
- More robust handling of figure captions.
+ - Support "lazy IDs": ensure sections have an ID when adding a self-link.
* docutils/writers/latex2e/__init__.py
Modified: trunk/docutils/RELEASE-NOTES.rst
===================================================================
--- trunk/docutils/RELEASE-NOTES.rst 2026-07-14 13:31:13 UTC (rev 10380)
+++ trunk/docutils/RELEASE-NOTES.rst 2026-07-14 13:31:29 UTC (rev 10381)
@@ -220,6 +220,7 @@
- The legacy_column_widths_ setting now defaults to False.
- The initial_header_level_ setting default for the HTML5 writer
changed to "auto".
+ - Rename command line option ``--matching-ids`` to ``--lazy-ids``.
Command line interface:
- Option ``-o`` sets the `output file path <output_path_>`__
@@ -227,8 +228,14 @@
- Drop the ``<destination>`` positional argument.
Use ``-o <destination>`` or output redirection.
+standalone reader:
+ - Do not load the `SectionIDs` transform.
+
rST parser:
- Warn if a `"figure"`_ directive is missing both caption and legend.
+ - Generate identifiers for implicit targets (mainly sections) only if
+ there is a cross-link to the target [#cross-links]_ and no "explicit"
+ identifier (unless legacy_ids_ is True).
HTML5 writer:
- Use normal font size and colour for informal titles of type "rubric".
@@ -285,6 +292,9 @@
`writers.latex2e.SortableDict`
Not used and deprecated since Docutils 0.22.
+.. [#cross-links] This includes links from the table of contents_ and
+ "`section self-links <section_self_link_>`_" added by the HTML5
+ writer.
Release 0.23 (2026-05-27)
=========================
Modified: trunk/docutils/docs/api/transforms.rst
===================================================================
--- trunk/docutils/docs/api/transforms.rst 2026-07-14 13:31:13 UTC (rev 10380)
+++ trunk/docutils/docs/api/transforms.rst 2026-07-14 13:31:29 UTC (rev 10381)
@@ -57,7 +57,7 @@
references_.Substitutions standalone_ (r), pep_ (r) _`220`
-references_.SectionIDs standalone_ (r), pep_ (r) _`240`
+references_.SectionIDs *not used* _`240`
references_.PropagateTargets standalone_ (r), pep_ (r) _`260`
Modified: trunk/docutils/docs/user/config.rst
===================================================================
--- trunk/docutils/docs/user/config.rst 2026-07-14 13:31:13 UTC (rev 10380)
+++ trunk/docutils/docs/user/config.rst 2026-07-14 13:31:29 UTC (rev 10381)
@@ -798,16 +798,38 @@
Keep element identifiers_ compatible to Docutils ≤ 0.22.
-In case of a name conflict with an `implicit target`_ (section heading),
-identifiers_ may have a disambiguating number added to the normalized
-`reference name`_.
+If "legacy_ids" is False or with the command line option ``--lazy-ids``,
+the generation of identifiers_ from the `reference names`_ of
+`implicit targets`_ is done after parsing is complete and only
+if required by an internal cross-link [#cross-link]_.
+An existing identifier from an `explicit target`_ is re-used instead of
+generating an additional identifier for the "implicit" reference name.
-:Default: True; will change to False in Docutils 2.0.
-:Options: ``--legacy-ids``, ``--matching-ids``.
+* Less "noise" in generated output documents.
+* Less cluttered identifier namespace: `explicit targets`_ have a better
+ chance to get an identifier_ matching their `reference name`_. [#]_
-New in Docutils 0.23. Provisional.
+.. caution:: Changing this setting may alter IDs in the output document
+ and hence break incoming "deep" hyperlinks that use "implicit"
+ identifiers in their `URI fragment`_.
+:Default: True (will change to False in Docutils 2.0).
+:Options: ``--legacy-ids``,
+ ``--lazy-ids`` (name changed in Docutils 1.0).
+New in Docutils 0.23. Provisional.
+
+.. [#cross-link]
+ Internal cross-links include links from `hyperlink references`_,
+ the `table of contents`_, and "`self-links <section_self_link_>`_"
+ added by the HTML5 writer.
+.. [#]
+ Due to the `identifier normalization`_, different `reference names`_
+ may compete for the same identifier_, e.g. the reference names
+ ``"legacy ids"`` and ``"legacy-ids"`` would get the
+ identifiers ``"legacy-ids"`` and ``"legacy-ids-1"``.
+
+
raw_enabled
-----------
@@ -2634,6 +2656,8 @@
.. _"code": ../ref/rst/directives.html#code
.. _"csv-table": ../ref/rst/directives.html#csv-table
.. _"figure": ../ref/rst/directives.html#figure
+.. _identifier normalization:
+ ../ref/rst/directives.html#identifier-normalization
.. _images:
.. _"image": ../ref/rst/directives.html#image
.. _"include": ../ref/rst/directives.html#include
@@ -2662,12 +2686,15 @@
.. _citations: ../ref/rst/restructuredtext.html#citations
.. _document title: ../ref/rst/restructuredtext.html#document-title
.. _enumerated lists: ../ref/rst/restructuredtext.html#enumerated-lists
-.. _explicit target: ../ref/rst/restructuredtext.html#explicit-hyperlink-targets
+.. _explicit target:
+.. _explicit targets: ../ref/rst/restructuredtext.html#explicit-hyperlink-targets
+.. _explicit internal target: ../ref/rst/restructuredtext.html#internal-hyperlink-targets
.. _field lists: ../ref/rst/restructuredtext.html#field-lists
.. _field names: ../ref/rst/restructuredtext.html#field-names
.. _footnotes: ../ref/rst/restructuredtext.html#footnotes
.. _footnote references: ../ref/rst/restructuredtext.html#footnote-references
.. _hyperlink references: ../ref/rst/restructuredtext.html#hyperlink-references
+.. _implicit hyperlink targets:
.. _implicit target:
.. _implicit targets: ../ref/rst/restructuredtext.html#implicit-hyperlink-targets
.. _interpreted text role: ../ref/rst/restructuredtext.html#interpreted-text
@@ -2675,6 +2702,7 @@
../ref/rst/restructuredtext.html#inline-markup-recognition-rules
.. _literal blocks: ../ref/rst/restructuredtext.html#literal-blocks
.. _option lists: ../ref/rst/restructuredtext.html#option-lists
+.. _sections: ../ref/rst/restructuredtext.html#sections
.. _tables: ../ref/rst/restructuredtext.html#tables
.. _Docutils HTML writers: html.html
@@ -2701,3 +2729,5 @@
.. _standard encodings:
https://docs.python.org/3/library/codecs.html#standard-encodings
.. _inspecting_codecs: https://codeberg.org/milde/inspecting-codecs
+.. _URI fragment:
+ https://developer.mozilla.org/en-US/docs/Web/URI/Reference/Fragment
Modified: trunk/docutils/docutils/parsers/__init__.py
===================================================================
--- trunk/docutils/docutils/parsers/__init__.py 2026-07-14 13:31:13 UTC (rev 10380)
+++ trunk/docutils/docutils/parsers/__init__.py 2026-07-14 13:31:29 UTC (rev 10381)
@@ -47,12 +47,12 @@
['--line-length-limit'],
{'metavar': '<length>', 'type': 'int', 'default': 10_000,
'validator': frontend.validate_nonnegative_int}),
- ('Keep identifiers backwards compatible. (default)',
+ ('Keep IDs backwards compatible. (default)',
['--legacy-ids'],
{'action': 'store_true', 'default': True,
'validator': frontend.validate_boolean}),
- ('Explicit targets use identifiers matching the reference name.',
- ['--matching-ids'],
+ ('Generate IDs for implicit targets only if required.',
+ ['--lazy-ids'],
{'dest': 'legacy_ids', 'action': 'store_false'}),
('Validate the document tree after parsing.',
['--validate'],
Modified: trunk/docutils/docutils/readers/standalone.py
===================================================================
--- trunk/docutils/docutils/readers/standalone.py 2026-07-14 13:31:13 UTC (rev 10380)
+++ trunk/docutils/docutils/readers/standalone.py 2026-07-14 13:31:29 UTC (rev 10381)
@@ -56,7 +56,6 @@
def get_transforms(self) -> list[type[Transform]]:
return super().get_transforms() + [
references.Substitutions,
- references.SectionIDs,
references.PropagateTargets,
frontmatter.DocTitle,
frontmatter.DocInfo,
Modified: trunk/docutils/docutils/transforms/parts.py
===================================================================
--- trunk/docutils/docutils/transforms/parts.py 2026-07-14 13:31:13 UTC (rev 10380)
+++ trunk/docutils/docutils/transforms/parts.py 2026-07-14 13:31:29 UTC (rev 10381)
@@ -118,12 +118,16 @@
sections = [sect for sect in node if isinstance(sect, nodes.section)]
entries = []
depth = self.startnode.details.get('depth', sys.maxsize)
+ legacy_ids = getattr(self.document.settings, "legacy_ids", True)
for section in sections:
title = section[0]
auto = title.get('auto') # May be set by SectNum.
entrytext = self.copy_and_filter(title)
- reference = nodes.reference('', '', refid=section['ids'][0],
- *entrytext)
+ if legacy_ids: # get first (backwards compatible)
+ sect_id = section['ids'][0]
+ else: # ensure there is an ID, get last
+ sect_id = self.document.set_id(section)
+ reference = nodes.reference('', '', refid=sect_id, *entrytext)
ref_id = self.document.set_id(reference,
suggested_prefix='toc-entry')
entry = nodes.paragraph('', '', reference)
Modified: trunk/docutils/docutils/transforms/references.py
===================================================================
--- trunk/docutils/docutils/transforms/references.py 2026-07-14 13:31:13 UTC (rev 10380)
+++ trunk/docutils/docutils/transforms/references.py 2026-07-14 13:31:29 UTC (rev 10381)
@@ -20,19 +20,18 @@
"""
Add identifiers to sections.
- If the "legacy_ids" configuration setting is False, the rST parser
- does not generate identifiers for implicit targets (e.g. sections)
- in order to give explicit targets preferential access to identifiers
- matching their reference name.
+ Since Docutils 0.23, the rST parser does not generate identifiers for
+ implicit targets (e.g. sections) unless the "legacy_ids" configuration
+ setting is True.
- However, the `parts.Contents` transform and most writers
- expect sections to have an identifier, so this transform adds them.
+ Components that expect all sections to have an identifier can either
+ set "legacy_ids" or load this transform to add them.
"""
default_priority = 240
def apply(self) -> None:
if getattr(self.document.settings, "legacy_ids", True):
- return
+ return # IDs already generated by parser
for node in self.document.findall(nodes.section):
self.document.set_id(node)
@@ -89,8 +88,8 @@
next_node.expect_referenced_by_name = {}
if not hasattr(next_node, 'expect_referenced_by_id'):
next_node.expect_referenced_by_id = {}
+ # Update mappings:
for id in target['ids']:
- # Update IDs to node mapping.
self.document.ids[id] = next_node
# If next_node is referenced by id ``id``, this
# target shall be marked as referenced.
@@ -883,16 +882,21 @@
nodes.citation_reference)):
if node.resolved or 'refname' not in node:
continue
- identifier = self.document.nameids.get(node['refname'])
- if identifier:
- # target found, set refid
- node['refid'] = identifier
- self.document.ids[identifier].note_referenced_by(id=identifier)
- # If a transform is able to resolve the reference,
- # it should # also remove the 'refname' attribute and
- # mark the node as resolved:
- del node['refname']
- node.resolved = True
+ refname = node['refname']
+ target = self.document.names.get(refname)
+ if target is None: # "refname" is unknown or duplicate
+ continue
+ # target found, set refid
+ refid = self.document.nameids.get(refname)
+ if refid:
+ target.note_referenced_by(id=refid)
+ else:
+ refid = self.document.set_id(target)
+ target.note_referenced_by(name=refname)
+ node['refid'] = refid
+ # cleanup
+ del node['refname']
+ node.resolved = True
class CitationReferences(Transform):
Modified: trunk/docutils/docutils/writers/html5_polyglot/__init__.py
===================================================================
--- trunk/docutils/docutils/writers/html5_polyglot/__init__.py 2026-07-14 13:31:13 UTC (rev 10380)
+++ trunk/docutils/docutils/writers/html5_polyglot/__init__.py 2026-07-14 13:31:29 UTC (rev 10381)
@@ -347,6 +347,11 @@
# use the new HTML5 element <section>
def visit_section(self, node) -> None:
self.section_level += 1
+ # ensure the element has an ID if we want to add a self-link:
+ if (getattr(self.settings, 'section_self_link', None)
+ and not getattr(self.settings, 'legacy_ids', None)
+ and 'system-messages' not in node['classes']):
+ node.document.set_id(node)
self.body.append(self.starttag(node, 'section'))
def depart_section(self, node) -> None:
Modified: trunk/docutils/test/data/help/docutils.rst
===================================================================
--- trunk/docutils/test/data/help/docutils.rst 2026-07-14 13:31:13 UTC (rev 10380)
+++ trunk/docutils/test/data/help/docutils.rst 2026-07-14 13:31:29 UTC (rev 10381)
@@ -89,9 +89,8 @@
--line-length-limit=<length>
Maximal number of characters in an input line.
(default 10 000)
---legacy-ids Keep identifiers backwards compatible. (default)
---matching-ids Explicit targets use identifiers matching the
- reference name.
+--legacy-ids Keep IDs backwards compatible. (default)
+--lazy-ids Generate IDs for implicit targets only if required.
--validate Validate the document tree after parsing.
--no-validation Do not validate the document tree. (default)
Modified: trunk/docutils/test/data/help/rst2html.rst
===================================================================
--- trunk/docutils/test/data/help/rst2html.rst 2026-07-14 13:31:13 UTC (rev 10380)
+++ trunk/docutils/test/data/help/rst2html.rst 2026-07-14 13:31:29 UTC (rev 10381)
@@ -90,9 +90,8 @@
--line-length-limit=<length>
Maximal number of characters in an input line.
(default 10 000)
---legacy-ids Keep identifiers backwards compatible. (default)
---matching-ids Explicit targets use identifiers matching the
- reference name.
+--legacy-ids Keep IDs backwards compatible. (default)
+--lazy-ids Generate IDs for implicit targets only if required.
--validate Validate the document tree after parsing.
--no-validation Do not validate the document tree. (default)
Modified: trunk/docutils/test/data/help/rst2latex.rst
===================================================================
--- trunk/docutils/test/data/help/rst2latex.rst 2026-07-14 13:31:13 UTC (rev 10380)
+++ trunk/docutils/test/data/help/rst2latex.rst 2026-07-14 13:31:29 UTC (rev 10381)
@@ -90,9 +90,8 @@
--line-length-limit=<length>
Maximal number of characters in an input line.
(default 10 000)
---legacy-ids Keep identifiers backwards compatible. (default)
---matching-ids Explicit targets use identifiers matching the
- reference name.
+--legacy-ids Keep IDs backwards compatible. (default)
+--lazy-ids Generate IDs for implicit targets only if required.
--validate Validate the document tree after parsing.
--no-validation Do not validate the document tree. (default)
Modified: trunk/docutils/test/functional/expected/length_units_html5.html
===================================================================
--- trunk/docutils/test/functional/expected/length_units_html5.html 2026-07-14 13:31:13 UTC (rev 10380)
+++ trunk/docutils/test/functional/expected/length_units_html5.html 2026-07-14 13:31:29 UTC (rev 10381)
@@ -9,10 +9,10 @@
<link rel="stylesheet" href="../input/data/plain.css" type="text/css" />
</head>
<body>
-<main id="test-length-specifications">
+<main>
<h1 class="title">Test length specifications</h1>
-<section id="images-and-figures">
+<section>
<h2>Images and Figures</h2>
<figure>
<img alt="blue square" height="32" src="../input/data/blue%20square.png" width="32" />
@@ -129,13 +129,13 @@
</figcaption>
</figure>
</section>
-<section id="ch-em-and-rem-test1ch-test1em-test1rem">
+<section>
<h2>ch, em, and rem: <img alt="test1ch" src="../input/data/blue%20square.png" style="height: 1ch;" /> <img alt="test1em" src="../input/data/blue%20square.png" style="height: 1em;" /> <img alt="test1rem" src="../input/data/blue%20square.png" style="height: 1rem;" /></h2>
<p>Image height 1ch, 1em, and 1rem: <img alt="test1ch" src="../input/data/blue%20square.png" style="height: 1ch;" /> <img alt="test1em" src="../input/data/blue%20square.png" style="height: 1em;" /> <img alt="test1rem" src="../input/data/blue%20square.png" style="height: 1rem;" /></p>
<p>The units "em" and "ch" change with the current font size.
The unit "rem" is tied to the document root fontsize.</p>
</section>
-<section id="tables">
+<section>
<h2>Tables</h2>
<table>
<tbody>
Modified: trunk/docutils/test/functional/expected/misc_rst_html5.html
===================================================================
--- trunk/docutils/test/functional/expected/misc_rst_html5.html 2026-07-14 13:31:13 UTC (rev 10380)
+++ trunk/docutils/test/functional/expected/misc_rst_html5.html 2026-07-14 13:31:29 UTC (rev 10381)
@@ -9,7 +9,7 @@
<link rel="stylesheet" href="../input/data/responsive.css" type="text/css" />
</head>
<body class="with-toc">
-<main id="additional-tests-with-html-5">
+<main>
<h1 class="title">Additional tests with HTML 5</h1>
<nav class="contents" id="contents" role="doc-toc">
Modified: trunk/docutils/test/functional/expected/standalone_rst_html5.html
===================================================================
--- trunk/docutils/test/functional/expected/standalone_rst_html5.html 2026-07-14 13:31:13 UTC (rev 10380)
+++ trunk/docutils/test/functional/expected/standalone_rst_html5.html 2026-07-14 13:31:29 UTC (rev 10381)
@@ -21,10 +21,9 @@
<header>
<p>Document header</p>
</header>
-<main id="restructuredtext-test-document">
-<span id="doctitle"></span>
+<main id="doctitle">
<h1 class="title">reStructuredText Test Document</h1>
-<p class="subtitle" id="examples-of-syntax-constructs"><span id="subtitle"></span>Examples of Syntax Constructs</p>
+<p class="subtitle" id="subtitle">Examples of Syntax Constructs</p>
<dl class="docinfo">
<dt class="author">Author<span class="colon">:</span></dt>
<dd class="author"><p>David Goodger</p></dd>
@@ -109,7 +108,7 @@
<li><p><a class="reference internal" href="#doctest-blocks" id="toc-entry-16"><span class="sectnum">2.10 </span>Doctest Blocks</a></p></li>
<li><p><a class="reference internal" href="#footnotes" id="toc-entry-17"><span class="sectnum">2.11 </span>Footnotes</a></p></li>
<li><p><a class="reference internal" href="#citations" id="toc-entry-18"><span class="sectnum">2.12 </span>Citations</a></p></li>
-<li><p><a class="reference internal" href="#targets" id="toc-entry-19"><span class="sectnum">2.13 </span>Targets</a></p>
+<li><p><a class="reference internal" href="#another-target" id="toc-entry-19"><span class="sectnum">2.13 </span>Targets</a></p>
<ul class="auto-toc">
<li><p><a class="reference internal" href="#duplicate-target-names-1" id="toc-entry-20"><span class="sectnum">2.13.1 </span>Duplicate Target Names</a></p></li>
<li><p><a class="reference internal" href="#duplicate-target-names-2" id="toc-entry-21"><span class="sectnum">2.13.2 </span>Duplicate Target Names</a></p></li>
@@ -165,7 +164,7 @@
<h2><a class="toc-backref" href="#toc-entry-1" role="doc-backlink"><span class="sectnum">1 </span>Structural Elements</a><a class="self-link" title="link to this section" href="#structural-elements"></a></h2>
<section id="section-title">
<h3><a class="toc-backref" href="#toc-entry-2" role="doc-backlink"><span class="sectnum">1.1 </span>Section Title</a><a class="self-link" title="link to this section" href="#section-title"></a></h3>
-<p class="section-subtitle" id="section-subtitle">Section Subtitle</p>
+<p class="section-subtitle">Section Subtitle</p>
<p>Lone subsections are converted to a section subtitle by a transform
activated with the <span class="docutils literal"><span class="pre">--section-subtitles</span></span> command line option or the
<span class="docutils literal"><span class="pre">sectsubtitle-xform</span></span> configuration value.</p>
@@ -198,7 +197,7 @@
<a class="brackets" href="#label" id="footnote-reference-3" role="doc-noteref"><span class="fn-bracket">[</span>2<span class="fn-bracket">]</span></a>, or symbolic <a class="brackets" href="#footnote-3" id="footnote-reference-4" role="doc-noteref"><span class="fn-bracket">[</span>*<span class="fn-bracket">]</span></a>), citation references (see <a class="citation-reference" href="#cit2002" id="citation-reference-1" role="doc-biblioref">[CIT2002]</a>),
substitution references (<img alt="EXAMPLE" src="../../../docs/user/rst/images/biohazard.png" /> &
a <em>trimmed heart</em> <span class="docutils literal">(U+2665):</span>♥), and <span class="target" id="inline-hyperlink-targets">inline hyperlink targets</span>
-(see <a class="reference internal" href="#targets">Targets</a> below for a reference back to here). Character-level
+(see <a class="reference internal" href="#another-target">Targets</a> below for a reference back to here). Character-level
inline markup is also possible (although exceedingly ugly!) in <em>re</em><span class="docutils literal">Structured</span><em>Text</em>. Problems are indicated by <a href="#system-message-1"><span class="problematic" id="problematic-1">|problematic|</span></a> text
(generated by processing errors; this one is intentional). Here is a
reference to the <a class="reference internal" href="#doctitle">doctitle</a> and the <a class="reference internal" href="#subtitle">subtitle</a>.</p>
@@ -530,18 +529,17 @@
<p>Here's a reference to the above, <a class="citation-reference" href="#cit2002" id="citation-reference-2" role="doc-biblioref">[CIT2002]</a>, and a <a href="#system-message-3"><span class="problematic" id="citation-reference-3">[nonexistent]_</span></a>
citation.</p>
</section>
-<section id="targets">
-<span id="another-target"></span>
+<section id="another-target">
<h3><a class="toc-backref" href="#toc-entry-19" role="doc-backlink"><span class="sectnum">2.13 </span>Targets</a><a class="self-link" title="link to this section" href="#another-target"></a></h3>
<p id="example">This paragraph is pointed to by the explicit "example" target. A
reference can be found under <a class="reference internal" href="#inline-markup">Inline Markup</a>, above. <a class="reference internal" href="#inline-hyperlink-targets">Inline
hyperlink targets</a> are also possible.</p>
<p>Section headers are implicit targets, referred to by name. See
-<a class="reference internal" href="#targets">Targets</a>, which is a subsection of <a class="reference internal" href="#body-elements">Body Elements</a>.</p>
+<a class="reference internal" href="#another-target">Targets</a>, which is a subsection of <a class="reference internal" href="#body-elements">Body Elements</a>.</p>
<p>Explicit external targets are interpolated into references such as
"<a class="reference external" href="http://www.python.org/">Python</a> <a class="brackets" href="#footnote-7" id="footnote-reference-19" role="doc-noteref"><span class="fn-bracket">[</span>7<span class="fn-bracket">]</span></a>".</p>
-<p>Targets may be indirect and anonymous. Thus <a class="reference internal" href="#targets">this phrase</a> may also
-refer to the <a class="reference internal" href="#targets">Targets</a> section.</p>
+<p>Targets may be indirect and anonymous. Thus <a class="reference internal" href="#another-target">this phrase</a> may also
+refer to the <a class="reference internal" href="#another-target">Targets</a> section.</p>
<p>Here's a <a href="#system-message-4"><span class="problematic" id="problematic-2">`hyperlink reference without a target`_</span></a>, which generates an
error.</p>
<section id="duplicate-target-names-1">
Modified: trunk/docutils/test/functional/expected/standalone_rst_pseudoxml.txt
===================================================================
--- trunk/docutils/test/functional/expected/standalone_rst_pseudoxml.txt 2026-07-14 13:31:13 UTC (rev 10380)
+++ trunk/docutils/test/functional/expected/standalone_rst_pseudoxml.txt 2026-07-14 13:31:29 UTC (rev 10381)
@@ -1,7 +1,7 @@
-<document ids="restructuredtext-test-document doctitle" names="restructuredtext\ test\ document doctitle" source="functional/input/standalone_rst_pseudoxml.rst" title="reStructuredText Test Document">
+<document ids="doctitle" names="restructuredtext\ test\ document doctitle" source="functional/input/standalone_rst_pseudoxml.rst" title="reStructuredText Test Document">
<title>
reStructuredText Test Document
- <subtitle ids="examples-of-syntax-constructs subtitle" names="examples\ of\ syntax\ constructs subtitle">
+ <subtitle ids="subtitle" names="examples\ of\ syntax\ constructs subtitle">
Examples of Syntax Constructs
<meta content="reStructuredText, test, parser" name="keywords">
<meta content="A test document, containing at least one example of each reStructuredText construct." lang="en" name="description">
@@ -204,7 +204,7 @@
Citations
<list_item>
<paragraph>
- <reference ids="toc-entry-19" refid="targets">
+ <reference ids="toc-entry-19" refid="another-target">
<generated classes="sectnum">
2.13
Targets
@@ -358,7 +358,7 @@
<generated classes="sectnum">
1.1
Section Title
- <subtitle ids="section-subtitle" names="section\ subtitle">
+ <subtitle names="section\ subtitle">
Section Subtitle
<paragraph>
Lone subsections are converted to a section subtitle by a transform
@@ -475,7 +475,7 @@
inline hyperlink targets
(see
- <reference refid="targets">
+ <reference refid="another-target">
Targets
below for a reference back to here). Character-level
inline markup is also possible (although exceedingly ugly!) in
@@ -1109,7 +1109,7 @@
citation.
<target refid="another-target">
- <section ids="targets another-target" names="targets another\ target">
+ <section ids="another-target" names="targets another\ target">
<title auto="1" refid="toc-entry-19">
<generated classes="sectnum">
2.13
@@ -1127,7 +1127,7 @@
are also possible.
<paragraph>
Section headers are implicit targets, referred to by name. See
- <reference refid="targets">
+ <reference refid="another-target">
Targets
, which is a subsection of
<reference refid="body-elements">
@@ -1145,14 +1145,14 @@
<target ids="python" names="python" refuri="http://www.python.org/">
<paragraph>
Targets may be indirect and anonymous. Thus
- <reference anonymous="1" refid="targets">
+ <reference anonymous="1" refid="another-target">
this phrase
may also
refer to the
- <reference refid="targets">
+ <reference refid="another-target">
Targets
section.
- <target anonymous="1" ids="target-4" refid="targets">
+ <target anonymous="1" ids="target-4" refid="another-target">
<paragraph>
Here's a
<problematic ids="problematic-2" refid="system-message-4">
@@ -2417,9 +2417,6 @@
<system_message level="1" line="159" source="functional/input/data/standard.rst" type="INFO">
<paragraph>
Hyperlink target "target" is not referenced.
- <system_message level="1" line="404" source="functional/input/data/standard.rst" type="INFO">
- <paragraph>
- Hyperlink target "another-target" is not referenced.
<system_message level="1" line="474" source="functional/input/data/standard.rst" type="INFO">
<paragraph>
Hyperlink target "image-target-1" is not referenced.
Modified: trunk/docutils/test/functional/expected/standalone_rst_xetex.tex
===================================================================
--- trunk/docutils/test/functional/expected/standalone_rst_xetex.tex 2026-07-14 13:31:13 UTC (rev 10380)
+++ trunk/docutils/test/functional/expected/standalone_rst_xetex.tex 2026-07-14 13:31:29 UTC (rev 10381)
@@ -188,7 +188,7 @@
\item \hyperref[citations]{2.12 Citations}
-\item \hyperref[targets]{2.13 Targets}
+\item \hyperref[another-target]{2.13 Targets}
\begin{DUclass}{auto-toc}
\begin{itemize}
@@ -325,7 +325,7 @@
substitution references (\includegraphics{../../../docs/user/rst/images/biohazard.png} \&
a \emph{trimmed heart} \texttt{(U+2665):}♥), and %
\phantomsection\label{inline-hyperlink-targets}inline hyperlink targets
-(see \hyperref[targets]{Targets} below for a reference back to here). Character-level
+(see \hyperref[another-target]{Targets} below for a reference back to here). Character-level
inline markup is also possible (although exceedingly ugly!) in \emph{re}\texttt{Structured}\emph{Text}. Problems are indicated by %
\raisebox{1em}{\hypertarget{problematic-1}{}}\hyperlink{system-message-1}{\textbf{\color{red}|problematic|}} text
(generated by processing errors; this one is intentional). Here is a
@@ -739,7 +739,6 @@
\subsection{2.13 Targets%
- \label{targets}%
\label{another-target}%
}
@@ -749,13 +748,13 @@
hyperlink targets} are also possible.
Section headers are implicit targets, referred to by name. See
-\hyperref[targets]{Targets}, which is a subsection of \hyperref[body-elements]{Body Elements}.
+\hyperref[another-target]{Targets}, which is a subsection of \hyperref[body-elements]{Body Elements}.
Explicit external targets are interpolated into references such as
“\href{http://www.python.org/}{Python}\DUfootnotemark{footnote-reference-11}{footnote-6}{5}”.
-Targets may be indirect and anonymous. Thus \hyperref[targets]{this phrase} may also
-refer to the \hyperref[targets]{Targets} section.
+Targets may be indirect and anonymous. Thus \hyperref[another-target]{this phrase} may also
+refer to the \hyperref[another-target]{Targets} section.
Here’s a %
\raisebox{1em}{\hypertarget{problematic-2}{}}\hyperlink{system-message-4}{\textbf{\color{red}`hyperlink reference without a target`\_}}, which generates an
Modified: trunk/docutils/test/functional/tests/length_units_html5.py
===================================================================
--- trunk/docutils/test/functional/tests/length_units_html5.py 2026-07-14 13:31:13 UTC (rev 10380)
+++ trunk/docutils/test/functional/tests/length_units_html5.py 2026-07-14 13:31:29 UTC (rev 10381)
@@ -16,4 +16,5 @@
# location of stylesheets (relative to ``docutils/test/``)
'stylesheet_dirs': ('functional/input/data', ),
'section_self_link': False,
+ 'legacy_ids': False,
}
Modified: trunk/docutils/test/test_transforms/test_contents.py
===================================================================
--- trunk/docutils/test/test_transforms/test_contents.py 2026-07-14 13:31:13 UTC (rev 10380)
+++ trunk/docutils/test/test_transforms/test_contents.py 2026-07-14 13:31:29 UTC (rev 10381)
@@ -20,7 +20,7 @@
from docutils.frontend import get_default_settings
from docutils.parsers.rst import Parser
-from docutils.transforms.references import SectionIDs, Substitutions
+from docutils.transforms.references import Substitutions
from docutils.transforms.universal import TestMessages
from docutils.utils import new_document
@@ -46,7 +46,7 @@
totest = {}
-totest['tables_of_contents'] = ((SectionIDs, Substitutions,), [
+totest['tables_of_contents'] = ((Substitutions,), [
["""\
.. contents::
Modified: trunk/docutils/test/test_transforms/test_hyperlinks.py
===================================================================
--- trunk/docutils/test/test_transforms/test_hyperlinks.py 2026-07-14 13:31:13 UTC (rev 10380)
+++ trunk/docutils/test/test_transforms/test_hyperlinks.py 2026-07-14 13:31:29 UTC (rev 10381)
@@ -20,7 +20,7 @@
from docutils.frontend import get_default_settings
from docutils.parsers.rst import Parser
from docutils.transforms.references import (
- SectionIDs, PropagateTargets, AnonymousHyperlinks, IndirectHyperlinks,
+ PropagateTargets, AnonymousHyperlinks, IndirectHyperlinks,
ExternalTargets, InternalTargets, DanglingReferences, MatchReferences,
ReportDanglingReferences, ReportUnreferencedTargets)
from docutils.transforms.universal import TestMessages
@@ -33,7 +33,7 @@
transforms = (PropagateTargets, AnonymousHyperlinks, IndirectHyperlinks,
ExternalTargets, InternalTargets, MatchReferences,
ReportDanglingReferences, ReportUnreferencedTargets,
- SectionIDs, TestMessages)
+ TestMessages)
def test_transforms(self):
parser = Parser()
@@ -594,7 +594,7 @@
"""],
])
-totest['hyperlinks legacy'] = ({'legacy_ids': True}, [
+totest['explicit hyperlinks legacy'] = ({'legacy_ids': True}, [
["""\
.. _internal hyperlink:
@@ -1036,6 +1036,58 @@
to an image with target (sic!).
"""],
["""\
+Unknown reference_.
+""",
+"""\
+<document source="test data">
+ <paragraph>
+ Unknown \n\
+ <problematic ids="problematic-1" refid="system-message-1">
+ reference_
+ .
+ <system_message backrefs="problematic-1" ids="system-message-1" level="3" line="1" source="test data" type="ERROR">
+ <paragraph>
+ Unknown target name: "reference".
+"""],
+["""\
+Duplicate manual footnote labels, with reference ([1]_):
+
+.. [1] Footnote.
+
+.. [1] Footnote.
+""",
+"""\
+<document source="test data">
+ <paragraph>
+ Duplicate manual footnote labels, with reference (
+ <problematic ids="footnote-reference-1" refid="system-message-1">
+ [1]_
+ ):
+ <footnote dupnames="1" ids="footnote-1">
+ <label>
+ 1
+ <paragraph>
+ Footnote.
+ <footnote dupnames="1" ids="footnote-2">
+ <label>
+ 1
+ <system_message backrefs="footnote-2" level="2" line="5" source="test data" type="WARNING">
+ <paragraph>
+ Duplicate explicit target name: "1".
+ <paragraph>
+ Footnote.
+ <system_message backrefs="footnote-reference-1" ids="system-message-1" level="3" line="1" source="test data" type="ERROR">
+ <paragraph>
+ Duplicate target name, cannot be used as a unique reference: "1".
+"""],
+])
+
+totest['explicit hyperlinks'] = ({'legacy_ids': False},
+ # all samples compile as before
+ totest['explicit hyperlinks legacy'][1])
+
+totest['implicit hyperlinks legacy'] = ({'legacy_ids': True}, [
+["""\
.. contents:: Table of Contents
.. _indirect reference to the table of contents: `table of contents`_
@@ -1109,51 +1161,6 @@
Title
"""],
["""\
-Unknown reference_.
-""",
-"""\
-<document source="test data">
- <paragraph>
- Unknown \n\
- <problematic ids="problematic-1" refid="system-message-1">
- reference_
- .
- <system_message backrefs="problematic-1" ids="system-message-1" level="3" line="1" source="test data" type="ERROR">
- <paragraph>
- Unknown target name: "reference".
-"""],
-["""\
-Duplicate manual footnote labels, with reference ([1]_):
-
-.. [1] Footnote.
-
-.. [1] Footnote.
-""",
-"""\
-<document source="test data">
- <paragraph>
- Duplicate manual footnote labels, with reference (
- <problematic ids="footnote-reference-1" refid="system-message-1">
- [1]_
- ):
- <footnote dupnames="1" ids="footnote-1">
- <label>
- 1
- <paragraph>
- Footnote.
- <footnote dupnames="1" ids="footnote-2">
- <label>
- 1
- <system_message backrefs="footnote-2" level="2" line="5" source="test data" type="WARNING">
- <paragraph>
- Duplicate explicit target name: "1".
- <paragraph>
- Footnote.
- <system_message backrefs="footnote-reference-1" ids="system-message-1" level="3" line="1" source="test data" type="ERROR">
- <paragraph>
- Duplicate target name, cannot be used as a unique reference: "1".
-"""],
-["""\
An explicit target _`foo` overrides a homonymous implicit target.
foo
@@ -1213,10 +1220,84 @@
"""],
])
-totest['hyperlinks'] = ({'legacy_ids': False},
- # all but the last sample compile as before
- totest['hyperlinks legacy'][1][:-1] + [
+totest['implicit hyperlinks'] = ({'legacy_ids': False}, [
["""\
+.. contents:: Table of Contents
+.. _indirect reference to the table of contents: `table of contents`_
+
+Section
+=======
+
+Testing an `indirect reference to the table of contents`_.
+""",
+"""\
+<document source="test data">
+ <topic classes="contents" ids="table-of-contents" names="table\\ of\\ contents">
+ <title>
+ Table of Contents
+ <bullet_list>
+ <list_item>
+ <paragraph>
+ <reference ids="toc-entry-1" refid="section">
+ Section
+ <target ids="indirect-reference-to-the-table-of-contents" names="indirect\\ reference\\ to\\ the\\ table\\ of\\ contents" refid="table-of-contents">
+ <section ids="section" names="section">
+ <title refid="toc-entry-1">
+ Section
+ <paragraph>
+ Testing an \n\
+ <reference refid="table-of-contents">
+ indirect reference to the table of contents
+ .
+"""],
+["""\
+.. _explicit target:
+
+Title
+-----
+
+References to the section (title_) use the ID from the `explicit target`_.
+""",
+"""\
+<document source="test data">
+ <target refid="explicit-target">
+ <section ids="explicit-target" names="title explicit\\ target">
+ <title>
+ Title
+ <paragraph>
+ References to the section (
+ <reference refid="explicit-target">
+ title
+ ) use the ID from the \n\
+ <reference refid="explicit-target">
+ explicit target
+ .
+"""],
+["""\
+target1_ should refer to target2_, not the Title.
+
+.. _target1:
+.. _target2: URI
+
+Title
+=====
+""",
+"""\
+<document source="test data">
+ <paragraph>
+ <reference refuri="URI">
+ target1
+ should refer to \n\
+ <reference refuri="URI">
+ target2
+ , not the Title.
+ <target refid="target1">
+ <target ids="target2 target1" names="target2 target1" refuri="URI">
+ <section names="title">
+ <title>
+ Title
+"""],
+["""\
foo
---
@@ -1229,7 +1310,7 @@
""",
"""\
<document source="test data">
- <section dupnames="foo" ids="foo-1">
+ <section dupnames="foo">
<title>
foo
<system_message backrefs="foo" level="1" line="5" source="test data" type="INFO">
Modified: trunk/docutils/test/test_transforms/test_sectnum.py
===================================================================
--- trunk/docutils/test/test_transforms/test_sectnum.py 2026-07-14 13:31:13 UTC (rev 10380)
+++ trunk/docutils/test/test_transforms/test_sectnum.py 2026-07-14 13:31:29 UTC (rev 10381)
@@ -20,7 +20,7 @@
from docutils.frontend import get_default_settings
from docutils.parsers.rst import Parser
-from docutils.transforms.references import SectionIDs, Substitutions
+from docutils.transforms.references import Substitutions
from docutils.transforms.universal import TestMessages
from docutils.utils import new_document
@@ -46,7 +46,7 @@
totest = {}
-totest['section_numbers'] = ((SectionIDs, Substitutions), [
+totest['section_numbers'] = ((Substitutions,), [
["""\
.. sectnum::
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
|
From: <mi...@us...> - 2026-07-14 13:31:16
|
Revision: 10380
http://sourceforge.net/p/docutils/code/10380
Author: milde
Date: 2026-07-14 13:31:13 +0000 (Tue, 14 Jul 2026)
Log Message:
-----------
Small fixes.
Fix typos, improve wording and formatting at various places.
Remove obsolete change announcements.
Sort link targets.
Update comments and simplifiy conditional in nodes.py.
Update `document.names` after transferring names from explicit internal targets,
simplify conditional, and use `True` instead of 1 for boolean value
in transforms/references.py.
Format code in html5 writer. More precise condition in `section_title_tags()`.
Simplify CSS rule to highlight "targeted" elements,
also highlight target admonitions and topics.
No change to tested behaviour.
Modified Paths:
--------------
trunk/docutils/HISTORY.rst
trunk/docutils/RELEASE-NOTES.rst
trunk/docutils/docs/ref/rst/restructuredtext.rst
trunk/docutils/docs/user/config.rst
trunk/docutils/docutils/nodes.py
trunk/docutils/docutils/transforms/references.py
trunk/docutils/docutils/writers/html5_polyglot/__init__.py
trunk/docutils/docutils/writers/html5_polyglot/responsive.css
Modified: trunk/docutils/HISTORY.rst
===================================================================
--- trunk/docutils/HISTORY.rst 2026-07-14 13:31:00 UTC (rev 10379)
+++ trunk/docutils/HISTORY.rst 2026-07-14 13:31:13 UTC (rev 10380)
@@ -94,12 +94,10 @@
* docutils/transforms/references.py
- - Do not call `unknown_reference_resolvers` in
- `IndirectHyperlinks.resolve_indirect_target()`.
- - 3 new transforms, `references.MatchReferences`,
- `references.ReportDanglingReferences` and
- `references.ReportUnreferencedLinks`,
- obsolete `references.DanglingReferences`.
+ - `IndirectHyperlinks.resolve_indirect_target()` no longer calls
+ `unknown_reference_resolvers` and only sets IDs if required.
+ - 3 new transforms, `MatchReferences`, `ReportDanglingReferences`,
+ and `ReportUnreferencedLinks` obsolete `DanglingReferences`.
- Add INFO system_message if a <target> cannot be propagated
to the next node.
@@ -119,10 +117,11 @@
- Change the default value of the "section_self_link" setting to True.
- Add CSS rules for back-link and self-link symbols from
"responsive.css" also in "plain.css" and "tuftig.css".
- - Use normal font size and colour in CSS for informal titles of type "rubric".
+ - Use normal font size and colour in CSS for informal titles
+ of type "rubric".
- 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.
+ 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/RELEASE-NOTES.rst
===================================================================
--- trunk/docutils/RELEASE-NOTES.rst 2026-07-14 13:31:00 UTC (rev 10379)
+++ trunk/docutils/RELEASE-NOTES.rst 2026-07-14 13:31:13 UTC (rev 10380)
@@ -71,11 +71,6 @@
<substitution_definition>, and <target> elements when warning about
transitions at the start or end of the document or a section.
-* In case of name conflicts, an explicit target will not only override
- the "name" attribute of an implicit target but also its name-based "id".
- Use case: "sane" anchors for links from an external source to a fragment
- of the document. Cf. https://github.com/sphinx-doc/sphinx/issues/1961
-
Parsers
-------
@@ -101,12 +96,6 @@
* "html5" writer:
- - Prefer explicit reference names as base for an HTML element's ID
- in Docutils 1.0. No change for internal cross-references.
- Cf. `Sphinx issue #1961`__
-
- __ https://github.com/sphinx-doc/sphinx/issues/1961
-
- Move attribution behind the blockquote to comply with the
`"HTML living standard"`__ [#]_ and adapt CSS stylesheets
in Docutils 1.0.
@@ -1638,8 +1627,6 @@
.. _datestamp: docs/user/config.html#datestamp
.. _embed_images: docs/user/config.html#embed-images
.. _graphicx_option: docs/user/config.html#graphicx-option
-.. _legacy_class_functions: docs/user/config.html#legacy-class-functions
-.. _literal_block_env: docs/user/config.html#literal-block-env
.. _id_prefix: docs/user/config.html#id-prefix
.. _image_loading: docs/user/config.html#image-loading
.. _initial_header_level: docs/user/config.html#initial-header-level
@@ -1646,9 +1633,10 @@
.. _input_encoding: docs/user/config.html#input-encoding
.. _[latex writers]: docs/user/config.html#latex-writers
.. _latex_footnotes: docs/user/config.html#latex-footnotes
+.. _legacy_class_functions: docs/user/config.html#legacy-class-functions
.. _legacy_column_widths: docs/user/config.html#legacy-column-widths
.. _legacy_ids: docs/user/config.html#legacy-ids
-.. _text_references: docs/user/config.html#text-references
+.. _literal_block_env: docs/user/config.html#literal-block-env
.. _math_output: docs/user/config.html#math-output
.. _old-format configuration files:
docs/user/config.html#old-format-configuration-files
@@ -1660,6 +1648,7 @@
.. _section_self_link: docs/user/config.html#section-self-link
.. _SmartQuotes: docs/user/config.html#smart-quotes
.. _sources: docs/user/config.html#sources
+.. _text_references: docs/user/config.html#text-references
.. _use_latex_citations: docs/user/config.html#use-latex-citations
.. _validate: docs/user/config.html#validate
.. _"writer" setting: docs/user/config.html#writer-buildhtml-application
Modified: trunk/docutils/docs/ref/rst/restructuredtext.rst
===================================================================
--- trunk/docutils/docs/ref/rst/restructuredtext.rst 2026-07-14 13:31:00 UTC (rev 10379)
+++ trunk/docutils/docs/ref/rst/restructuredtext.rst 2026-07-14 13:31:13 UTC (rev 10380)
@@ -474,7 +474,7 @@
Hyperlink`_
Hyperlinks_, footnotes_, and citations_ all share the same namespace
-for reference names. [#substitution-text]_
+for `reference names`_. [#substitution-text]_
This means that a footnote defined as "``.. [#note]``" can be referred to
by the `footnote reference`_ ``[#note]_`` as well as a plain `hyperlink
reference`_ ``note_``. Of course, each type of reference (hyperlink,
@@ -629,8 +629,8 @@
established, sections must use that hierarchy. [#]_
Each section title automatically generates a hyperlink target pointing
-to the section. The text of the hyperlink target (the "reference
-name") is the same as that of the section title. See `Implicit
+to the section. The text of the hyperlink target (the `reference name`_)
+is the same as that of the section title. See `Implicit
Hyperlink Targets`_ for a complete description.
Sections may contain `body elements`_, transitions_, and nested
Modified: trunk/docutils/docs/user/config.rst
===================================================================
--- trunk/docutils/docs/user/config.rst 2026-07-14 13:31:00 UTC (rev 10379)
+++ trunk/docutils/docs/user/config.rst 2026-07-14 13:31:13 UTC (rev 10380)
@@ -255,10 +255,7 @@
:Default: "%" (use Doctree element name; changed from "id" in Docutils 0.18).
:Option: ``--auto-id-prefix`` (hidden, intended mainly for programmatic use).
-.. _identifier normalization:
- ../ref/rst/directives.html#identifier-normalization
-
datestamp
---------
@@ -806,7 +803,7 @@
`reference name`_.
:Default: True; will change to False in Docutils 2.0.
-:Option: ``--legacy-ids``, ``--matching-ids``.
+:Options: ``--legacy-ids``, ``--matching-ids``.
New in Docutils 0.23. Provisional.
@@ -2158,7 +2155,7 @@
.. _ODT Writer: odt.html
.. _OpenDocument: https://en.wikipedia.org/wiki/OpenDocument
-add-syntax_highlighting
+add_syntax_highlighting
~~~~~~~~~~~~~~~~~~~~~~~
Add syntax highlighting in literal code blocks.
See section "`Syntax highlighting`__" in the ODT Writer documentation
@@ -2610,6 +2607,8 @@
.. _Document Tree: ../ref/doctree.html
.. _Doctree: ../ref/doctree.html
.. _class attribute: ../ref/doctree.html#classes
+.. _identifier:
+.. _element identifiers:
.. _identifiers: ../ref/doctree.html#identifiers
.. _reference name:
.. _reference names: ../ref/doctree.html#reference-names
@@ -2670,7 +2669,7 @@
.. _footnote references: ../ref/rst/restructuredtext.html#footnote-references
.. _hyperlink references: ../ref/rst/restructuredtext.html#hyperlink-references
.. _implicit target:
-.. _implicit targets: ../ref/rst/restructuredtext.html#implicit-hyperlink-targets
+.. _implicit targets: ../ref/rst/restructuredtext.html#implicit-hyperlink-targets
.. _interpreted text role: ../ref/rst/restructuredtext.html#interpreted-text
.. _inline markup recognition rules:
../ref/rst/restructuredtext.html#inline-markup-recognition-rules
Modified: trunk/docutils/docutils/nodes.py
===================================================================
--- trunk/docutils/docutils/nodes.py 2026-07-14 13:31:00 UTC (rev 10379)
+++ trunk/docutils/docutils/nodes.py 2026-07-14 13:31:13 UTC (rev 10380)
@@ -686,7 +686,7 @@
def __len__(self) -> int:
return len(self.children)
- def __contains__(self, key) -> bool:
+ def __contains__(self, key: str | Node) -> bool:
# Test for both, children and attributes with operator ``in``.
if isinstance(key, str):
return key in self.attributes
@@ -1209,17 +1209,13 @@
`name` or id `id`."""
self.referenced = True
# Element.expect_referenced_by_* dictionaries map names or ids
- # to nodes whose ``referenced`` attribute is set to true as
- # soon as this node is referenced by the given name or id.
- # Needed for target propagation.
- by_name = getattr(self, 'expect_referenced_by_name', {}).get(name)
- by_id = getattr(self, 'expect_referenced_by_id', {}).get(id)
- if by_name:
- assert name is not None
- by_name.referenced = True
- if by_id:
- assert id is not None
- by_id.referenced = True
+ # that were "propagated" to this element to the elements that
+ # had these attributes before. Mark them as ``referenced``
+ # when this node is referenced by the respective names or ids.
+ if relay := getattr(self, 'expect_referenced_by_name', {}).get(name):
+ relay.referenced = True
+ if relay := getattr(self, 'expect_referenced_by_id', {}).get(id):
+ relay.referenced = True
@classmethod
def is_not_list_attribute(cls, attr: str) -> bool:
@@ -1972,7 +1968,7 @@
Check/set identifiers of element `node`. Return last identifier.
Check `node`s identifiers for duplicates,
- create a new identifier if there are none.
+ create a new identifier if there are no identifiers.
Update `document.ids` and `document.nameids`.
Provisional.
@@ -2168,7 +2164,7 @@
self.nametypes.setdefault(name, explicit)
def has_name(self, name: str) -> bool:
- # TODO: deprecate? (use ``name in document.names``)
+ # TODO: deprecate in Docutils 2.0 (use ``name in document.names``)
return name in self.names
# "note" here is an imperative verb: "take note of".
@@ -2576,9 +2572,7 @@
(legend, '?'),
)
# (image, ((caption, legend?) | legend))
- # TODO: According to the DTD, a caption or legend is required
- # but rST allows "bare" figures which are formatted differently from
- # images (floating in LaTeX, nested in a <figure> in HTML). [bugs: #489]
+ # A caption or legend is required (cf. [bugs: #489]).
# Tables
Modified: trunk/docutils/docutils/transforms/references.py
===================================================================
--- trunk/docutils/docutils/transforms/references.py 2026-07-14 13:31:00 UTC (rev 10379)
+++ trunk/docutils/docutils/transforms/references.py 2026-07-14 13:31:13 UTC (rev 10380)
@@ -64,11 +64,11 @@
def apply(self) -> None:
for target in self.document.findall(nodes.target):
# Only block-level targets without reference (like ".. _target:"):
- if (isinstance(target.parent, nodes.TextElement)
- or (target.hasattr('refid') or target.hasattr('refuri')
- or target.hasattr('refname'))):
+ if (len(target) or isinstance(target.parent, nodes.TextElement)
+ or 'refid' in target
+ or 'refname' in target
+ or 'refuri' in target):
continue
- assert len(target) == 0, 'error: block-level target has children'
next_node = target.next_node(ascend=True)
# skip system messages (may be removed by universal.FilterMessages)
while isinstance(next_node, nodes.system_message):
@@ -96,6 +96,7 @@
# target shall be marked as referenced.
next_node.expect_referenced_by_id[id] = target
for name in target['names']:
+ self.document.names[name] = next_node
next_node.expect_referenced_by_name[name] = target
# If there are any expect_referenced_by_... attributes
# in target set, copy them to next_node.
@@ -264,12 +265,12 @@
if (isinstance(reftarget, nodes.target)
and not reftarget.resolved
and reftarget.hasattr('refname')):
- if hasattr(target, 'multiply_indirect'):
+ if hasattr(target, 'multiple_indirect'):
self.circular_indirect_reference(target)
return
- target.multiply_indirect = 1
- self.resolve_indirect_target(reftarget) # multiply indirect
- del target.multiply_indirect
+ target.multiple_indirect = True
+ self.resolve_indirect_target(reftarget) # multiple redirection
+ del target.multiple_indirect
if reftarget.hasattr('refuri'):
target['refuri'] = reftarget['refuri']
if 'refid' in target:
@@ -277,13 +278,12 @@
elif reftarget.hasattr('refid'):
target['refid'] = reftarget['refid']
self.document.note_refid(target)
+ elif reftarget['ids']:
+ target['refid'] = refid
+ self.document.note_refid(target)
else:
- if reftarget['ids']:
- target['refid'] = refid
- self.document.note_refid(target)
- else:
- self.nonexistent_indirect_target(target)
- return
+ self.nonexistent_indirect_target(target)
+ return
if refname is not None:
del target['refname']
target.resolved = True
@@ -403,7 +403,7 @@
def apply(self) -> None:
for target in self.document.findall(nodes.target):
- if not target.hasattr('refuri') and not target.hasattr('refid'):
+ if 'refid' not in target and 'refuri' not in target:
self.resolve_reference_ids(target)
def resolve_reference_ids(self, target) -> None:
@@ -809,7 +809,7 @@
nodelist = []
for target in self.document.findall(nodes.target):
# Only external targets.
- if not target.hasattr('refuri'):
+ if 'refuri' not in target:
continue
names = target['names']
refs = []
@@ -1050,7 +1050,7 @@
pass
def visit_reference(self, node) -> None:
- if node.resolved or not node.hasattr('refname'):
+ if node.resolved or 'refname' not in node:
return
refname = node['refname']
id = self.document.nameids.get(refname, '')
Modified: trunk/docutils/docutils/writers/html5_polyglot/__init__.py
===================================================================
--- trunk/docutils/docutils/writers/html5_polyglot/__init__.py 2026-07-14 13:31:00 UTC (rev 10379)
+++ trunk/docutils/docutils/writers/html5_polyglot/__init__.py 2026-07-14 13:31:13 UTC (rev 10380)
@@ -347,8 +347,7 @@
# use the new HTML5 element <section>
def visit_section(self, node) -> None:
self.section_level += 1
- self.body.append(
- self.starttag(node, 'section'))
+ self.body.append(self.starttag(node, 'section'))
def depart_section(self, node) -> None:
self.section_level -= 1
@@ -356,8 +355,7 @@
# use the new HTML5 element <aside>
def visit_sidebar(self, node) -> None:
- self.body.append(
- self.starttag(node, 'aside', CLASS='sidebar'))
+ self.body.append(self.starttag(node, 'aside', CLASS='sidebar'))
self.in_sidebar = True
def depart_sidebar(self, node) -> None:
@@ -394,7 +392,7 @@
start_tag, close_tag = super().section_title_tags(node)
ids = node.parent['ids']
if (ids and getattr(self.settings, 'section_self_link', None)
- and not isinstance(node.parent, nodes.document)):
+ and isinstance(node.parent, nodes.section)):
self_link = ('<a class="self-link" title="link to this section"'
f' href="#{ids[-1]}"></a>')
close_tag = close_tag.replace('</h', self_link + '</h')
Modified: trunk/docutils/docutils/writers/html5_polyglot/responsive.css
===================================================================
--- trunk/docutils/docutils/writers/html5_polyglot/responsive.css 2026-07-14 13:31:00 UTC (rev 10379)
+++ trunk/docutils/docutils/writers/html5_polyglot/responsive.css 2026-07-14 13:31:13 UTC (rev 10380)
@@ -299,11 +299,9 @@
dt:target, span:target, p:target,
.contents :target,
.contents:target > .topic-title,
-aside.system-message:target,
+aside:target,
[role="doc-biblioentry"]:target,
[role="doc-biblioref"]:target,
-[role="note"]:target, /* Docutils 0.18 and 0.19 */
-[role="doc-footnote"]:target, /* Docutils >= 0.20 */
[role="doc-noteref"]:target {
background-color: #d2e6ec;
}
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
|
From: <mi...@us...> - 2026-07-14 13:31:03
|
Revision: 10379
http://sourceforge.net/p/docutils/code/10379
Author: milde
Date: 2026-07-14 13:31:00 +0000 (Tue, 14 Jul 2026)
Log Message:
-----------
Add test for the bug with anonymous links to images with a :target:.
Anonymous internal hyperlinks to "clickable" images currently link to the
wrapping `<reference>` instead of the `<image>`.
The reference is handled similar to an indirect target: the reference's
"refid" or "refuri" is transferred to the internal reference.
As a result, clicking the hyperlink reference to the image brings you
directly to the image's "target" (instead of the internal image).
Modified Paths:
--------------
trunk/docutils/test/test_transforms/test_hyperlinks.py
Modified: trunk/docutils/test/test_transforms/test_hyperlinks.py
===================================================================
--- trunk/docutils/test/test_transforms/test_hyperlinks.py 2026-07-13 11:13:03 UTC (rev 10378)
+++ trunk/docutils/test/test_transforms/test_hyperlinks.py 2026-07-14 13:31:00 UTC (rev 10379)
@@ -937,7 +937,105 @@
<reference refid="internal">
<image uri="picture.png">
"""],
+# TODO: Anonymous links to a "clickable image should go
+# to the image, not the image's click-target!
["""\
+.. _img1:
+.. image:: pic1.png
+ :target: uri1.html
+__
+.. image:: pic2.png
+__
+.. image:: pic3.png
+ :target: uri3.html
+
+Named link to img1_ with target and anonymous links to
+the targetless img2__ and
+img3__ with target (sic!).
+""",
+"""\
+<document source="test data">
+ <target refid="img1">
+ <reference ids="img1" names="img1" refuri="uri1.html">
+ <image uri="pic1.png">
+ <target anonymous="1" refid="target-1">
+ <image ids="target-1" uri="pic2.png">
+ <target anonymous="1" refid="target-2">
+ <reference ids="target-2" refuri="uri3.html">
+ <image uri="pic3.png">
+ <paragraph>
+ Named link to \n\
+ <reference refid="img1">
+ img1
+ with target and anonymous links to
+ the targetless \n\
+ <reference anonymous="1" refid="target-1">
+ img2
+ and
+ <reference anonymous="1" refuri="uri3.html">
+ img3
+ with target (sic!).
+"""],
+["""\
+__
+__
+.. image:: pic1.png
+ :target: uri1.html
+
+Two anonymous__ links to an `image with target`__ (sic!).
+
+.. _named:
+__
+.. image:: pic2.png
+ :target: uri2.html
+
+Named_ and anonymous__ link to an image with target (sic!).
+
+__
+.. _named link:
+.. image:: pic3.png
+ :target: uri3.html
+
+Anonymous__ and `named link`_ to an image with target (sic!).
+""",
+"""\
+<document source="test data">
+ <target anonymous="1" refid="target-1">
+ <target anonymous="1" refid="target-2">
+ <reference ids="target-2 target-1" refuri="uri1.html">
+ <image uri="pic1.png">
+ <paragraph>
+ Two \n\
+ <reference anonymous="1" refuri="uri1.html">
+ anonymous
+ links to an \n\
+ <reference anonymous="1" refuri="uri1.html">
+ image with target
+ (sic!).
+ <target refid="named">
+ <target anonymous="1" refid="target-3">
+ <reference ids="target-3 named" names="named" refuri="uri2.html">
+ <image uri="pic2.png">
+ <paragraph>
+ <reference refid="named">
+ Named
+ and \n\
+ <reference anonymous="1" refuri="uri2.html">
+ anonymous
+ link to an image with target (sic!).
+ <target anonymous="1" refid="target-4">
+ <target refid="named-link">
+ <reference ids="named-link target-4" names="named\\ link" refuri="uri3.html">
+ <image uri="pic3.png">
+ <paragraph>
+ <reference anonymous="1" refuri="uri3.html">
+ Anonymous
+ and \n\
+ <reference refid="named-link">
+ named link
+ to an image with target (sic!).
+"""],
+["""\
.. contents:: Table of Contents
.. _indirect reference to the table of contents: `table of contents`_
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
|
From: <mi...@us...> - 2026-07-13 11:13:06
|
Revision: 10378
http://sourceforge.net/p/docutils/code/10378
Author: milde
Date: 2026-07-13 11:13:03 +0000 (Mon, 13 Jul 2026)
Log Message:
-----------
Inform if a target cannot be propagated to the next element.
Add an INFO system_message if a `<target>` cannot be "propagated" because the
next element is invisible, a footnote, or a citation.
Modified Paths:
--------------
trunk/docutils/HISTORY.rst
trunk/docutils/docutils/transforms/references.py
trunk/docutils/test/functional/expected/standalone_rst_pseudoxml.txt
trunk/docutils/test/test_transforms/test_hyperlinks.py
Modified: trunk/docutils/HISTORY.rst
===================================================================
--- trunk/docutils/HISTORY.rst 2026-06-30 08:11:33 UTC (rev 10377)
+++ trunk/docutils/HISTORY.rst 2026-07-13 11:13:03 UTC (rev 10378)
@@ -100,6 +100,8 @@
`references.ReportDanglingReferences` and
`references.ReportUnreferencedLinks`,
obsolete `references.DanglingReferences`.
+ - Add INFO system_message if a <target> cannot be propagated
+ to the next node.
* docutils/transforms/universal.py
Modified: trunk/docutils/docutils/transforms/references.py
===================================================================
--- trunk/docutils/docutils/transforms/references.py 2026-06-30 08:11:33 UTC (rev 10377)
+++ trunk/docutils/docutils/transforms/references.py 2026-07-13 11:13:03 UTC (rev 10378)
@@ -78,6 +78,9 @@
if (next_node is None
or isinstance(next_node, (nodes.Invisible, nodes.Targetable))
and not isinstance(next_node, nodes.target)):
+ self.document.reporter.info(
+ f'Cannot propagate target "{" ".join(target["names"])}" '
+ 'to next element', base_node=target)
continue
next_node['ids'].extend(target['ids'])
next_node['names'].extend(target['names'])
Modified: trunk/docutils/test/functional/expected/standalone_rst_pseudoxml.txt
===================================================================
--- trunk/docutils/test/functional/expected/standalone_rst_pseudoxml.txt 2026-06-30 08:11:33 UTC (rev 10377)
+++ trunk/docutils/test/functional/expected/standalone_rst_pseudoxml.txt 2026-07-13 11:13:03 UTC (rev 10378)
@@ -2399,6 +2399,9 @@
<system_message backrefs="problematic-1" ids="system-message-1" level="3" line="99" source="functional/input/data/standard.rst" type="ERROR">
<paragraph>
Undefined substitution referenced: "problematic".
+ <system_message level="1" line="159" source="functional/input/data/standard.rst" type="INFO">
+ <paragraph>
+ Cannot propagate target "target" to next element
<system_message backrefs="footnote-reference-8" ids="system-message-2" level="3" line="390" source="functional/input/data/standard.rst" type="ERROR">
<paragraph>
Unknown target name: "5".
Modified: trunk/docutils/test/test_transforms/test_hyperlinks.py
===================================================================
--- trunk/docutils/test/test_transforms/test_hyperlinks.py 2026-06-30 08:11:33 UTC (rev 10377)
+++ trunk/docutils/test/test_transforms/test_hyperlinks.py 2026-07-13 11:13:03 UTC (rev 10378)
@@ -569,6 +569,9 @@
Footnote; \n\
<reference refid="target">
target
+ <system_message level="1" line="1" source="test data" type="INFO">
+ <paragraph>
+ Cannot propagate target "target" to next element
"""],
["""\
.. _target:
@@ -585,6 +588,9 @@
Citation; \n\
<reference refid="target">
target
+ <system_message level="1" line="1" source="test data" type="INFO">
+ <paragraph>
+ Cannot propagate target "target" to next element
"""],
])
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
|
From: <mi...@us...> - 2026-06-30 08:11:35
|
Revision: 10377
http://sourceforge.net/p/docutils/code/10377
Author: milde
Date: 2026-06-30 08:11:33 +0000 (Tue, 30 Jun 2026)
Log Message:
-----------
Make section-titles test sample less discombobulating.
The "section_titles.rst" functional test sample tests, among other things,
inline markup (including a reference) in a section title.
Move the sample refeference's target to a place where it makes some sense
instead of causing puzzlement. Adapt the tests using this sample.
Modified Paths:
--------------
trunk/docutils/test/functional/expected/latex_cornercases.tex
trunk/docutils/test/functional/expected/misc_rst_html4css1.html
trunk/docutils/test/functional/expected/misc_rst_html5.html
trunk/docutils/test/functional/input/data/section_titles.rst
Modified: trunk/docutils/test/functional/expected/latex_cornercases.tex
===================================================================
--- trunk/docutils/test/functional/expected/latex_cornercases.tex 2026-06-29 14:03:43 UTC (rev 10376)
+++ trunk/docutils/test/functional/expected/latex_cornercases.tex 2026-06-30 08:11:33 UTC (rev 10377)
@@ -227,9 +227,7 @@
Unsupported in ODT.
-\section{Section titles with inline markup%
- \label{references}%
-}
+\section{Section titles with inline markup}
\subsection{\emph{emphasized}, H\textsubscript{2}O, $x^2$, and \hyperref[references]{references}}
@@ -239,6 +237,7 @@
\label{substitutions-fail}%
}
+\phantomsection\label{references}
Note, that the \textquotedbl{}reference name\textquotedbl{} for this section is derived from the
content \emph{before} substitution. You can link to it with the \href{https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html\#hyperlink-references}{phrase
reference} \textquotedbl{}\hyperref[substitutions-fail]{substitutions fail}\textquotedbl{}.
Modified: trunk/docutils/test/functional/expected/misc_rst_html4css1.html
===================================================================
--- trunk/docutils/test/functional/expected/misc_rst_html4css1.html 2026-06-29 14:03:43 UTC (rev 10376)
+++ trunk/docutils/test/functional/expected/misc_rst_html4css1.html 2026-06-30 08:11:33 UTC (rev 10377)
@@ -50,7 +50,6 @@
</div>
</div>
<div class="section" id="section-titles-with-inline-markup">
-<span id="references"></span>
<h1>Section titles with inline markup</h1>
<div class="section" id="emphasized-h2o-x-2-and-references">
<h2><em>emphasized</em>, H<sub>2</sub>O, <span class="formula"><i>x</i><sup>2</sup></span>, and <a class="reference internal" href="#references">references</a></h2>
@@ -57,7 +56,7 @@
</div>
<div class="section" id="substitutions-fail">
<h2>Substitutions work</h2>
-<p>Note, that the "reference name" for this section is derived from the
+<p id="references">Note, that the "reference name" for this section is derived from the
content <em>before</em> substitution. You can link to it with the <a class="reference external" href="https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#hyperlink-references">phrase
reference</a> "<a class="reference internal" href="#substitutions-fail">substitutions fail</a>".
This behaviour may be exploited to get intelligible IDs after <a class="reference external" href="https://docutils.sourceforge.io/docs/ref/rst/directives.html#identifier-normalization">identifier
Modified: trunk/docutils/test/functional/expected/misc_rst_html5.html
===================================================================
--- trunk/docutils/test/functional/expected/misc_rst_html5.html 2026-06-29 14:03:43 UTC (rev 10376)
+++ trunk/docutils/test/functional/expected/misc_rst_html5.html 2026-06-30 08:11:33 UTC (rev 10377)
@@ -97,8 +97,7 @@
</section>
</section>
<section id="section-titles-with-inline-markup">
-<span id="references"></span>
-<h2><a class="toc-backref" href="#contents" role="doc-backlink">Section titles with inline markup</a><a class="self-link" title="link to this section" href="#references"></a></h2>
+<h2><a class="toc-backref" href="#contents" role="doc-backlink">Section titles with inline markup</a><a class="self-link" title="link to this section" href="#section-titles-with-inline-markup"></a></h2>
<section id="emphasized-h2o-x-2-and-references">
<h3><em>emphasized</em>, H<sub>2</sub>O, <math xmlns="http://www.w3.org/1998/Math/MathML">
<msup>
@@ -109,7 +108,7 @@
</section>
<section id="substitutions-fail">
<h3><a class="toc-backref" href="#contents" role="doc-backlink">Substitutions work</a><a class="self-link" title="link to this section" href="#substitutions-fail"></a></h3>
-<p>Note, that the “reference name” for this section is derived from the
+<p id="references">Note, that the “reference name” for this section is derived from the
content <em>before</em> substitution. You can link to it with the <a class="reference external" href="https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#hyperlink-references">phrase
reference</a> “<a class="reference internal" href="#substitutions-fail">substitutions fail</a>”.
This behaviour may be exploited to get intelligible IDs after <a class="reference external" href="https://docutils.sourceforge.io/docs/ref/rst/directives.html#identifier-normalization">identifier
Modified: trunk/docutils/test/functional/input/data/section_titles.rst
===================================================================
--- trunk/docutils/test/functional/input/data/section_titles.rst 2026-06-29 14:03:43 UTC (rev 10376)
+++ trunk/docutils/test/functional/input/data/section_titles.rst 2026-06-30 08:11:33 UTC (rev 10377)
@@ -34,7 +34,6 @@
<<<<<<<
Unsupported in ODT.
-.. _references:
Section titles with inline markup
==================================
@@ -46,6 +45,8 @@
--------------------
.. |fail| replace:: work
+.. _references:
+
Note, that the "reference name" for this section is derived from the
content *before* substitution. You can link to it with the `phrase
reference`_ "`substitutions fail`_".
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
|
From: <mi...@us...> - 2026-06-29 14:03:46
|
Revision: 10376
http://sourceforge.net/p/docutils/code/10376
Author: milde
Date: 2026-06-29 14:03:43 +0000 (Mon, 29 Jun 2026)
Log Message:
-----------
Improve warning for figures without caption.
Move details to a separate paragraph (not shown in console output).
Add hint to cheat with an empty comment in place of the caption.
Note: When cheating with an empty comment, the `<figure>` element
remains invalid (but most writers can handle this).
Fixup for [r10370].
Modified Paths:
--------------
trunk/docutils/docutils/parsers/rst/directives/images.py
trunk/docutils/test/test_parsers/test_rst/test_directives/test_figures.py
trunk/docutils/test/test_writers/test_html4css1.py
trunk/docutils/test/test_writers/test_html5_polyglot.py
Modified: trunk/docutils/docutils/parsers/rst/directives/images.py
===================================================================
--- trunk/docutils/docutils/parsers/rst/directives/images.py 2026-06-27 17:26:02 UTC (rev 10375)
+++ trunk/docutils/docutils/parsers/rst/directives/images.py 2026-06-29 14:03:43 UTC (rev 10376)
@@ -156,8 +156,10 @@
if align:
figure_node['align'] = align
if not self.content:
- msg = self.reporter.warning('Figure without caption and legend. '
- 'Use "image"?', line=self.lineno)
+ msg = self.reporter.warning('Figure without caption and legend.',
+ line=self.lineno)
+ msg.append(nodes.paragraph('', 'Try the "image" directive '
+ '(or cheat with an empty comment).'))
return [figure_node, msg]
else:
# optional caption (single paragraph or empty comment)
Modified: trunk/docutils/test/test_parsers/test_rst/test_directives/test_figures.py
===================================================================
--- trunk/docutils/test/test_parsers/test_rst/test_directives/test_figures.py 2026-06-27 17:26:02 UTC (rev 10375)
+++ trunk/docutils/test/test_parsers/test_rst/test_directives/test_figures.py 2026-06-29 14:03:43 UTC (rev 10376)
@@ -51,7 +51,9 @@
<image uri="picture.png">
<system_message level="2" line="1" source="test data" type="WARNING">
<paragraph>
- Figure without caption and legend. Use "image"?
+ Figure without caption and legend.
+ <paragraph>
+ Try the "image" directive (or cheat with an empty comment).
"""],
["""\
.. figure:: picture.png
@@ -330,7 +332,9 @@
<image uri="picture.png">
<system_message level="2" line="15" source="test data" type="WARNING">
<paragraph>
- Figure without caption and legend. Use "image"?
+ Figure without caption and legend.
+ <paragraph>
+ Try the "image" directive (or cheat with an empty comment).
<figure>
<image uri="picture.png">
<figure>
@@ -347,7 +351,9 @@
<image uri="picture.png">
<system_message level="2" line="34" source="test data" type="WARNING">
<paragraph>
- Figure without caption and legend. Use "image"?
+ Figure without caption and legend.
+ <paragraph>
+ Try the "image" directive (or cheat with an empty comment).
"""],
]
Modified: trunk/docutils/test/test_writers/test_html4css1.py
===================================================================
--- trunk/docutils/test/test_writers/test_html4css1.py 2026-06-27 17:26:02 UTC (rev 10375)
+++ trunk/docutils/test/test_writers/test_html4css1.py 2026-06-29 14:03:43 UTC (rev 10376)
@@ -364,7 +364,9 @@
</div>
<div class="system-message">
<p class="system-message-title">System Message: WARNING/2 (<tt class="docutils"><string></tt>, line 1)</p>
-Figure without caption and legend. Use "image"?</div>
+<p>Figure without caption and legend.</p>
+<p>Try the "image" directive (or cheat with an empty comment).</p>
+</div>
<p>No caption nor legend.</p>
""",
],
Modified: trunk/docutils/test/test_writers/test_html5_polyglot.py
===================================================================
--- trunk/docutils/test/test_writers/test_html5_polyglot.py 2026-06-27 17:26:02 UTC (rev 10375)
+++ trunk/docutils/test/test_writers/test_html5_polyglot.py 2026-06-29 14:03:43 UTC (rev 10376)
@@ -391,7 +391,8 @@
</figure>
<aside class="system-message">
<p class="system-message-title">System Message: WARNING/2 (<span class="docutils literal"><string></span>, line 1)</p>
-<p>Figure without caption and legend. Use "image"?</p>
+<p>Figure without caption and legend.</p>
+<p>Try the "image" directive (or cheat with an empty comment).</p>
</aside>
<p>No caption nor legend.</p>
""",
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
|
From: <mi...@us...> - 2026-06-27 17:26:05
|
Revision: 10375
http://sourceforge.net/p/docutils/code/10375
Author: milde
Date: 2026-06-27 17:26:02 +0000 (Sat, 27 Jun 2026)
Log Message:
-----------
Revise `SettingsSpec` definitions.
Use more consistent style.
A `frontend.validate_boolean` validator is required for boolean settings
(converts config file entries to True/False).
It does not need to be specified again in the "reverse-option" for the same
setting variable.
Modified Paths:
--------------
trunk/docutils/docutils/frontend.py
trunk/docutils/docutils/parsers/__init__.py
trunk/docutils/docutils/parsers/rst/__init__.py
trunk/docutils/docutils/writers/_html_base.py
trunk/docutils/docutils/writers/docutils_xml.py
trunk/docutils/docutils/writers/html5_polyglot/__init__.py
trunk/docutils/docutils/writers/latex2e/__init__.py
Modified: trunk/docutils/docutils/frontend.py
===================================================================
--- trunk/docutils/docutils/frontend.py 2026-06-27 17:25:52 UTC (rev 10374)
+++ trunk/docutils/docutils/frontend.py 2026-06-27 17:26:02 UTC (rev 10375)
@@ -686,32 +686,33 @@
'General Docutils Options',
None,
(('Output destination name. (default: stdout)',
- ['--output', '-o'], {'metavar': '<destination>',
- 'dest': 'output_path'}),
+ ['--output', '-o'],
+ {'dest': 'output_path', 'metavar': '<destination>'}),
('Specify the document title as metadata.',
['--title'], {'metavar': '<title>'}),
('Include a "Generated by Docutils" credit and link.',
- ['--generator', '-g'], {'action': 'store_true',
- 'validator': validate_boolean}),
+ ['--generator', '-g'],
+ {'action': 'store_true', 'validator': validate_boolean}),
('Do not include a generator credit.',
- ['--no-generator'], {'action': 'store_false', 'dest': 'generator'}),
+ ['--no-generator'],
+ {'dest': 'generator', 'action': 'store_false'}),
('Include the date at the end of the document (UTC).',
- ['--date', '-d'], {'action': 'store_const', 'const': '%Y-%m-%d',
- 'dest': 'datestamp'}),
+ ['--date', '-d'],
+ {'dest': 'datestamp', 'action': 'store_const', 'const': '%Y-%m-%d'}),
('Include the time & date (UTC).',
- ['--time', '-t'], {'action': 'store_const',
- 'const': '%Y-%m-%d %H:%M UTC',
- 'dest': 'datestamp'}),
+ ['--time', '-t'],
+ {'dest': 'datestamp', 'action': 'store_const',
+ 'const': '%Y-%m-%d %H:%M UTC'}),
('Do not include a datestamp of any kind.',
- ['--no-datestamp'], {'action': 'store_const', 'const': None,
- 'dest': 'datestamp'}),
+ ['--no-datestamp'],
+ {'dest': 'datestamp', 'action': 'store_const', 'const': None}),
('Base directory for absolute paths when reading '
'from the local filesystem. (default: "")',
['--root-prefix'],
{'default': '', 'metavar': '<path>'}),
('Include a "View document source" link.',
- ['--source-link', '-s'], {'action': 'store_true',
- 'validator': validate_boolean}),
+ ['--source-link', '-s'],
+ {'action': 'store_true', 'validator': validate_boolean}),
('Use <URL> for a source link; implies --source-link.',
['--source-url'], {'metavar': '<URL>'}),
('Do not include a "View document source" link.',
@@ -737,66 +738,69 @@
{'dest': 'footnote_backlinks', 'action': 'store_false'}),
('Enable section numbering by Docutils. (default)',
['--section-numbering'],
- {'action': 'store_true', 'dest': 'sectnum_xform',
+ {'dest': 'sectnum_xform', 'action': 'store_true',
'default': True, 'validator': validate_boolean}),
('Disable section numbering by Docutils.',
['--no-section-numbering'],
- {'action': 'store_false', 'dest': 'sectnum_xform'}),
+ {'dest': 'sectnum_xform', 'action': 'store_false'}),
('Remove comment elements from the document tree.',
['--strip-comments'],
{'action': 'store_true', 'validator': validate_boolean}),
('Leave comment elements in the document tree. (default)',
['--leave-comments'],
- {'action': 'store_false', 'dest': 'strip_comments'}),
+ {'dest': 'strip_comments', 'action': 'store_false'}),
('Remove all elements with classes="<class>" from the document tree. '
'Warning: potentially dangerous; use with caution. '
'(multiple-use option.)',
['--strip-elements-with-class'],
- {'action': 'append', 'dest': 'strip_elements_with_classes',
+ {'dest': 'strip_elements_with_classes', 'action': 'append',
'metavar': '<class>', 'validator': validate_strip_class}),
('Remove all classes="<class>" attributes from elements in the '
'document tree. Warning: potentially dangerous; use with caution. '
'(multiple-use option.)',
['--strip-class'],
- {'action': 'append', 'dest': 'strip_classes',
+ {'dest': 'strip_classes', 'action': 'append',
'metavar': '<class>', 'validator': validate_strip_class}),
('Report system messages at or higher than <level>: "info" or "1", '
'"warning"/"2" (default), "error"/"3", "severe"/"4", "none"/"5"',
- ['--report', '-r'], {'choices': threshold_choices, 'default': 2,
- 'dest': 'report_level', 'metavar': '<level>',
- 'validator': validate_threshold}),
+ ['--report', '-r'],
+ {'dest': 'report_level', 'choices': threshold_choices, 'default': 2,
+ 'metavar': '<level>', 'validator': validate_threshold}),
('Report all system messages. (Same as "--report=1".)',
- ['--verbose', '-v'], {'action': 'store_const', 'const': 1,
- 'dest': 'report_level'}),
+ ['--verbose', '-v'],
+ {'dest': 'report_level', 'action': 'store_const', 'const': 1}),
('Report no system messages. (Same as "--report=5".)',
- ['--quiet', '-q'], {'action': 'store_const', 'const': 5,
- 'dest': 'report_level'}),
+ ['--quiet', '-q'],
+ {'dest': 'report_level', 'action': 'store_const', 'const': 5}),
('Halt execution at system messages at or above <level>. '
'Levels as in --report. Default: 4 (severe).',
- ['--halt'], {'choices': threshold_choices, 'dest': 'halt_level',
- 'default': 4, 'metavar': '<level>',
- 'validator': validate_threshold}),
+ ['--halt'],
+ {'dest': 'halt_level', 'choices': threshold_choices, 'default': 4,
+ 'metavar': '<level>', 'validator': validate_threshold}),
('Halt at the slightest problem. Same as "--halt=info".',
- ['--strict'], {'action': 'store_const', 'const': 1,
- 'dest': 'halt_level'}),
+ ['--strict'],
+ {'dest': 'halt_level', 'action': 'store_const', 'const': 1}),
('Enable a non-zero exit status for non-halting system messages at '
'or above <level>. Default: 5 (disabled).',
- ['--exit-status'], {'choices': threshold_choices,
- 'dest': 'exit_status_level',
- 'default': 5, 'metavar': '<level>',
- 'validator': validate_threshold}),
+ ['--exit-status'],
+ {'dest': 'exit_status_level', 'choices': threshold_choices,
+ 'default': 5,
+ 'metavar': '<level>', 'validator': validate_threshold}),
('Enable debug-level system messages and diagnostics.',
- ['--debug'], {'action': 'store_true',
- 'validator': validate_boolean}),
+ ['--debug'],
+ {'action': 'store_true', 'validator': validate_boolean}),
('Disable debug output. (default)',
- ['--no-debug'], {'action': 'store_false', 'dest': 'debug'}),
+ ['--no-debug'],
+ {'dest': 'debug', 'action': 'store_false'}),
('Send the output of system messages to <file>.',
- ['--warnings'], {'dest': 'warning_stream', 'metavar': '<file>'}),
+ ['--warnings'],
+ {'dest': 'warning_stream', 'metavar': '<file>'}),
('Enable Python tracebacks when Docutils is halted.',
- ['--traceback'], {'action': 'store_true', 'default': None,
- 'validator': validate_boolean}),
+ ['--traceback'],
+ {'action': 'store_true', 'validator': validate_boolean}),
('Disable Python tracebacks. (default)',
- ['--no-traceback'], {'dest': 'traceback', 'action': 'store_false'}),
+ ['--no-traceback'],
+ {'dest': 'traceback', 'action': 'store_false'}),
('Specify the encoding and optionally the '
'error handler of input text. (default: utf-8)',
['--input-encoding'],
@@ -820,19 +824,22 @@
{'default': default_error_encoding_error_handler,
'validator': validate_encoding_error_handler}),
('Specify the language (as BCP 47 language tag). (default: en)',
- ['--language', '-l'], {'dest': 'language_code', 'default': 'en',
- 'metavar': '<tag>'}),
+ ['--language', '-l'],
+ {'dest': 'language_code', 'metavar': '<tag>', 'default': 'en'}),
('Write output file dependencies to <file>.',
['--record-dependencies'],
{'metavar': '<file>', 'validator': validate_dependency_file,
- 'default': None}), # default set in Values class
+ 'default': None}), # default file set in Values class
('Read configuration settings from <file>, if it exists.',
- ['--config'], {'metavar': '<file>', 'type': 'string',
- 'action': 'callback', 'callback': read_config_file}),
+ ['--config'],
+ {'metavar': '<file>', 'type': 'string',
+ 'action': 'callback', 'callback': read_config_file}),
("Show this program's version number and exit.",
- ['--version', '-V'], {'action': 'version'}),
+ ['--version', '-V'],
+ {'action': 'version'}),
('Show this help message and exit.',
- ['--help', '-h'], {'action': 'help'}),
+ ['--help', '-h'],
+ {'action': 'help'}),
# Typically not useful for non-programmatical use:
(SUPPRESS_HELP, ['--id-prefix'], {'default': ''}),
(SUPPRESS_HELP, ['--auto-id-prefix'], {'default': '%'}),
@@ -843,7 +850,7 @@
(SUPPRESS_HELP, ['--dump-transforms'], {'action': 'store_true'}),
(SUPPRESS_HELP, ['--dump-pseudo-xml'], {'action': 'store_true'}),
(SUPPRESS_HELP, ['--expose-internal-attribute'],
- {'action': 'append', 'dest': 'expose_internals',
+ {'dest': 'expose_internals', 'action': 'append',
'validator': validate_colon_separated_string_list}),
(SUPPRESS_HELP, ['--strict-visitor'], {'action': 'store_true'}),
))
Modified: trunk/docutils/docutils/parsers/__init__.py
===================================================================
--- trunk/docutils/docutils/parsers/__init__.py 2026-06-27 17:25:52 UTC (rev 10374)
+++ trunk/docutils/docutils/parsers/__init__.py 2026-06-27 17:26:02 UTC (rev 10375)
@@ -29,9 +29,8 @@
(('Disable directives that insert the contents of an external file; '
'replaced with a "warning" system message.',
['--no-file-insertion'],
- {'action': 'store_false', 'default': True,
- 'dest': 'file_insertion_enabled',
- 'validator': frontend.validate_boolean}),
+ {'dest': 'file_insertion_enabled', 'action': 'store_false',
+ 'default': True, 'validator': frontend.validate_boolean}),
('Enable directives that insert the contents '
'of an external file. (default)',
['--file-insertion-enabled'],
@@ -39,7 +38,7 @@
('Disable the "raw" directive; '
'replaced with a "warning" system message.',
['--no-raw'],
- {'action': 'store_false', 'default': True, 'dest': 'raw_enabled',
+ {'dest': 'raw_enabled', 'action': 'store_false', 'default': True,
'validator': frontend.validate_boolean}),
('Enable the "raw" directive. (default)',
['--raw-enabled'],
@@ -50,20 +49,17 @@
'validator': frontend.validate_nonnegative_int}),
('Keep identifiers backwards compatible. (default)',
['--legacy-ids'],
- {'action': 'store_true',
- 'validator': frontend.validate_boolean,
- 'default': True}),
+ {'action': 'store_true', 'default': True,
+ 'validator': frontend.validate_boolean}),
('Explicit targets use identifiers matching the reference name.',
['--matching-ids'],
- {'action': 'store_false',
- 'dest': 'legacy_ids'}),
+ {'dest': 'legacy_ids', 'action': 'store_false'}),
('Validate the document tree after parsing.',
['--validate'],
- {'action': 'store_true',
- 'validator': frontend.validate_boolean}),
+ {'action': 'store_true', 'validator': frontend.validate_boolean}),
('Do not validate the document tree. (default)',
['--no-validation'],
- {'action': 'store_false', 'dest': 'validate'}),
+ {'dest': 'validate', 'action': 'store_false'}),
)
)
component_type: Final = 'parser'
Modified: trunk/docutils/docutils/parsers/rst/__init__.py
===================================================================
--- trunk/docutils/docutils/parsers/rst/__init__.py 2026-06-27 17:25:52 UTC (rev 10374)
+++ trunk/docutils/docutils/parsers/rst/__init__.py 2026-06-27 17:26:02 UTC (rev 10375)
@@ -116,7 +116,7 @@
{'action': 'store_true', 'validator': frontend.validate_boolean}),
('Leave spaces before footnote references.',
['--leave-footnote-reference-space'],
- {'action': 'store_false', 'dest': 'trim_footnote_reference_space'}),
+ {'dest': 'trim_footnote_reference_space', 'action': 'store_false'}),
('Token name set for parsing code with Pygments: one of '
'"long", "short", or "none" (no parsing). (default: "long")',
['--syntax-highlight'],
@@ -137,13 +137,13 @@
'Force character-level inline markup recognition with '
'"\\ " (backslash + space). (default)',
['--word-level-inline-markup'],
- {'action': 'store_false', 'dest': 'character_level_inline_markup'}),
+ {'dest': 'character_level_inline_markup', 'action': 'store_false',
+ 'validator': frontend.validate_boolean}),
('Inline markup recognized anywhere, regardless of surrounding '
'characters. Backslash-escapes must be used to avoid unwanted '
'markup recognition. Useful for East Asian languages. ',
['--character-level-inline-markup'],
- {'action': 'store_true', 'default': False,
- 'dest': 'character_level_inline_markup'}),
+ {'action': 'store_true'}),
)
)
Modified: trunk/docutils/docutils/writers/_html_base.py
===================================================================
--- trunk/docutils/docutils/writers/_html_base.py 2026-06-27 17:25:52 UTC (rev 10374)
+++ trunk/docutils/docutils/writers/_html_base.py 2026-06-27 17:26:02 UTC (rev 10375)
@@ -128,8 +128,7 @@
'validator': frontend.validate_math_output}),
('Prepend an XML declaration. ',
['--xml-declaration'],
- {'default': False, 'action': 'store_true',
- 'validator': frontend.validate_boolean}),
+ {'action': 'store_true', 'validator': frontend.validate_boolean}),
('Omit the XML declaration.',
['--no-xml-declaration'],
{'dest': 'xml_declaration', 'action': 'store_false'}),
Modified: trunk/docutils/docutils/writers/docutils_xml.py
===================================================================
--- trunk/docutils/docutils/writers/docutils_xml.py 2026-06-27 17:25:52 UTC (rev 10374)
+++ trunk/docutils/docutils/writers/docutils_xml.py 2026-06-27 17:26:02 UTC (rev 10375)
@@ -39,11 +39,11 @@
{'action': 'store_true', 'validator': frontend.validate_boolean}),
('Omit the XML declaration. Use with caution.',
['--no-xml-declaration'],
- {'dest': 'xml_declaration', 'default': 1, 'action': 'store_false',
+ {'dest': 'xml_declaration', 'default': True, 'action': 'store_false',
'validator': frontend.validate_boolean}),
('Omit the DOCTYPE declaration.',
['--no-doctype'],
- {'dest': 'doctype_declaration', 'default': 1,
+ {'dest': 'doctype_declaration', 'default': True,
'action': 'store_false', 'validator': frontend.validate_boolean}),))
settings_defaults = {'output_encoding_error_handler': 'xmlcharrefreplace'}
Modified: trunk/docutils/docutils/writers/html5_polyglot/__init__.py
===================================================================
--- trunk/docutils/docutils/writers/html5_polyglot/__init__.py 2026-06-27 17:25:52 UTC (rev 10374)
+++ trunk/docutils/docutils/writers/html5_polyglot/__init__.py 2026-06-27 17:26:02 UTC (rev 10375)
@@ -99,7 +99,8 @@
}),
('Append a self-link to section headings. (default)',
['--section-self-link'],
- {'default': True, 'action': 'store_true'}),
+ {'default': True, 'action': 'store_true',
+ 'validator': frontend.validate_boolean}),
('Do not append a self-link to section headings.',
['--no-section-self-link'],
{'dest': 'section_self_link', 'action': 'store_false'}),
Modified: trunk/docutils/docutils/writers/latex2e/__init__.py
===================================================================
--- trunk/docutils/docutils/writers/latex2e/__init__.py 2026-06-27 17:25:52 UTC (rev 10374)
+++ trunk/docutils/docutils/writers/latex2e/__init__.py 2026-06-27 17:26:02 UTC (rev 10375)
@@ -60,13 +60,12 @@
'overrides': 'trim_footnote_reference_space'}),
('Use \\cite command for citations. (default)',
['--use-latex-citations'],
- {'default': True, 'action': 'store_true',
+ {'action': 'store_true', 'default': True,
'validator': frontend.validate_boolean}),
('Use figure floats for citations '
'(might get mixed with real figures).',
['--figure-citations'],
- {'dest': 'use_latex_citations', 'action': 'store_false',
- 'validator': frontend.validate_boolean}),
+ {'dest': 'use_latex_citations', 'action': 'store_false'}),
('Format for block quote attributions: one of "dash" (em-dash '
'prefix), "parentheses"/"parens", or "none". (default: "dash")',
['--attribution'],
@@ -89,19 +88,18 @@
'validator': frontend.validate_comma_separated_list}),
('Link to the stylesheet(s) in the output file. (default)',
['--link-stylesheet'],
- {'dest': 'embed_stylesheet', 'action': 'store_false'}),
+ {'dest': 'embed_stylesheet', 'action': 'store_false',
+ 'validator': frontend.validate_boolean}),
('Embed the stylesheet(s) in the output file. '
'Stylesheets must be accessible during processing. ',
['--embed-stylesheet'],
- {'default': False, 'action': 'store_true',
- 'validator': frontend.validate_boolean}),
+ {'action': 'store_true'}),
('Comma-separated list of directories where stylesheets are found. '
'Used by --stylesheet-path when expanding relative path arguments. '
'(default: ".")',
['--stylesheet-dirs'],
- {'metavar': '<dir[,dir,...]>',
- 'validator': frontend.validate_comma_separated_list,
- 'default': ['.']}),
+ {'metavar': '<dir[,dir,...]>', 'default': ['.'],
+ 'validator': frontend.validate_comma_separated_list}),
('Customization by LaTeX code in the preamble. '
'Default: select PDF standard fonts (Times, Helvetica, Courier).',
['--latex-preamble'],
@@ -111,16 +109,14 @@
{'default': default_template, 'metavar': '<file>'}),
('Table of contents by LaTeX. (default)',
['--use-latex-toc'],
- {'default': True, 'action': 'store_true',
+ {'action': 'store_true', 'default': True,
'validator': frontend.validate_boolean}),
('Table of contents by Docutils (without page numbers).',
['--use-docutils-toc'],
- {'dest': 'use_latex_toc', 'action': 'store_false',
- 'validator': frontend.validate_boolean}),
+ {'dest': 'use_latex_toc', 'action': 'store_false'}),
('Add parts on top of the section hierarchy.',
['--use-part-section'],
- {'default': False, 'action': 'store_true',
- 'validator': frontend.validate_boolean}),
+ {'action': 'store_true', 'validator': frontend.validate_boolean}),
('Attach author and date to the document info table. (default)',
['--use-docutils-docinfo'],
{'dest': 'use_latex_docinfo', 'action': 'store_false',
@@ -127,8 +123,7 @@
'validator': frontend.validate_boolean}),
('Attach author and date to the document title.',
['--use-latex-docinfo'],
- {'default': False, 'action': 'store_true',
- 'validator': frontend.validate_boolean}),
+ {'action': 'store_true'}),
("Typeset abstract as topic. (default)",
['--topic-abstract'],
{'dest': 'use_latex_abstract', 'action': 'store_false',
@@ -135,8 +130,7 @@
'validator': frontend.validate_boolean}),
("Use LaTeX abstract environment for the document's abstract.",
['--use-latex-abstract'],
- {'default': False, 'action': 'store_true',
- 'validator': frontend.validate_boolean}),
+ {'action': 'store_true'}),
('Color of any hyperlinks embedded in text. '
'Default: "blue" (use "false" to disable).',
['--hyperlink-color'],
@@ -147,20 +141,18 @@
('Enable compound enumerators for nested enumerated lists '
'(e.g. "1.2.a.ii").',
['--compound-enumerators'],
- {'default': False, 'action': 'store_true',
- 'validator': frontend.validate_boolean}),
+ {'action': 'store_true', 'validator': frontend.validate_boolean}),
('Disable compound enumerators for nested enumerated lists. '
'(default)',
['--no-compound-enumerators'],
- {'action': 'store_false', 'dest': 'compound_enumerators'}),
+ {'dest': 'compound_enumerators', 'action': 'store_false'}),
('Enable section ("." subsection ...) prefixes for compound '
'enumerators. This has no effect without --compound-enumerators.',
['--section-prefix-for-enumerators'],
- {'default': None, 'action': 'store_true',
- 'validator': frontend.validate_boolean}),
+ {'action': 'store_true', 'validator': frontend.validate_boolean}),
('Disable section prefixes for compound enumerators. (default)',
['--no-section-prefix-for-enumerators'],
- {'action': 'store_false', 'dest': 'section_prefix_for_enumerators'}),
+ {'dest': 'section_prefix_for_enumerators', 'action': 'store_false'}),
('Set the separator between section number and enumerator '
'for compound enumerated lists. (default: "-")',
['--section-enumerator-separator'],
@@ -171,8 +163,7 @@
{'metavar': '<environment>', 'default': ''}),
(frontend.SUPPRESS_HELP, # deprecated legacy option
['--use-verbatim-when-possible'],
- {'action': 'store_true',
- 'validator': frontend.validate_boolean}),
+ {'action': 'store_true', 'validator': frontend.validate_boolean}),
('Table style. "standard" with horizontal and vertical lines, '
'"booktabs" (LaTeX booktabs style) only horizontal lines '
'above and below the table and below the header, or "borderless". '
@@ -205,35 +196,24 @@
('Use legacy functions with class value list for '
'\\DUtitle and \\DUadmonition.',
['--legacy-class-functions'],
- {'default': False,
- 'action': 'store_true',
- 'validator': frontend.validate_boolean}),
+ {'action': 'store_true', 'validator': frontend.validate_boolean}),
('Use \\DUrole and "DUclass" wrappers for class values. '
'Place admonition content in an environment. (default)',
['--new-class-functions'],
- {'dest': 'legacy_class_functions',
- 'action': 'store_false',
- 'validator': frontend.validate_boolean}),
+ {'dest': 'legacy_class_functions', 'action': 'store_false'}),
('Use legacy algorithm to determine table column widths. ',
['--legacy-column-widths'],
- {'default': False,
- 'action': 'store_true',
- 'validator': frontend.validate_boolean}),
+ {'action': 'store_true', 'validator': frontend.validate_boolean}),
('Use new algorithm to determine table column widths. (default)',
['--new-column-widths'],
- {'dest': 'legacy_column_widths',
- 'action': 'store_false',
- 'validator': frontend.validate_boolean}),
+ {'dest': 'legacy_column_widths', 'action': 'store_false'}),
('Footnotes with numbers/symbols by Docutils. (default)',
['--docutils-footnotes'],
- {'dest': 'latex_footnotes',
- 'action': 'store_false',
+ {'dest': 'latex_footnotes', 'action': 'store_false',
'validator': frontend.validate_boolean}),
('Footnotes with numbers by LaTeX.',
['--latex-footnotes'],
- {'action': 'store_true',
- 'default': False,
- 'validator': frontend.validate_boolean}),
+ {'action': 'store_true', 'default': False}),
),
)
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
|
From: <mi...@us...> - 2026-06-27 17:25:55
|
Revision: 10374
http://sourceforge.net/p/docutils/code/10374
Author: milde
Date: 2026-06-27 17:25:52 +0000 (Sat, 27 Jun 2026)
Log Message:
-----------
Update command-line help.
Use more consistent style.
After 10 years, character_level_inline_markup is no longer "experimental".
Modified Paths:
--------------
trunk/docutils/docutils/frontend.py
trunk/docutils/docutils/parsers/__init__.py
trunk/docutils/docutils/parsers/rst/__init__.py
trunk/docutils/docutils/writers/latex2e/__init__.py
trunk/docutils/test/data/help/docutils.rst
trunk/docutils/test/data/help/rst2html.rst
trunk/docutils/test/data/help/rst2latex.rst
Modified: trunk/docutils/docutils/frontend.py
===================================================================
--- trunk/docutils/docutils/frontend.py 2026-06-27 17:25:07 UTC (rev 10373)
+++ trunk/docutils/docutils/frontend.py 2026-06-27 17:25:52 UTC (rev 10374)
@@ -685,7 +685,7 @@
settings_spec = (
'General Docutils Options',
None,
- (('Output destination name. Default: None (stdout).',
+ (('Output destination name. (default: stdout)',
['--output', '-o'], {'metavar': '<destination>',
'dest': 'output_path'}),
('Specify the document title as metadata.',
@@ -706,7 +706,7 @@
['--no-datestamp'], {'action': 'store_const', 'const': None,
'dest': 'datestamp'}),
('Base directory for absolute paths when reading '
- 'from the local filesystem. Default "".',
+ 'from the local filesystem. (default: "")',
['--root-prefix'],
{'default': '', 'metavar': '<path>'}),
('Include a "View document source" link.',
@@ -750,13 +750,13 @@
{'action': 'store_false', 'dest': 'strip_comments'}),
('Remove all elements with classes="<class>" from the document tree. '
'Warning: potentially dangerous; use with caution. '
- '(Multiple-use option.)',
+ '(multiple-use option.)',
['--strip-elements-with-class'],
{'action': 'append', 'dest': 'strip_elements_with_classes',
'metavar': '<class>', 'validator': validate_strip_class}),
('Remove all classes="<class>" attributes from elements in the '
'document tree. Warning: potentially dangerous; use with caution. '
- '(Multiple-use option.)',
+ '(multiple-use option.)',
['--strip-class'],
{'action': 'append', 'dest': 'strip_classes',
'metavar': '<class>', 'validator': validate_strip_class}),
@@ -798,7 +798,7 @@
('Disable Python tracebacks. (default)',
['--no-traceback'], {'dest': 'traceback', 'action': 'store_false'}),
('Specify the encoding and optionally the '
- 'error handler of input text. Default: utf-8.',
+ 'error handler of input text. (default: utf-8)',
['--input-encoding'],
{'metavar': '<name[:handler]>', 'default': 'utf-8',
'validator': validate_encoding_and_error_handler}),
@@ -805,7 +805,7 @@
(SUPPRESS_HELP, ['--input-encoding-error-handler'],
{'default': 'strict', 'validator': validate_encoding_error_handler}),
('Specify the text encoding and optionally the error handler for '
- 'output. Default: utf-8.',
+ 'output. (default: utf-8)',
['--output-encoding'],
{'metavar': '<name[:handler]>', 'default': 'utf-8',
'validator': validate_encoding_and_error_handler}),
@@ -812,7 +812,7 @@
(SUPPRESS_HELP, ['--output-encoding-error-handler'],
{'default': 'strict', 'validator': validate_encoding_error_handler}),
('Specify text encoding and optionally the error handler'
- f' for error output. Default: {default_error_encoding}.',
+ f' for error output. (default: {default_error_encoding})',
['--error-encoding', '-e'],
{'metavar': '<name[:handler]>', 'default': default_error_encoding,
'validator': validate_encoding_and_error_handler}),
@@ -819,7 +819,7 @@
(SUPPRESS_HELP, ['--error-encoding-error-handler'],
{'default': default_error_encoding_error_handler,
'validator': validate_encoding_error_handler}),
- ('Specify the language (as BCP 47 language tag). Default: en.',
+ ('Specify the language (as BCP 47 language tag). (default: en)',
['--language', '-l'], {'dest': 'language_code', 'default': 'en',
'metavar': '<tag>'}),
('Write output file dependencies to <file>.',
Modified: trunk/docutils/docutils/parsers/__init__.py
===================================================================
--- trunk/docutils/docutils/parsers/__init__.py 2026-06-27 17:25:07 UTC (rev 10373)
+++ trunk/docutils/docutils/parsers/__init__.py 2026-06-27 17:25:52 UTC (rev 10374)
@@ -44,11 +44,11 @@
('Enable the "raw" directive. (default)',
['--raw-enabled'],
{'action': 'store_true'}),
- ('Maximal number of characters in an input line. Default 10 000.',
+ ('Maximal number of characters in an input line. (default 10 000)',
['--line-length-limit'],
{'metavar': '<length>', 'type': 'int', 'default': 10_000,
'validator': frontend.validate_nonnegative_int}),
- ('Keep identifiers backwards compatible. Default.',
+ ('Keep identifiers backwards compatible. (default)',
['--legacy-ids'],
{'action': 'store_true',
'validator': frontend.validate_boolean,
Modified: trunk/docutils/docutils/parsers/rst/__init__.py
===================================================================
--- trunk/docutils/docutils/parsers/rst/__init__.py 2026-06-27 17:25:07 UTC (rev 10373)
+++ trunk/docutils/docutils/parsers/rst/__init__.py 2026-06-27 17:25:52 UTC (rev 10374)
@@ -118,12 +118,12 @@
['--leave-footnote-reference-space'],
{'action': 'store_false', 'dest': 'trim_footnote_reference_space'}),
('Token name set for parsing code with Pygments: one of '
- '"long", "short", or "none" (no parsing). Default is "long".',
+ '"long", "short", or "none" (no parsing). (default: "long")',
['--syntax-highlight'],
{'choices': ['long', 'short', 'none'],
'default': 'long', 'metavar': '<format>'}),
('Change straight quotation marks to typographic form: '
- 'one of "yes", "no", "alt[ernative]" (default "no").',
+ 'one of "yes", "no", "alt[ernative]". (default: "no")',
['--smart-quotes'],
{'default': False, 'metavar': '<yes/no/alt>',
'validator': frontend.validate_ternary}),
@@ -135,13 +135,12 @@
('Inline markup recognized at word boundaries only '
'(adjacent to punctuation or whitespace). '
'Force character-level inline markup recognition with '
- '"\\ " (backslash + space). Default.',
+ '"\\ " (backslash + space). (default)',
['--word-level-inline-markup'],
{'action': 'store_false', 'dest': 'character_level_inline_markup'}),
('Inline markup recognized anywhere, regardless of surrounding '
'characters. Backslash-escapes must be used to avoid unwanted '
- 'markup recognition. Useful for East Asian languages. '
- 'Experimental.',
+ 'markup recognition. Useful for East Asian languages. ',
['--character-level-inline-markup'],
{'action': 'store_true', 'default': False,
'dest': 'character_level_inline_markup'}),
Modified: trunk/docutils/docutils/writers/latex2e/__init__.py
===================================================================
--- trunk/docutils/docutils/writers/latex2e/__init__.py 2026-06-27 17:25:07 UTC (rev 10373)
+++ trunk/docutils/docutils/writers/latex2e/__init__.py 2026-06-27 17:25:52 UTC (rev 10374)
@@ -45,15 +45,15 @@
settings_spec = (
'LaTeX-Specific Options',
None,
- (('Specify LaTeX documentclass. Default: "article".',
+ (('Specify LaTeX documentclass. (default: "article")',
['--documentclass'],
{'metavar': '<documentclass>', 'default': 'article'}),
('Specify document options. Multiple options can be given, '
- 'separated by commas. Default: "a4paper".',
+ 'separated by commas. (default: "a4paper")',
['--documentoptions'],
{'metavar': '<options>', 'default': 'a4paper'}),
('Format for footnote references: one of "superscript" or '
- '"brackets". Default: "superscript".',
+ '"brackets". (default: "superscript")',
['--footnote-references'],
{'choices': ['superscript', 'brackets'], 'default': 'superscript',
'metavar': '<format>',
@@ -68,7 +68,7 @@
{'dest': 'use_latex_citations', 'action': 'store_false',
'validator': frontend.validate_boolean}),
('Format for block quote attributions: one of "dash" (em-dash '
- 'prefix), "parentheses"/"parens", or "none". Default: "dash".',
+ 'prefix), "parentheses"/"parens", or "none". (default: "dash")',
['--attribution'],
{'choices': ['dash', 'parentheses', 'parens', 'none'],
'default': 'dash', 'metavar': '<format>'}),
@@ -96,8 +96,8 @@
{'default': False, 'action': 'store_true',
'validator': frontend.validate_boolean}),
('Comma-separated list of directories where stylesheets are found. '
- 'Used by --stylesheet-path when expanding relative path arguments. '
- 'Default: ".".',
+ 'Used by --stylesheet-path when expanding relative path arguments. '
+ '(default: ".")',
['--stylesheet-dirs'],
{'metavar': '<dir[,dir,...]>',
'validator': frontend.validate_comma_separated_list,
@@ -106,10 +106,10 @@
'Default: select PDF standard fonts (Times, Helvetica, Courier).',
['--latex-preamble'],
{'metavar': '<preamble>', 'default': default_preamble}),
- ('Specify the template file. Default: "%s".' % default_template,
+ (f'Specify the template file. (default: "{default_template}")',
['--template'],
{'default': default_template, 'metavar': '<file>'}),
- ('Table of contents by LaTeX. (default)',
+ ('Table of contents by LaTeX. (default)',
['--use-latex-toc'],
{'default': True, 'action': 'store_true',
'validator': frontend.validate_boolean}),
@@ -162,7 +162,7 @@
['--no-section-prefix-for-enumerators'],
{'action': 'store_false', 'dest': 'section_prefix_for_enumerators'}),
('Set the separator between section number and enumerator '
- 'for compound enumerated lists. Default: "-".',
+ 'for compound enumerated lists. (default: "-")',
['--section-enumerator-separator'],
{'default': '-', 'metavar': '<char>'}),
('When possible, use the specified environment for literal-blocks. '
@@ -175,8 +175,8 @@
'validator': frontend.validate_boolean}),
('Table style. "standard" with horizontal and vertical lines, '
'"booktabs" (LaTeX booktabs style) only horizontal lines '
- 'above and below the table and below the header, or "borderless". '
- 'Default: "standard"',
+ 'above and below the table and below the header, or "borderless". '
+ '(default: "standard")',
['--table-style'],
{'default': ['standard'],
'metavar': '<format>',
@@ -183,7 +183,7 @@
'action': 'append',
'validator': frontend.validate_comma_separated_list,
'choices': table_style_values}),
- ('LaTeX graphicx package option. Default: "".',
+ ('LaTeX graphicx package option. (default: "")',
['--graphicx-option'],
{'metavar': '<option>', 'default': ''}),
('LaTeX font encoding. '
Modified: trunk/docutils/test/data/help/docutils.rst
===================================================================
--- trunk/docutils/test/data/help/docutils.rst 2026-06-27 17:25:07 UTC (rev 10373)
+++ trunk/docutils/test/data/help/docutils.rst 2026-06-27 17:25:52 UTC (rev 10374)
@@ -12,7 +12,7 @@
General Docutils Options
------------------------
--output=<destination>, -o <destination>
- Output destination name. Default: None (stdout).
+ Output destination name. (default: stdout)
--title=<title> Specify the document title as metadata.
--generator, -g Include a "Generated by Docutils" credit and link.
--no-generator Do not include a generator credit.
@@ -20,7 +20,7 @@
--time, -t Include the time & date (UTC).
--no-datestamp Do not include a datestamp of any kind.
--root-prefix=<path> Base directory for absolute paths when reading from
- the local filesystem. Default "".
+ the local filesystem. (default: "")
--source-link, -s Include a "View document source" link.
--source-url=<URL> Use <URL> for a source link; implies --source-link.
--no-source-link Do not include a "View document source" link.
@@ -37,10 +37,10 @@
--strip-elements-with-class=<class>
Remove all elements with classes="<class>" from the
document tree. Warning: potentially dangerous; use
- with caution. (Multiple-use option.)
+ with caution. (multiple-use option.)
--strip-class=<class> Remove all classes="<class>" attributes from elements
in the document tree. Warning: potentially dangerous;
- use with caution. (Multiple-use option.)
+ use with caution. (multiple-use option.)
--report=<level>, -r <level>
Report system messages at or higher than <level>:
"info" or "1", "warning"/"2" (default), "error"/"3",
@@ -59,16 +59,16 @@
--no-traceback Disable Python tracebacks. (default)
--input-encoding=<name[:handler]>
Specify the encoding and optionally the error handler
- of input text. Default: utf-8.
+ of input text. (default: utf-8)
--output-encoding=<name[:handler]>
Specify the text encoding and optionally the error
- handler for output. Default: utf-8.
+ handler for output. (default: utf-8)
--error-encoding=<name[:handler]>, -e <name[:handler]>
Specify text encoding and optionally the error handler
- for error output. Default: utf-8.
+ for error output. (default: utf-8)
--language=<tag>, -l <tag>
Specify the language (as BCP 47 language tag).
- Default: en.
+ (default: en)
--record-dependencies=<file>
Write output file dependencies to <file>.
--config=<file> Read configuration settings from <file>, if it exists.
@@ -87,9 +87,9 @@
system message.
--raw-enabled Enable the "raw" directive. (default)
--line-length-limit=<length>
- Maximal number of characters in an input line. Default
- 10 000.
---legacy-ids Keep identifiers backwards compatible. Default.
+ Maximal number of characters in an input line.
+ (default 10 000)
+--legacy-ids Keep identifiers backwards compatible. (default)
--matching-ids Explicit targets use identifiers matching the
reference name.
--validate Validate the document tree after parsing.
@@ -115,11 +115,11 @@
Leave spaces before footnote references.
--syntax-highlight=<format>
Token name set for parsing code with Pygments: one of
- "long", "short", or "none" (no parsing). Default is
- "long".
+ "long", "short", or "none" (no parsing).
+ (default: "long")
--smart-quotes=<yes/no/alt>
Change straight quotation marks to typographic form:
- one of "yes", "no", "alt[ernative]" (default "no").
+ one of "yes", "no", "alt[ernative]". (default: "no")
--smartquotes-locales=<language:quotes[,language:quotes,...]>
Characters to use as "smart quotes" for <language>.
--word-level-inline-markup
@@ -126,12 +126,12 @@
Inline markup recognized at word boundaries only
(adjacent to punctuation or whitespace). Force
character-level inline markup recognition with "\ "
- (backslash + space). Default.
+ (backslash + space). (default)
--character-level-inline-markup
Inline markup recognized anywhere, regardless of
surrounding characters. Backslash-escapes must be used
to avoid unwanted markup recognition. Useful for East
- Asian languages. Experimental.
+ Asian languages.
Standalone Reader Options
-------------------------
Modified: trunk/docutils/test/data/help/rst2html.rst
===================================================================
--- trunk/docutils/test/data/help/rst2html.rst 2026-06-27 17:25:07 UTC (rev 10373)
+++ trunk/docutils/test/data/help/rst2html.rst 2026-06-27 17:25:52 UTC (rev 10374)
@@ -13,7 +13,7 @@
General Docutils Options
------------------------
--output=<destination>, -o <destination>
- Output destination name. Default: None (stdout).
+ Output destination name. (default: stdout)
--title=<title> Specify the document title as metadata.
--generator, -g Include a "Generated by Docutils" credit and link.
--no-generator Do not include a generator credit.
@@ -21,7 +21,7 @@
--time, -t Include the time & date (UTC).
--no-datestamp Do not include a datestamp of any kind.
--root-prefix=<path> Base directory for absolute paths when reading from
- the local filesystem. Default "".
+ the local filesystem. (default: "")
--source-link, -s Include a "View document source" link.
--source-url=<URL> Use <URL> for a source link; implies --source-link.
--no-source-link Do not include a "View document source" link.
@@ -38,10 +38,10 @@
--strip-elements-with-class=<class>
Remove all elements with classes="<class>" from the
document tree. Warning: potentially dangerous; use
- with caution. (Multiple-use option.)
+ with caution. (multiple-use option.)
--strip-class=<class> Remove all classes="<class>" attributes from elements
in the document tree. Warning: potentially dangerous;
- use with caution. (Multiple-use option.)
+ use with caution. (multiple-use option.)
--report=<level>, -r <level>
Report system messages at or higher than <level>:
"info" or "1", "warning"/"2" (default), "error"/"3",
@@ -60,16 +60,16 @@
--no-traceback Disable Python tracebacks. (default)
--input-encoding=<name[:handler]>
Specify the encoding and optionally the error handler
- of input text. Default: utf-8.
+ of input text. (default: utf-8)
--output-encoding=<name[:handler]>
Specify the text encoding and optionally the error
- handler for output. Default: utf-8.
+ handler for output. (default: utf-8)
--error-encoding=<name[:handler]>, -e <name[:handler]>
Specify text encoding and optionally the error handler
- for error output. Default: utf-8.
+ for error output. (default: utf-8)
--language=<tag>, -l <tag>
Specify the language (as BCP 47 language tag).
- Default: en.
+ (default: en)
--record-dependencies=<file>
Write output file dependencies to <file>.
--config=<file> Read configuration settings from <file>, if it exists.
@@ -88,9 +88,9 @@
system message.
--raw-enabled Enable the "raw" directive. (default)
--line-length-limit=<length>
- Maximal number of characters in an input line. Default
- 10 000.
---legacy-ids Keep identifiers backwards compatible. Default.
+ Maximal number of characters in an input line.
+ (default 10 000)
+--legacy-ids Keep identifiers backwards compatible. (default)
--matching-ids Explicit targets use identifiers matching the
reference name.
--validate Validate the document tree after parsing.
@@ -116,11 +116,11 @@
Leave spaces before footnote references.
--syntax-highlight=<format>
Token name set for parsing code with Pygments: one of
- "long", "short", or "none" (no parsing). Default is
- "long".
+ "long", "short", or "none" (no parsing).
+ (default: "long")
--smart-quotes=<yes/no/alt>
Change straight quotation marks to typographic form:
- one of "yes", "no", "alt[ernative]" (default "no").
+ one of "yes", "no", "alt[ernative]". (default: "no")
--smartquotes-locales=<language:quotes[,language:quotes,...]>
Characters to use as "smart quotes" for <language>.
--word-level-inline-markup
@@ -127,12 +127,12 @@
Inline markup recognized at word boundaries only
(adjacent to punctuation or whitespace). Force
character-level inline markup recognition with "\ "
- (backslash + space). Default.
+ (backslash + space). (default)
--character-level-inline-markup
Inline markup recognized anywhere, regardless of
surrounding characters. Backslash-escapes must be used
to avoid unwanted markup recognition. Useful for East
- Asian languages. Experimental.
+ Asian languages.
Standalone Reader Options
-------------------------
Modified: trunk/docutils/test/data/help/rst2latex.rst
===================================================================
--- trunk/docutils/test/data/help/rst2latex.rst 2026-06-27 17:25:07 UTC (rev 10373)
+++ trunk/docutils/test/data/help/rst2latex.rst 2026-06-27 17:25:52 UTC (rev 10374)
@@ -13,7 +13,7 @@
General Docutils Options
------------------------
--output=<destination>, -o <destination>
- Output destination name. Default: None (stdout).
+ Output destination name. (default: stdout)
--title=<title> Specify the document title as metadata.
--generator, -g Include a "Generated by Docutils" credit and link.
--no-generator Do not include a generator credit.
@@ -21,7 +21,7 @@
--time, -t Include the time & date (UTC).
--no-datestamp Do not include a datestamp of any kind.
--root-prefix=<path> Base directory for absolute paths when reading from
- the local filesystem. Default "".
+ the local filesystem. (default: "")
--source-link, -s Include a "View document source" link.
--source-url=<URL> Use <URL> for a source link; implies --source-link.
--no-source-link Do not include a "View document source" link.
@@ -38,10 +38,10 @@
--strip-elements-with-class=<class>
Remove all elements with classes="<class>" from the
document tree. Warning: potentially dangerous; use
- with caution. (Multiple-use option.)
+ with caution. (multiple-use option.)
--strip-class=<class> Remove all classes="<class>" attributes from elements
in the document tree. Warning: potentially dangerous;
- use with caution. (Multiple-use option.)
+ use with caution. (multiple-use option.)
--report=<level>, -r <level>
Report system messages at or higher than <level>:
"info" or "1", "warning"/"2" (default), "error"/"3",
@@ -60,16 +60,16 @@
--no-traceback Disable Python tracebacks. (default)
--input-encoding=<name[:handler]>
Specify the encoding and optionally the error handler
- of input text. Default: utf-8.
+ of input text. (default: utf-8)
--output-encoding=<name[:handler]>
Specify the text encoding and optionally the error
- handler for output. Default: utf-8.
+ handler for output. (default: utf-8)
--error-encoding=<name[:handler]>, -e <name[:handler]>
Specify text encoding and optionally the error handler
- for error output. Default: utf-8.
+ for error output. (default: utf-8)
--language=<tag>, -l <tag>
Specify the language (as BCP 47 language tag).
- Default: en.
+ (default: en)
--record-dependencies=<file>
Write output file dependencies to <file>.
--config=<file> Read configuration settings from <file>, if it exists.
@@ -88,9 +88,9 @@
system message.
--raw-enabled Enable the "raw" directive. (default)
--line-length-limit=<length>
- Maximal number of characters in an input line. Default
- 10 000.
---legacy-ids Keep identifiers backwards compatible. Default.
+ Maximal number of characters in an input line.
+ (default 10 000)
+--legacy-ids Keep identifiers backwards compatible. (default)
--matching-ids Explicit targets use identifiers matching the
reference name.
--validate Validate the document tree after parsing.
@@ -116,11 +116,11 @@
Leave spaces before footnote references.
--syntax-highlight=<format>
Token name set for parsing code with Pygments: one of
- "long", "short", or "none" (no parsing). Default is
- "long".
+ "long", "short", or "none" (no parsing).
+ (default: "long")
--smart-quotes=<yes/no/alt>
Change straight quotation marks to typographic form:
- one of "yes", "no", "alt[ernative]" (default "no").
+ one of "yes", "no", "alt[ernative]". (default: "no")
--smartquotes-locales=<language:quotes[,language:quotes,...]>
Characters to use as "smart quotes" for <language>.
--word-level-inline-markup
@@ -127,12 +127,12 @@
Inline markup recognized at word boundaries only
(adjacent to punctuation or whitespace). Force
character-level inline markup recognition with "\ "
- (backslash + space). Default.
+ (backslash + space). (default)
--character-level-inline-markup
Inline markup recognized anywhere, regardless of
surrounding characters. Backslash-escapes must be used
to avoid unwanted markup recognition. Useful for East
- Asian languages. Experimental.
+ Asian languages.
Standalone Reader Options
-------------------------
@@ -148,19 +148,19 @@
LaTeX-Specific Options
----------------------
--documentclass=<documentclass>
- Specify LaTeX documentclass. Default: "article".
+ Specify LaTeX documentclass. (default: "article")
--documentoptions=<options>
Specify document options. Multiple options can be
- given, separated by commas. Default: "a4paper".
+ given, separated by commas. (default: "a4paper")
--footnote-references=<format>
Format for footnote references: one of "superscript"
- or "brackets". Default: "superscript".
+ or "brackets". (default: "superscript")
--use-latex-citations Use \cite command for citations. (default)
--figure-citations Use figure floats for citations (might get mixed with
real figures).
--attribution=<format> Format for block quote attributions: one of "dash"
(em-dash prefix), "parentheses"/"parens", or "none".
- Default: "dash".
+ (default: "dash")
--stylesheet=<file[,file,...]>
Specify LaTeX packages/stylesheets. A style is
referenced with "\usepackage" if extension is ".sty"
@@ -179,12 +179,12 @@
--stylesheet-dirs=<dir[,dir,...]>
Comma-separated list of directories where stylesheets
are found. Used by --stylesheet-path when expanding
- relative path arguments. Default: ".".
+ relative path arguments. (default: ".")
--latex-preamble=<preamble>
Customization by LaTeX code in the preamble. Default:
select PDF standard fonts (Times, Helvetica, Courier).
---template=<file> Specify the template file. Default: "default.tex".
---use-latex-toc Table of contents by LaTeX. (default)
+--template=<file> Specify the template file. (default: "default.tex")
+--use-latex-toc Table of contents by LaTeX. (default)
--use-docutils-toc Table of contents by Docutils (without page numbers).
--use-part-section Add parts on top of the section hierarchy.
--use-docutils-docinfo Attach author and date to the document info table.
@@ -212,8 +212,8 @@
(default)
--section-enumerator-separator=<char>
Set the separator between section number and
- enumerator for compound enumerated lists. Default:
- "-".
+ enumerator for compound enumerated lists.
+ (default: "-")
--literal-block-env=<environment>
When possible, use the specified environment for
literal-blocks. Default: "" (fall back to "alltt").
@@ -220,9 +220,9 @@
--table-style=<format> Table style. "standard" with horizontal and vertical
lines, "booktabs" (LaTeX booktabs style) only
horizontal lines above and below the table and below
- the header, or "borderless". Default: "standard"
+ the header, or "borderless". (default: "standard")
--graphicx-option=<option>
- LaTeX graphicx package option. Default: "".
+ LaTeX graphicx package option. (default: "")
--font-encoding=<encoding>
LaTeX font encoding. Possible values are "", "T1"
(default), "OT1", "LGR,T1" or any other combination of
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
|
From: <mi...@us...> - 2026-06-27 17:25:09
|
Revision: 10373
http://sourceforge.net/p/docutils/code/10373
Author: milde
Date: 2026-06-27 17:25:07 +0000 (Sat, 27 Jun 2026)
Log Message:
-----------
Imrove readability of generated HTML5 document source.
Add newlines to the `<span>` elements used for additional IDs
if the context allows. Makes affected section title lines a bit shorter.
Modified Paths:
--------------
trunk/docutils/HISTORY.rst
trunk/docutils/docutils/writers/_html_base.py
trunk/docutils/test/functional/expected/misc_rst_html4css1.html
trunk/docutils/test/functional/expected/misc_rst_html5.html
trunk/docutils/test/functional/expected/standalone_rst_html4css1.html
trunk/docutils/test/functional/expected/standalone_rst_html5.html
Modified: trunk/docutils/HISTORY.rst
===================================================================
--- trunk/docutils/HISTORY.rst 2026-06-26 10:26:58 UTC (rev 10372)
+++ trunk/docutils/HISTORY.rst 2026-06-27 17:25:07 UTC (rev 10373)
@@ -520,6 +520,9 @@
- Add "px" to unitless table "width" values.
- Fix error when determining the document metadata title from the
source path and the internal `source` attribute is None.
+ - `HTMLTranslator.starttag()`: Add newlines to the `<span>` elements
+ used for additional IDs if the `suffix` argument starts with "\n"
+ (indicating that it is OK to add whitespace).
* docutils/writers/html4css1/__init__.py
Modified: trunk/docutils/docutils/writers/_html_base.py
===================================================================
--- trunk/docutils/docutils/writers/_html_base.py 2026-06-26 10:26:58 UTC (rev 10372)
+++ trunk/docutils/docutils/writers/_html_base.py 2026-06-27 17:25:07 UTC (rev 10373)
@@ -580,20 +580,20 @@
if ids:
atts['id'] = ids[0]
for id in ids[1:]:
- # Add empty "span" elements for additional IDs. Note
- # that we cannot use empty "a" elements because there
- # may be targets inside of references, but nested "a"
- # elements aren't allowed in XHTML (even if they do
- # not all have a "href" attribute).
+ # Add empty "span" elements for additional IDs:
if empty or isinstance(node, (nodes.Sequential,
nodes.docinfo,
nodes.table)):
# Insert target right in front of element.
prefix.append('<span id="%s"></span>' % id)
+ if suffix.startswith('\n'):
+ prefix.append('\n')
else:
# Non-empty tag. Place the auxiliary <span> tag
# *inside* the element, as the first child.
- suffix += '<span id="%s"></span>' % id
+ suffix += f'<span id="{id}"></span>'
+ if suffix.startswith('\n'):
+ suffix += '\n'
attlist = sorted(atts.items())
parts = [tagname]
for name, value in attlist:
Modified: trunk/docutils/test/functional/expected/misc_rst_html4css1.html
===================================================================
--- trunk/docutils/test/functional/expected/misc_rst_html4css1.html 2026-06-26 10:26:58 UTC (rev 10372)
+++ trunk/docutils/test/functional/expected/misc_rst_html4css1.html 2026-06-27 17:25:07 UTC (rev 10373)
@@ -50,7 +50,8 @@
</div>
</div>
<div class="section" id="section-titles-with-inline-markup">
-<span id="references"></span><h1>Section titles with inline markup</h1>
+<span id="references"></span>
+<h1>Section titles with inline markup</h1>
<div class="section" id="emphasized-h2o-x-2-and-references">
<h2><em>emphasized</em>, H<sub>2</sub>O, <span class="formula"><i>x</i><sup>2</sup></span>, and <a class="reference internal" href="#references">references</a></h2>
</div>
Modified: trunk/docutils/test/functional/expected/misc_rst_html5.html
===================================================================
--- trunk/docutils/test/functional/expected/misc_rst_html5.html 2026-06-26 10:26:58 UTC (rev 10372)
+++ trunk/docutils/test/functional/expected/misc_rst_html5.html 2026-06-27 17:25:07 UTC (rev 10373)
@@ -97,7 +97,8 @@
</section>
</section>
<section id="section-titles-with-inline-markup">
-<span id="references"></span><h2><a class="toc-backref" href="#contents" role="doc-backlink">Section titles with inline markup</a><a class="self-link" title="link to this section" href="#references"></a></h2>
+<span id="references"></span>
+<h2><a class="toc-backref" href="#contents" role="doc-backlink">Section titles with inline markup</a><a class="self-link" title="link to this section" href="#references"></a></h2>
<section id="emphasized-h2o-x-2-and-references">
<h3><em>emphasized</em>, H<sub>2</sub>O, <math xmlns="http://www.w3.org/1998/Math/MathML">
<msup>
Modified: trunk/docutils/test/functional/expected/standalone_rst_html4css1.html
===================================================================
--- trunk/docutils/test/functional/expected/standalone_rst_html4css1.html 2026-06-26 10:26:58 UTC (rev 10372)
+++ trunk/docutils/test/functional/expected/standalone_rst_html4css1.html 2026-06-27 17:25:07 UTC (rev 10373)
@@ -534,7 +534,8 @@
citation.</p>
</div>
<div class="section" id="targets">
-<span id="another-target"></span><h2><a class="toc-backref" href="#toc-entry-19">2.13 Targets</a></h2>
+<span id="another-target"></span>
+<h2><a class="toc-backref" href="#toc-entry-19">2.13 Targets</a></h2>
<p id="example">This paragraph is pointed to by the explicit "example" target. A
reference can be found under <a class="reference internal" href="#inline-markup">Inline Markup</a>, above. <a class="reference internal" href="#inline-hyperlink-targets">Inline
hyperlink targets</a> are also possible.</p>
@@ -591,7 +592,9 @@
<img alt="../../../docs/user/rst/images/title.png" class="class1 class2" src="../../../docs/user/rst/images/title.png" style="width: 70%;" />
</a>
<p>Image with multiple IDs:</p>
-<span id="image-target-2"></span><span id="image-target-1"></span><img alt="../../../docs/user/rst/images/biohazard.png" id="image-target-3" src="../../../docs/user/rst/images/biohazard.png" />
+<span id="image-target-2"></span>
+<span id="image-target-1"></span>
+<img alt="../../../docs/user/rst/images/biohazard.png" id="image-target-3" src="../../../docs/user/rst/images/biohazard.png" />
<p>A centered image:</p>
<img alt="../../../docs/user/rst/images/biohazard.png" class="align-center" src="../../../docs/user/rst/images/biohazard.png" />
<p>A left-aligned image:</p>
@@ -745,7 +748,8 @@
<p>With the "widths" argument "auto" (or "class" value "colwidths-auto"),
column widths are determined by the backend (if supported by the
writer/backend).</p>
-<span id="target1"></span><table border="1" class="docutils" id="target2">
+<span id="target1"></span>
+<table border="1" class="docutils" id="target2">
<thead valign="bottom">
<tr><th class="head">A</th>
<th class="head">B</th>
Modified: trunk/docutils/test/functional/expected/standalone_rst_html5.html
===================================================================
--- trunk/docutils/test/functional/expected/standalone_rst_html5.html 2026-06-26 10:26:58 UTC (rev 10372)
+++ trunk/docutils/test/functional/expected/standalone_rst_html5.html 2026-06-27 17:25:07 UTC (rev 10373)
@@ -531,7 +531,8 @@
citation.</p>
</section>
<section id="targets">
-<span id="another-target"></span><h3><a class="toc-backref" href="#toc-entry-19" role="doc-backlink"><span class="sectnum">2.13 </span>Targets</a><a class="self-link" title="link to this section" href="#another-target"></a></h3>
+<span id="another-target"></span>
+<h3><a class="toc-backref" href="#toc-entry-19" role="doc-backlink"><span class="sectnum">2.13 </span>Targets</a><a class="self-link" title="link to this section" href="#another-target"></a></h3>
<p id="example">This paragraph is pointed to by the explicit "example" target. A
reference can be found under <a class="reference internal" href="#inline-markup">Inline Markup</a>, above. <a class="reference internal" href="#inline-hyperlink-targets">Inline
hyperlink targets</a> are also possible.</p>
@@ -588,7 +589,9 @@
<img alt="../../../docs/user/rst/images/title.png" class="class1 class2" src="../../../docs/user/rst/images/title.png" style="width: 70%;" />
</a>
<p>Image with multiple IDs:</p>
-<span id="image-target-2"></span><span id="image-target-1"></span><img alt="../../../docs/user/rst/images/biohazard.png" id="image-target-3" src="../../../docs/user/rst/images/biohazard.png" />
+<span id="image-target-2"></span>
+<span id="image-target-1"></span>
+<img alt="../../../docs/user/rst/images/biohazard.png" id="image-target-3" src="../../../docs/user/rst/images/biohazard.png" />
<p>A centered image:</p>
<img alt="../../../docs/user/rst/images/biohazard.png" class="align-center" src="../../../docs/user/rst/images/biohazard.png" />
<p>A left-aligned image:</p>
@@ -734,7 +737,8 @@
<p>With the "widths" argument "auto" (or "class" value "colwidths-auto"),
column widths are determined by the backend (if supported by the
writer/backend).</p>
-<span id="target1"></span><table id="target2">
+<span id="target1"></span>
+<table id="target2">
<thead>
<tr><th class="head"><p>A</p></th>
<th class="head"><p>B</p></th>
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
|
From: <mi...@us...> - 2026-06-26 10:27:00
|
Revision: 10372
http://sourceforge.net/p/docutils/code/10372
Author: milde
Date: 2026-06-26 10:26:58 +0000 (Fri, 26 Jun 2026)
Log Message:
-----------
"responsive.css": Highlight `<h1>` link target.
Add selectors for `<h1>` to the CSS rule highlighting section headings
if they are the current ":target" in the "responsive.css" stylesheet of the
HTML5 writer.
Since the change of the "initial_header_level" setting default to "auto"
in [r10365], `<h1>` is regularely used for top-level section headings if
there is no document title.
Modified Paths:
--------------
trunk/docutils/HISTORY.rst
trunk/docutils/docutils/writers/html5_polyglot/responsive.css
Modified: trunk/docutils/HISTORY.rst
===================================================================
--- trunk/docutils/HISTORY.rst 2026-06-23 17:20:41 UTC (rev 10371)
+++ trunk/docutils/HISTORY.rst 2026-06-26 10:26:58 UTC (rev 10372)
@@ -69,7 +69,7 @@
- Do not add "name" attribute to `<reference>` elements
nor set the internal attribute `indirect_reference_name`.
- - Warn if a `"figure"`_ directive is missing both caption and legend.
+ - Warn if a "figure" directive is missing both caption and legend.
* docutils/parsers/rst/directives/tables.py
@@ -113,7 +113,7 @@
* docutils/writers/html5_polyglot/*
- Change the default value of the initial_header_level_ setting to "auto"
- (<h2> if there is a document title, else <h1>).
+ (<h2> if there is a document title, else <h1>). Adapt "responsive.css".
- Change the default value of the "section_self_link" setting to True.
- Add CSS rules for back-link and self-link symbols from
"responsive.css" also in "plain.css" and "tuftig.css".
Modified: trunk/docutils/docutils/writers/html5_polyglot/responsive.css
===================================================================
--- trunk/docutils/docutils/writers/html5_polyglot/responsive.css 2026-06-23 17:20:41 UTC (rev 10371)
+++ trunk/docutils/docutils/writers/html5_polyglot/responsive.css 2026-06-26 10:26:58 UTC (rev 10372)
@@ -292,10 +292,10 @@
margin-left: 0.2em;
}
/* highlight specific targets of the current URL */
-section:target > h2, section:target > h3, section:target > h4,
-section:target > h5, section:target > h6,
-span:target + h2, span:target + h3, span:target + h4,
-span:target + h5, span:target + h6,
+section:target > h1, section:target > h2, section:target > h3,
+section:target > h4, section:target > h5, section:target > h6,
+span:target + h1, span:target + h2, span:target + h3,
+span:target + h4, span:target + h5, span:target + h6,
dt:target, span:target, p:target,
.contents :target,
.contents:target > .topic-title,
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
|
From: <mi...@us...> - 2026-06-23 17:20:43
|
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.
|
|
From: <mi...@us...> - 2026-06-23 14:59:30
|
Revision: 10370
http://sourceforge.net/p/docutils/code/10370
Author: milde
Date: 2026-06-23 14:59:27 +0000 (Tue, 23 Jun 2026)
Log Message:
-----------
Warn if a "figure" directive is missing both caption and legend.
The `<figure>` Document Tree element's content model mandates an `<image>`
followed by either a `<caption>` or `<legend>` or both.
As a "power-user feature", an empty comment instead of the caption
silences the parser warning (the "--validate" option will still report
an invalid `<figure>`).
Modified Paths:
--------------
trunk/docutils/HISTORY.rst
trunk/docutils/RELEASE-NOTES.rst
trunk/docutils/docs/ref/rst/directives.rst
trunk/docutils/docutils/parsers/rst/directives/images.py
trunk/docutils/test/data/dependencies.rst
trunk/docutils/test/functional/expected/dangerous.html
trunk/docutils/test/functional/expected/rst_html5_tuftig.html
trunk/docutils/test/functional/input/dangerous.rst
trunk/docutils/test/functional/input/rst_html5_tuftig.rst
trunk/docutils/test/test_parsers/test_rst/test_directives/test_figures.py
trunk/docutils/test/test_writers/test_html4css1.py
trunk/docutils/test/test_writers/test_html5_polyglot.py
Modified: trunk/docutils/HISTORY.rst
===================================================================
--- trunk/docutils/HISTORY.rst 2026-06-23 14:59:13 UTC (rev 10369)
+++ trunk/docutils/HISTORY.rst 2026-06-23 14:59:27 UTC (rev 10370)
@@ -69,6 +69,7 @@
- Do not add "name" attribute to `<reference>` elements
nor set the internal attribute `indirect_reference_name`.
+ - Warn if a `"figure"`_ directive is missing both caption and legend.
* docutils/parsers/rst/directives/tables.py
Modified: trunk/docutils/RELEASE-NOTES.rst
===================================================================
--- trunk/docutils/RELEASE-NOTES.rst 2026-06-23 14:59:13 UTC (rev 10369)
+++ trunk/docutils/RELEASE-NOTES.rst 2026-06-23 14:59:27 UTC (rev 10370)
@@ -79,9 +79,6 @@
Parsers
-------
-* The "rst" parser will warn if a `"figure"`_ directive is missing both
- caption and legend in Docutils 1.0.
-
* The `legacy_ids`_ configuration setting default will change to False
in Docutils 2.0
@@ -241,6 +238,9 @@
- Drop the ``<destination>`` positional argument.
Use ``-o <destination>`` or output redirection.
+rST parser:
+ - Warn if a `"figure"`_ directive is missing both caption and legend.
+
HTML5 writer:
- Use normal font size and colour for informal titles of type "rubric".
- Use more specific CSS selectors for styling <aside> elements as
Modified: trunk/docutils/docs/ref/rst/directives.rst
===================================================================
--- trunk/docutils/docs/ref/rst/directives.rst 2026-06-23 14:59:13 UTC (rev 10369)
+++ trunk/docutils/docs/ref/rst/directives.rst 2026-06-23 14:59:27 UTC (rev 10370)
@@ -376,7 +376,7 @@
+-----------------------+-----------------------+
There must be blank lines before the caption paragraph and before the
-legend. To specify a legend without a caption, use an empty comment
+legend. To specify an image without a caption, use an empty comment
("..") in place of the caption.
.. _figure options:
Modified: trunk/docutils/docutils/parsers/rst/directives/images.py
===================================================================
--- trunk/docutils/docutils/parsers/rst/directives/images.py 2026-06-23 14:59:13 UTC (rev 10369)
+++ trunk/docutils/docutils/parsers/rst/directives/images.py 2026-06-23 14:59:27 UTC (rev 10370)
@@ -155,7 +155,11 @@
self.state.document.note_explicit_target(figure_node, figure_node)
if align:
figure_node['align'] = align
- if self.content:
+ if not self.content:
+ msg = self.reporter.warning('Figure without caption and legend. '
+ 'Use "image"?', line=self.lineno)
+ return [figure_node, msg]
+ else:
# optional caption (single paragraph or empty comment)
# + optional legend (arbitrary body elements).
node = nodes.Element() # anonymous container for parsing
Modified: trunk/docutils/test/data/dependencies.rst
===================================================================
--- trunk/docutils/test/data/dependencies.rst 2026-06-23 14:59:13 UTC (rev 10369)
+++ trunk/docutils/test/data/dependencies.rst 2026-06-23 14:59:27 UTC (rev 10370)
@@ -23,6 +23,10 @@
.. figure:: ../docs/user/rst/images/title.png
:figwidth: image
+ ..
+
+ Image width is read to determine figure width
+
Scaled images without given size are recorded by the html writer:
.. image:: ../docs/user/rst/images/biohazard.png
Modified: trunk/docutils/test/functional/expected/dangerous.html
===================================================================
--- trunk/docutils/test/functional/expected/dangerous.html 2026-06-23 14:59:13 UTC (rev 10369)
+++ trunk/docutils/test/functional/expected/dangerous.html 2026-06-23 14:59:27 UTC (rev 10370)
@@ -62,6 +62,7 @@
</div>
<div class="figure">
<img alt="picture.png" src="picture.png" />
+<p class="caption">This image is read by PIL to determine its width.</p>
</div>
</div>
</body>
Modified: trunk/docutils/test/functional/expected/rst_html5_tuftig.html
===================================================================
--- trunk/docutils/test/functional/expected/rst_html5_tuftig.html 2026-06-23 14:59:13 UTC (rev 10369)
+++ trunk/docutils/test/functional/expected/rst_html5_tuftig.html 2026-06-23 14:59:27 UTC (rev 10370)
@@ -72,10 +72,8 @@
</div>
</figcaption>
</figure>
-<p>To place an image in the margin, use a marginal figure without caption.</p>
-<figure class="marginal">
-<img alt="../../../docs/user/rst/images/biohazard.png" src="../../../docs/user/rst/images/biohazard.png" style="width: 2em;" />
-</figure>
+<p>An image with option <span class="docutils literal">:class: marginal</span> moves to the margin as well.</p>
+<img alt="../../../docs/user/rst/images/biohazard.png" class="marginal" src="../../../docs/user/rst/images/biohazard.png" style="width: 2em;" />
<p>Marginal objects are placed to the right of the preceding main text
block.</p>
<aside class="admonition marginal note">
Modified: trunk/docutils/test/functional/input/dangerous.rst
===================================================================
--- trunk/docutils/test/functional/input/dangerous.rst 2026-06-23 14:59:13 UTC (rev 10369)
+++ trunk/docutils/test/functional/input/dangerous.rst 2026-06-23 14:59:27 UTC (rev 10370)
@@ -14,3 +14,5 @@
.. csv-table:: :url: file:///etc/passwd
.. figure:: picture.png
:figwidth: image
+
+ This image is read by PIL to determine its width.
Modified: trunk/docutils/test/functional/input/rst_html5_tuftig.rst
===================================================================
--- trunk/docutils/test/functional/input/rst_html5_tuftig.rst 2026-06-23 14:59:13 UTC (rev 10369)
+++ trunk/docutils/test/functional/input/rst_html5_tuftig.rst 2026-06-23 14:59:27 UTC (rev 10370)
@@ -58,10 +58,10 @@
This is the legend.
-To place an image in the margin, use a marginal figure without caption.
+An image with option ``:class: marginal`` moves to the margin as well.
-.. figure:: ../../../docs/user/rst/images/biohazard.png
- :figclass: marginal
+.. image:: ../../../docs/user/rst/images/biohazard.png
+ :class: marginal
:width: 2em
Marginal objects are placed to the right of the preceding main text
Modified: trunk/docutils/test/test_parsers/test_rst/test_directives/test_figures.py
===================================================================
--- trunk/docutils/test/test_parsers/test_rst/test_directives/test_figures.py 2026-06-23 14:59:13 UTC (rev 10369)
+++ trunk/docutils/test/test_parsers/test_rst/test_directives/test_figures.py 2026-06-23 14:59:27 UTC (rev 10370)
@@ -49,6 +49,9 @@
<document source="test data">
<figure>
<image uri="picture.png">
+ <system_message level="2" line="1" source="test data" type="WARNING">
+ <paragraph>
+ Figure without caption and legend. Use "image"?
"""],
["""\
.. figure:: picture.png
@@ -277,21 +280,30 @@
.. figure:: picture.png
A picture with a caption.
+
.. figure:: picture.png
A picture with a caption.
+
.. figure:: picture.png
A picture with a caption.
+
.. figure:: picture.png
.. figure:: picture.png
+
+ ..
.. figure:: picture.png
+
+ ..
.. figure:: picture.png
- A picture with a caption.
+ ..
.. figure:: picture.png
+ ..
+
.. figure:: picture.png
A picture with a caption.
@@ -316,6 +328,9 @@
A picture with a caption.
<figure>
<image uri="picture.png">
+ <system_message level="2" line="15" source="test data" type="WARNING">
+ <paragraph>
+ Figure without caption and legend. Use "image"?
<figure>
<image uri="picture.png">
<figure>
@@ -322,8 +337,6 @@
<image uri="picture.png">
<figure>
<image uri="picture.png">
- <caption>
- A picture with a caption.
<figure>
<image uri="picture.png">
<figure>
@@ -332,6 +345,9 @@
A picture with a caption.
<figure>
<image uri="picture.png">
+ <system_message level="2" line="34" source="test data" type="WARNING">
+ <paragraph>
+ Figure without caption and legend. Use "image"?
"""],
]
Modified: trunk/docutils/test/test_writers/test_html4css1.py
===================================================================
--- trunk/docutils/test/test_writers/test_html4css1.py 2026-06-23 14:59:13 UTC (rev 10369)
+++ trunk/docutils/test/test_writers/test_html4css1.py 2026-06-23 14:59:27 UTC (rev 10370)
@@ -63,6 +63,7 @@
'strict_visitor': True,
'stylesheet_path': '',
'section_self_link': True,
+ 'warning_stream': '', # suppress warnings
**settings_overrides,
}
)
@@ -361,6 +362,9 @@
<div class="figure">
<img alt="dummy.png" src="dummy.png" />
</div>
+<div class="system-message">
+<p class="system-message-title">System Message: WARNING/2 (<tt class="docutils"><string></tt>, line 1)</p>
+Figure without caption and legend. Use "image"?</div>
<p>No caption nor legend.</p>
""",
],
@@ -424,11 +428,14 @@
.. image:: /data/blue%20square.png
:scale: 100%
.. figure:: /data/blue%20square.png
+
+ Embedded image of a blue square.
""",
f"""\
<img alt="/data/blue%20square.png" src="/data/blue%20square.png" {SCALING_OUTPUT}/>
<div class="figure">
<img alt="/data/blue%20square.png" src="/data/blue%20square.png" />
+<p class="caption">Embedded image of a blue square.</p>
</div>
"""
],
Modified: trunk/docutils/test/test_writers/test_html5_polyglot.py
===================================================================
--- trunk/docutils/test/test_writers/test_html5_polyglot.py 2026-06-23 14:59:13 UTC (rev 10369)
+++ trunk/docutils/test/test_writers/test_html5_polyglot.py 2026-06-23 14:59:27 UTC (rev 10370)
@@ -85,6 +85,7 @@
'strict_visitor': True,
'stylesheet_path': '',
'section_self_link': True,
+ 'warning_stream': '', # suppress warnings
**settings_overrides,
}
)
@@ -388,6 +389,10 @@
<figure>
<img alt="dummy.png" src="dummy.png" />
</figure>
+<aside class="system-message">
+<p class="system-message-title">System Message: WARNING/2 (<span class="docutils literal"><string></span>, line 1)</p>
+<p>Figure without caption and legend. Use "image"?</p>
+</aside>
<p>No caption nor legend.</p>
""",
],
@@ -426,8 +431,12 @@
.. image:: dummy.png
:loading: link
.. figure:: dummy.png
+
+ Figure with lazy-loading image.
.. figure:: dummy.png
:loading: embed
+
+ Image not embedded, because it is unavailable.
""",
"""\
<p>Lazy loading by default, overridden by :loading: option
@@ -436,9 +445,15 @@
<img alt="dummy.png" src="dummy.png" />
<figure>
<img alt="dummy.png" loading="lazy" src="dummy.png" />
+<figcaption>
+<p>Figure with lazy-loading image.</p>
+</figcaption>
</figure>
<figure>
<img alt="dummy.png" src="dummy.png" />
+<figcaption>
+<p>Image not embedded, because it is unavailable.</p>
+</figcaption>
</figure>
""",
],
@@ -453,6 +468,8 @@
.. image:: /data/blue%20square.png
:scale: 100%
.. figure:: /data/blue%20square.png
+
+ Figure with embedded blue square image.
""",
f'<img alt="/data/blue%20square.png" {HEIGHT_ATTR}src="data:image/png;base64,'
'iVBORw0KGgoAAAANSUhEUgAAACAAAAAgCAIAAAD8GO2jAAAALElEQVR4nO3NMQ'
@@ -464,6 +481,9 @@
'iVBORw0KGgoAAAANSUhEUgAAACAAAAAgCAIAAAD8GO2jAAAALElEQVR4nO3NMQ'
'EAMAjAsDFjvIhHFCbgSwU0kdXvsn96BwAAAAAAAAAAAIsNnEwBk52VRuMAAAAA'
'SUVORK5CYII=" />\n'
+'<figcaption>\n'
+'<p>Figure with embedded blue square image.</p>\n'
+'</figcaption>\n'
'</figure>\n',
],
])
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
|
From: <mi...@us...> - 2026-06-23 14:59:15
|
Revision: 10369
http://sourceforge.net/p/docutils/code/10369
Author: milde
Date: 2026-06-23 14:59:13 +0000 (Tue, 23 Jun 2026)
Log Message:
-----------
Ignore the "match_titles" argument of `RSTState.nested_list_parse()`.
The rST parser function `parsers.rst.states.RSTState.nested_list_parse()`
is used to parse the content of lists and list-like constructs where
section titles are generally not allowed.
Modified Paths:
--------------
trunk/docutils/HISTORY.rst
trunk/docutils/RELEASE-NOTES.rst
trunk/docutils/docutils/parsers/rst/states.py
Modified: trunk/docutils/HISTORY.rst
===================================================================
--- trunk/docutils/HISTORY.rst 2026-06-23 14:59:05 UTC (rev 10368)
+++ trunk/docutils/HISTORY.rst 2026-06-23 14:59:13 UTC (rev 10369)
@@ -78,8 +78,9 @@
- Do not add "name" attribute to `<reference>` elements
nor set the internal attribute `indirect_reference_name`.
- - Report INFO message, if a directive that does not take
+ - Generate INFO message, if a directive that does not take
arguments has content above and below directive options.
+ - Ignore the "match_titles" argument of `RSTState.nested_list_parse()`.
* docutils/readers/standalone.py
Modified: trunk/docutils/RELEASE-NOTES.rst
===================================================================
--- trunk/docutils/RELEASE-NOTES.rst 2026-06-23 14:59:05 UTC (rev 10368)
+++ trunk/docutils/RELEASE-NOTES.rst 2026-06-23 14:59:13 UTC (rev 10369)
@@ -184,9 +184,9 @@
* Remove `parsers.rst.states.Struct` (obsoleted by `types.SimpleNamespace`)
in Docutils 2.0.
-* Ignore the "match_titles" argument of
- `parsers.rst.states.RSTState.nested_list_parse()` in Docutils 1.0;
- remove it in Docutils 2.0.
+* Remove the "match_titles" argument of
+ `parsers.rst.states.RSTState.nested_list_parse()` (ignored since
+ Docutils 1.0.) in Docutils 2.0.
* Remove `frontend.OptionParser`, `frontend.Option`, `frontend.Values`,
`frontend.store_multiple()`, and `frontend.read_config_file()` when
Modified: trunk/docutils/docutils/parsers/rst/states.py
===================================================================
--- trunk/docutils/docutils/parsers/rst/states.py 2026-06-23 14:59:05 UTC (rev 10368)
+++ trunk/docutils/docutils/parsers/rst/states.py 2026-06-23 14:59:13 UTC (rev 10369)
@@ -383,7 +383,7 @@
blank_finish,
blank_finish_state=None,
extra_settings={},
- match_titles=False, # deprecated, will be removed
+ match_titles=None, # deprecated, will be removed
state_machine_class=None,
state_machine_kwargs=None):
"""
@@ -397,11 +397,10 @@
Return new offset and a boolean indicating whether there was a
blank final line.
"""
- if match_titles:
+ if match_titles is not None:
warnings.warn('The "match_titles" argument of '
'parsers.rst.states.RSTState.nested_list_parse() '
- 'will be ignored in Docutils 1.0 '
- 'and removed in Docutils 2.0.',
+ 'is ignored and will be removed in Docutils 2.0.',
PendingDeprecationWarning, stacklevel=2)
if state_machine_class is None:
state_machine_class = self.nested_sm
@@ -417,8 +416,7 @@
my_state_machine.states[blank_finish_state].blank_finish = blank_finish
for key, value in extra_settings.items():
setattr(my_state_machine.states[initial_state], key, value)
- my_state_machine.run(block, input_offset, memo=self.memo,
- node=node, match_titles=match_titles)
+ my_state_machine.run(block, input_offset, memo=self.memo, node=node)
blank_finish = my_state_machine.states[blank_finish_state].blank_finish
my_state_machine.unlink()
return my_state_machine.abs_line_offset(), blank_finish
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
|
From: <mi...@us...> - 2026-06-23 14:59:07
|
Revision: 10368
http://sourceforge.net/p/docutils/code/10368
Author: milde
Date: 2026-06-23 14:59:05 +0000 (Tue, 23 Jun 2026)
Log Message:
-----------
Postpone removal of `nodes.set_name_id_map()`
... as already announced in the RELEASE NOTES.
Modified Paths:
--------------
trunk/docutils/docutils/nodes.py
Modified: trunk/docutils/docutils/nodes.py
===================================================================
--- trunk/docutils/docutils/nodes.py 2026-06-22 12:04:21 UTC (rev 10367)
+++ trunk/docutils/docutils/nodes.py 2026-06-23 14:59:05 UTC (rev 10368)
@@ -2036,9 +2036,9 @@
msgnode: Element | None = None,
explicit: bool = False,
) -> None:
- """Deprecated. Will be removed in Docutils 1.0."""
+ """Deprecated. Will be removed in Docutils 2.0."""
warnings.warn('nodes.document.set_name_id_map() will be removed'
- ' in Docutils 1.0.', DeprecationWarning, stacklevel=2)
+ ' in Docutils 2.0.', DeprecationWarning, stacklevel=2)
self.note_names(node, msgnode, explicit)
for name in node['names']:
self.nameids[name] = id
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
|
From: <mi...@us...> - 2026-06-22 12:04:23
|
Revision: 10367
http://sourceforge.net/p/docutils/code/10367
Author: milde
Date: 2026-06-22 12:04:21 +0000 (Mon, 22 Jun 2026)
Log Message:
-----------
End support for the special "encoding" value "" (empty string).
Remove exception for `""` in `frontend.validate_encoding()`.
Fix error message for unknown encodings.
Modified Paths:
--------------
trunk/docutils/HISTORY.rst
trunk/docutils/RELEASE-NOTES.rst
trunk/docutils/docutils/frontend.py
Modified: trunk/docutils/HISTORY.rst
===================================================================
--- trunk/docutils/HISTORY.rst 2026-06-18 13:28:08 UTC (rev 10366)
+++ trunk/docutils/HISTORY.rst 2026-06-22 12:04:21 UTC (rev 10367)
@@ -32,6 +32,7 @@
- Accept the short option ``-o`` for ``--output`` (settings.output_path).
- Drop the second positional argument <destination>.
Solves feature-request #36.
+ - End support for the special value ``""`` in `validate_encoding()`.
* docutils/io.py
Modified: trunk/docutils/RELEASE-NOTES.rst
===================================================================
--- trunk/docutils/RELEASE-NOTES.rst 2026-06-18 13:28:08 UTC (rev 10366)
+++ trunk/docutils/RELEASE-NOTES.rst 2026-06-22 12:04:21 UTC (rev 10367)
@@ -227,7 +227,8 @@
Configuration changes:
- `Auto-detection`_ of the input encoding is no longer supported.
- The input_encoding_ value ``None`` now stands for "utf-8".
+ The input_encoding_ value ``None`` now stands for "utf-8",
+ the empty string now leads to a LookupError.
- The section_self_link_ setting now defaults to True.
- The use_latex_citations_ setting now defaults to True.
- The legacy_column_widths_ setting now defaults to False.
Modified: trunk/docutils/docutils/frontend.py
===================================================================
--- trunk/docutils/docutils/frontend.py 2026-06-18 13:28:08 UTC (rev 10366)
+++ trunk/docutils/docutils/frontend.py 2026-06-22 12:04:21 UTC (rev 10367)
@@ -138,16 +138,10 @@
# If there is only one positional argument, it is interpreted as `value`.
if value is None:
value = setting
- if value == '':
- warnings.warn('Input encoding detection will be removed and the '
- 'special encoding values None and "" become invalid '
- 'in Docutils 1.0.', FutureWarning, stacklevel=2)
- return None
try:
codecs.lookup(value)
except LookupError:
- prefix = f'setting "{setting}":' if setting else ''
- raise LookupError(f'{prefix} unknown encoding: "{value}"')
+ raise LookupError(f'unknown encoding: "{value}"')
return value
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
|
From: <mi...@us...> - 2026-06-18 13:28:11
|
Revision: 10366
http://sourceforge.net/p/docutils/code/10366
Author: milde
Date: 2026-06-18 13:28:08 +0000 (Thu, 18 Jun 2026)
Log Message:
-----------
Change "section_self_link" setting default to True.
The "section_self_link" setting tells the HTML5 writer to
extend section headings with an empty <a> element with a ``href``
to the section.
CSS rules show a link symbol when the mouse hovers over the heading.
Modified Paths:
--------------
trunk/docutils/HISTORY.rst
trunk/docutils/RELEASE-NOTES.rst
trunk/docutils/docs/user/config.rst
trunk/docutils/docutils/writers/html5_polyglot/__init__.py
trunk/docutils/docutils/writers/html5_polyglot/plain.css
trunk/docutils/docutils/writers/html5_polyglot/tuftig.css
trunk/docutils/test/data/help/docutils.rst
trunk/docutils/test/functional/expected/rst_html5_tuftig.html
trunk/docutils/test/functional/expected/standalone_rst_html5.html
trunk/docutils/test/functional/tests/length_units_html5.py
trunk/docutils/test/test_writers/test_html5_template.py
Modified: trunk/docutils/HISTORY.rst
===================================================================
--- trunk/docutils/HISTORY.rst 2026-06-18 13:27:53 UTC (rev 10365)
+++ trunk/docutils/HISTORY.rst 2026-06-18 13:28:08 UTC (rev 10366)
@@ -111,6 +111,9 @@
- Change the default value of the initial_header_level_ setting to "auto"
(<h2> if there is a document title, else <h1>).
+ - Change the default value of the "section_self_link" setting to True.
+ - Add CSS rules for back-link and self-link symbols from
+ "responsive.css" also in "plain.css" and "tuftig.css".
- Use normal font size and colour in CSS for informal titles of type "rubric".
- Use more specific CSS selectors for styling <aside> elements to avoid
problems with other elements using "topic" as class value, e.g. a docinfo
Modified: trunk/docutils/RELEASE-NOTES.rst
===================================================================
--- trunk/docutils/RELEASE-NOTES.rst 2026-06-18 13:27:53 UTC (rev 10365)
+++ trunk/docutils/RELEASE-NOTES.rst 2026-06-18 13:28:08 UTC (rev 10366)
@@ -104,9 +104,6 @@
* "html5" writer:
- - The default of the self-link_ configuration setting will change to
- "True" in Docutils 1.0.
-
- Prefer explicit reference names as base for an HTML element's ID
in Docutils 1.0. No change for internal cross-references.
Cf. `Sphinx issue #1961`__
@@ -231,6 +228,7 @@
Configuration changes:
- `Auto-detection`_ of the input encoding is no longer supported.
The input_encoding_ value ``None`` now stands for "utf-8".
+ - The section_self_link_ setting now defaults to True.
- The use_latex_citations_ setting now defaults to True.
- The legacy_column_widths_ setting now defaults to False.
- The initial_header_level_ setting default for the HTML5 writer
Modified: trunk/docutils/docs/user/config.rst
===================================================================
--- trunk/docutils/docs/user/config.rst 2026-06-18 13:27:53 UTC (rev 10365)
+++ trunk/docutils/docs/user/config.rst 2026-06-18 13:28:08 UTC (rev 10366)
@@ -1532,7 +1532,7 @@
the section. See ``responsive.css`` for an example how this can be
styled to show a symbol allowing users to copy the section's URL.
-:Default: False.
+:Default: True (since Docutils 1.0).
:Options: ``--section-self-link``, ``--no-section-self-link``.
New in Docutils 0.18.
Modified: trunk/docutils/docutils/writers/html5_polyglot/__init__.py
===================================================================
--- trunk/docutils/docutils/writers/html5_polyglot/__init__.py 2026-06-18 13:27:53 UTC (rev 10365)
+++ trunk/docutils/docutils/writers/html5_polyglot/__init__.py 2026-06-18 13:28:08 UTC (rev 10366)
@@ -97,10 +97,10 @@
{'metavar': '<strategy>', 'choices': ('embed', 'link', 'lazy'),
# 'default': 'link' # default set in _html_base.py
}),
- ('Append a self-link to section headings.',
+ ('Append a self-link to section headings. (default)',
['--section-self-link'],
- {'default': False, 'action': 'store_true'}),
- ('Do not append a self-link to section headings. (default)',
+ {'default': True, 'action': 'store_true'}),
+ ('Do not append a self-link to section headings.',
['--no-section-self-link'],
{'dest': 'section_self_link', 'action': 'store_false'}),
)
Modified: trunk/docutils/docutils/writers/html5_polyglot/plain.css
===================================================================
--- trunk/docutils/docutils/writers/html5_polyglot/plain.css 2026-06-18 13:27:53 UTC (rev 10365)
+++ trunk/docutils/docutils/writers/html5_polyglot/plain.css 2026-06-18 13:28:08 UTC (rev 10366)
@@ -295,6 +295,17 @@
/* Hyperlink References */
a { text-decoration: none; }
+*:hover > a.toc-backref:after,
+.topic-title:hover > a:after {
+ content: " \2191"; /* ↑ UPWARDS ARROW */
+ color: grey;
+}
+*:hover > a.self-link:after {
+ content: "\1F517"; /* LINK SYMBOL */
+ color: grey;
+ font-size: smaller;
+ margin-left: 0.2em;
+}
/* External Targets */
/* span.target.external */
Modified: trunk/docutils/docutils/writers/html5_polyglot/tuftig.css
===================================================================
--- trunk/docutils/docutils/writers/html5_polyglot/tuftig.css 2026-06-18 13:27:53 UTC (rev 10365)
+++ trunk/docutils/docutils/writers/html5_polyglot/tuftig.css 2026-06-18 13:28:08 UTC (rev 10366)
@@ -334,6 +334,17 @@
a:link:hover {
text-decoration: underline;
}
+*:hover > a.toc-backref:after,
+.topic-title:hover > a:after {
+ content: " \2191"; /* ↑ UPWARDS ARROW */
+ color: grey;
+}
+*:hover > a.self-link:after {
+content: "\26AD"; /* MARRIAGE SYMBOL (LINK SYMBOL doesn't show up) */
+ color: grey;
+ margin-left: 0.2em;
+ text-decoration: none;
+}
/* Block Alignment */
/* Let content flow to the side of aligned images and figures */
Modified: trunk/docutils/test/data/help/docutils.rst
===================================================================
--- trunk/docutils/test/data/help/docutils.rst 2026-06-18 13:27:53 UTC (rev 10365)
+++ trunk/docutils/test/data/help/docutils.rst 2026-06-18 13:28:08 UTC (rev 10366)
@@ -201,9 +201,8 @@
--image-loading=<strategy>
Suggest at which point images should be loaded:
"embed", "link" (default), or "lazy".
---section-self-link Append a self-link to section headings.
+--section-self-link Append a self-link to section headings. (default)
--no-section-self-link Do not append a self-link to section headings.
- (default)
Docutils Application Options
----------------------------
Modified: trunk/docutils/test/functional/expected/rst_html5_tuftig.html
===================================================================
--- trunk/docutils/test/functional/expected/rst_html5_tuftig.html 2026-06-18 13:27:53 UTC (rev 10365)
+++ trunk/docutils/test/functional/expected/rst_html5_tuftig.html 2026-06-18 13:28:08 UTC (rev 10366)
@@ -29,7 +29,7 @@
</div>
</div>
<section id="fullwidth-and-margin-objects">
-<h2>Fullwidth and Margin Objects</h2>
+<h2>Fullwidth and Margin Objects<a class="self-link" title="link to this section" href="#fullwidth-and-margin-objects"></a></h2>
<p class="fullwidth">Block elements (paragraphs, admonitions, topics, figures, tables, …)
with the “fullwidth” class argument use full text width.</p>
<table class="booktabs numbered captionbelow fullwidth">
Modified: trunk/docutils/test/functional/expected/standalone_rst_html5.html
===================================================================
--- trunk/docutils/test/functional/expected/standalone_rst_html5.html 2026-06-18 13:27:53 UTC (rev 10365)
+++ trunk/docutils/test/functional/expected/standalone_rst_html5.html 2026-06-18 13:28:08 UTC (rev 10366)
@@ -162,9 +162,9 @@
</ul>
</nav>
<section id="structural-elements">
-<h2><a class="toc-backref" href="#toc-entry-1" role="doc-backlink"><span class="sectnum">1 </span>Structural Elements</a></h2>
+<h2><a class="toc-backref" href="#toc-entry-1" role="doc-backlink"><span class="sectnum">1 </span>Structural Elements</a><a class="self-link" title="link to this section" href="#structural-elements"></a></h2>
<section id="section-title">
-<h3><a class="toc-backref" href="#toc-entry-2" role="doc-backlink"><span class="sectnum">1.1 </span>Section Title</a></h3>
+<h3><a class="toc-backref" href="#toc-entry-2" role="doc-backlink"><span class="sectnum">1.1 </span>Section Title</a><a class="self-link" title="link to this section" href="#section-title"></a></h3>
<p class="section-subtitle" id="section-subtitle">Section Subtitle</p>
<p>Lone subsections are converted to a section subtitle by a transform
activated with the <span class="docutils literal"><span class="pre">--section-subtitles</span></span> command line option or the
@@ -171,10 +171,10 @@
<span class="docutils literal"><span class="pre">sectsubtitle-xform</span></span> configuration value.</p>
</section>
<section id="empty-section">
-<h3><a class="toc-backref" href="#toc-entry-3" role="doc-backlink"><span class="sectnum">1.2 </span>Empty Section</a></h3>
+<h3><a class="toc-backref" href="#toc-entry-3" role="doc-backlink"><span class="sectnum">1.2 </span>Empty Section</a><a class="self-link" title="link to this section" href="#empty-section"></a></h3>
</section>
<section id="transitions">
-<h3><a class="toc-backref" href="#toc-entry-4" role="doc-backlink"><span class="sectnum">1.3 </span>Transitions</a></h3>
+<h3><a class="toc-backref" href="#toc-entry-4" role="doc-backlink"><span class="sectnum">1.3 </span>Transitions</a><a class="self-link" title="link to this section" href="#transitions"></a></h3>
<p>Here's a transition:</p>
<hr class="docutils" />
<p>It divides the section. Transitions may also occur between sections:</p>
@@ -182,12 +182,12 @@
</section>
<hr class="docutils" />
<section id="body-elements">
-<h2><a class="toc-backref" href="#toc-entry-5" role="doc-backlink"><span class="sectnum">2 </span>Body Elements</a></h2>
+<h2><a class="toc-backref" href="#toc-entry-5" role="doc-backlink"><span class="sectnum">2 </span>Body Elements</a><a class="self-link" title="link to this section" href="#body-elements"></a></h2>
<section id="paragraphs">
-<h3><a class="toc-backref" href="#toc-entry-6" role="doc-backlink"><span class="sectnum">2.1 </span>Paragraphs</a></h3>
+<h3><a class="toc-backref" href="#toc-entry-6" role="doc-backlink"><span class="sectnum">2.1 </span>Paragraphs</a><a class="self-link" title="link to this section" href="#paragraphs"></a></h3>
<p>A paragraph.</p>
<section id="inline-markup">
-<h4><a class="toc-backref" href="#toc-entry-7" role="doc-backlink"><span class="sectnum">2.1.1 </span>Inline Markup</a></h4>
+<h4><a class="toc-backref" href="#toc-entry-7" role="doc-backlink"><span class="sectnum">2.1.1 </span>Inline Markup</a><a class="self-link" title="link to this section" href="#inline-markup"></a></h4>
<p>Paragraphs contain text and may contain inline markup: <em>emphasis</em>,
<strong>strong emphasis</strong>, <span class="docutils literal">inline literals</span>, standalone hyperlinks
(<a class="reference external" href="http://www.python.org">http://www.python.org</a>), external hyperlinks (<a class="reference external" href="http://www.python.org/">Python</a> <a class="brackets" href="#footnote-7" id="footnote-reference-18" role="doc-noteref"><span class="fn-bracket">[</span>7<span class="fn-bracket">]</span></a>), internal
@@ -216,7 +216,7 @@
</section>
</section>
<section id="bullet-lists">
-<h3><a class="toc-backref" href="#toc-entry-8" role="doc-backlink"><span class="sectnum">2.2 </span>Bullet Lists</a></h3>
+<h3><a class="toc-backref" href="#toc-entry-8" role="doc-backlink"><span class="sectnum">2.2 </span>Bullet Lists</a><a class="self-link" title="link to this section" href="#bullet-lists"></a></h3>
<ul>
<li><p>A bullet list</p>
<ul class="simple">
@@ -243,7 +243,7 @@
</ul>
</section>
<section id="enumerated-lists">
-<h3><a class="toc-backref" href="#toc-entry-9" role="doc-backlink"><span class="sectnum">2.3 </span>Enumerated Lists</a></h3>
+<h3><a class="toc-backref" href="#toc-entry-9" role="doc-backlink"><span class="sectnum">2.3 </span>Enumerated Lists</a><a class="self-link" title="link to this section" href="#enumerated-lists"></a></h3>
<ol class="arabic">
<li><p>Arabic numerals.</p>
<ol class="loweralpha simple">
@@ -279,7 +279,7 @@
</ol>
</section>
<section id="definition-lists">
-<h3><a class="toc-backref" href="#toc-entry-10" role="doc-backlink"><span class="sectnum">2.4 </span>Definition Lists</a></h3>
+<h3><a class="toc-backref" href="#toc-entry-10" role="doc-backlink"><span class="sectnum">2.4 </span>Definition Lists</a><a class="self-link" title="link to this section" href="#definition-lists"></a></h3>
<dl>
<dt>Term</dt>
<dd><p>Definition</p>
@@ -297,7 +297,7 @@
</dl>
</section>
<section id="field-lists">
-<h3><a class="toc-backref" href="#toc-entry-11" role="doc-backlink"><span class="sectnum">2.5 </span>Field Lists</a></h3>
+<h3><a class="toc-backref" href="#toc-entry-11" role="doc-backlink"><span class="sectnum">2.5 </span>Field Lists</a><a class="self-link" title="link to this section" href="#field-lists"></a></h3>
<dl class="field-list">
<dt>what<span class="colon">:</span></dt>
<dd><p>Field lists map field names to field bodies, like database
@@ -317,7 +317,7 @@
</dl>
</section>
<section id="option-lists">
-<h3><a class="toc-backref" href="#toc-entry-12" role="doc-backlink"><span class="sectnum">2.6 </span>Option Lists</a></h3>
+<h3><a class="toc-backref" href="#toc-entry-12" role="doc-backlink"><span class="sectnum">2.6 </span>Option Lists</a><a class="self-link" title="link to this section" href="#option-lists"></a></h3>
<p>For listing command-line options:</p>
<dl class="option-list">
<dt><kbd><span class="option">-a</span></kbd></dt>
@@ -363,7 +363,7 @@
description.</p>
</section>
<section id="literal-blocks">
-<h3><a class="toc-backref" href="#toc-entry-13" role="doc-backlink"><span class="sectnum">2.7 </span>Literal Blocks</a></h3>
+<h3><a class="toc-backref" href="#toc-entry-13" role="doc-backlink"><span class="sectnum">2.7 </span>Literal Blocks</a><a class="self-link" title="link to this section" href="#literal-blocks"></a></h3>
<p>Literal blocks are indicated with a double-colon ("::") at the end of
the preceding paragraph (over there <span class="docutils literal"><span class="pre">--></span></span>). They can be indented:</p>
<pre class="literal-block">if literal_block:
@@ -376,7 +376,7 @@
> Why didn't I think of that?</pre>
</section>
<section id="line-blocks">
-<h3><a class="toc-backref" href="#toc-entry-14" role="doc-backlink"><span class="sectnum">2.8 </span>Line Blocks</a></h3>
+<h3><a class="toc-backref" href="#toc-entry-14" role="doc-backlink"><span class="sectnum">2.8 </span>Line Blocks</a><a class="self-link" title="link to this section" href="#line-blocks"></a></h3>
<p>This section tests line blocks. Line blocks are body elements which
consist of lines and other line blocks. Nested line blocks cause
indentation.</p>
@@ -450,7 +450,7 @@
</div>
</section>
<section id="block-quotes">
-<h3><a class="toc-backref" href="#toc-entry-15" role="doc-backlink"><span class="sectnum">2.9 </span>Block Quotes</a></h3>
+<h3><a class="toc-backref" href="#toc-entry-15" role="doc-backlink"><span class="sectnum">2.9 </span>Block Quotes</a><a class="self-link" title="link to this section" href="#block-quotes"></a></h3>
<p>Block quotes consist of indented body elements:</p>
<blockquote>
<p>My theory by A. Elk. Brackets Miss, brackets. This theory goes
@@ -469,7 +469,7 @@
</blockquote>
</section>
<section id="doctest-blocks">
-<h3><a class="toc-backref" href="#toc-entry-16" role="doc-backlink"><span class="sectnum">2.10 </span>Doctest Blocks</a></h3>
+<h3><a class="toc-backref" href="#toc-entry-16" role="doc-backlink"><span class="sectnum">2.10 </span>Doctest Blocks</a><a class="self-link" title="link to this section" href="#doctest-blocks"></a></h3>
<pre class="code python doctest">>>> print 'Python-specific usage examples; begun with ">>>"'
Python-specific usage examples; begun with ">>>"
>>> print '(cut and pasted from interactive Python sessions)'
@@ -477,7 +477,7 @@
</pre>
</section>
<section id="footnotes">
-<h3><a class="toc-backref" href="#toc-entry-17" role="doc-backlink"><span class="sectnum">2.11 </span>Footnotes</a></h3>
+<h3><a class="toc-backref" href="#toc-entry-17" role="doc-backlink"><span class="sectnum">2.11 </span>Footnotes</a><a class="self-link" title="link to this section" href="#footnotes"></a></h3>
<aside class="footnote-list brackets">
<aside class="footnote brackets" id="footnote-1" role="doc-footnote">
<span class="label"><span class="fn-bracket">[</span>1<span class="fn-bracket">]</span></span>
@@ -518,7 +518,7 @@
</aside>
</section>
<section id="citations">
-<h3><a class="toc-backref" href="#toc-entry-18" role="doc-backlink"><span class="sectnum">2.12 </span>Citations</a></h3>
+<h3><a class="toc-backref" href="#toc-entry-18" role="doc-backlink"><span class="sectnum">2.12 </span>Citations</a><a class="self-link" title="link to this section" href="#citations"></a></h3>
<div role="list" class="citation-list">
<div class="citation" id="cit2002" role="doc-biblioentry">
<span class="label"><span class="fn-bracket">[</span>CIT2002<span class="fn-bracket">]</span></span>
@@ -531,7 +531,7 @@
citation.</p>
</section>
<section id="targets">
-<span id="another-target"></span><h3><a class="toc-backref" href="#toc-entry-19" role="doc-backlink"><span class="sectnum">2.13 </span>Targets</a></h3>
+<span id="another-target"></span><h3><a class="toc-backref" href="#toc-entry-19" role="doc-backlink"><span class="sectnum">2.13 </span>Targets</a><a class="self-link" title="link to this section" href="#another-target"></a></h3>
<p id="example">This paragraph is pointed to by the explicit "example" target. A
reference can be found under <a class="reference internal" href="#inline-markup">Inline Markup</a>, above. <a class="reference internal" href="#inline-hyperlink-targets">Inline
hyperlink targets</a> are also possible.</p>
@@ -544,13 +544,13 @@
<p>Here's a <a href="#system-message-4"><span class="problematic" id="problematic-2">`hyperlink reference without a target`_</span></a>, which generates an
error.</p>
<section id="duplicate-target-names-1">
-<h4><a class="toc-backref" href="#toc-entry-20" role="doc-backlink"><span class="sectnum">2.13.1 </span>Duplicate Target Names</a></h4>
+<h4><a class="toc-backref" href="#toc-entry-20" role="doc-backlink"><span class="sectnum">2.13.1 </span>Duplicate Target Names</a><a class="self-link" title="link to this section" href="#duplicate-target-names-1"></a></h4>
<p>Duplicate names in section headers or other implicit targets will
generate "info" (level-1) system messages. Duplicate names in
explicit targets will generate "warning" (level-2) system messages.</p>
</section>
<section id="duplicate-target-names-2">
-<h4><a class="toc-backref" href="#toc-entry-21" role="doc-backlink"><span class="sectnum">2.13.2 </span>Duplicate Target Names</a></h4>
+<h4><a class="toc-backref" href="#toc-entry-21" role="doc-backlink"><span class="sectnum">2.13.2 </span>Duplicate Target Names</a><a class="self-link" title="link to this section" href="#duplicate-target-names-2"></a></h4>
<p>Since there are two "Duplicate Target Names" section headers, we
cannot uniquely refer to either of them by name. If we try to (like
this: <a href="#system-message-5"><span class="problematic" id="problematic-3">`Duplicate Target Names`_</span></a>), an error is generated.</p>
@@ -557,7 +557,7 @@
</section>
</section>
<section id="directives">
-<h3><a class="toc-backref" href="#toc-entry-22" role="doc-backlink"><span class="sectnum">2.14 </span>Directives</a></h3>
+<h3><a class="toc-backref" href="#toc-entry-22" role="doc-backlink"><span class="sectnum">2.14 </span>Directives</a><a class="self-link" title="link to this section" href="#directives"></a></h3>
<nav class="contents local" id="contents">
<ul class="auto-toc simple">
<li><p><a class="reference internal" href="#document-parts" id="toc-entry-55"><span class="sectnum">2.14.1 </span>Document Parts</a></p></li>
@@ -576,13 +576,13 @@
<p>These are just a sample of the many reStructuredText Directives. For
others, please see <a class="reference external" href="https://docutils.sourceforge.io/docs/ref/rst/directives.html">reStructuredText Directives</a> <a class="brackets" href="#footnote-15" id="footnote-reference-29" role="doc-noteref"><span class="fn-bracket">[</span>15<span class="fn-bracket">]</span></a>.</p>
<section id="document-parts">
-<h4><a class="toc-backref" href="#toc-entry-55" role="doc-backlink"><span class="sectnum">2.14.1 </span>Document Parts</a></h4>
+<h4><a class="toc-backref" href="#toc-entry-55" role="doc-backlink"><span class="sectnum">2.14.1 </span>Document Parts</a><a class="self-link" title="link to this section" href="#document-parts"></a></h4>
<p>An example of the "contents" directive can be seen above this section
(a local, untitled table of <a class="reference internal" href="#contents">contents</a>) and at the beginning of the
document (a document-wide <a class="reference internal" href="#table-of-contents">table of contents</a>).</p>
</section>
<section id="images-and-figures">
-<h4><a class="toc-backref" href="#toc-entry-56" role="doc-backlink"><span class="sectnum">2.14.2 </span>Images and Figures</a></h4>
+<h4><a class="toc-backref" href="#toc-entry-56" role="doc-backlink"><span class="sectnum">2.14.2 </span>Images and Figures</a><a class="self-link" title="link to this section" href="#images-and-figures"></a></h4>
<p>An image directive (also clickable -- a hyperlink reference):</p>
<a class="reference internal image-reference" href="#directives">
<img alt="../../../docs/user/rst/images/title.png" class="class1 class2" src="../../../docs/user/rst/images/title.png" style="width: 70%;" />
@@ -680,7 +680,7 @@
upon the style sheet and the browser or rendering software used.</p>
</section>
<section id="tables">
-<h4><a class="toc-backref" href="#toc-entry-57" role="doc-backlink"><span class="sectnum">2.14.3 </span>Tables</a></h4>
+<h4><a class="toc-backref" href="#toc-entry-57" role="doc-backlink"><span class="sectnum">2.14.3 </span>Tables</a><a class="self-link" title="link to this section" href="#tables"></a></h4>
<p>Tables may be given titles and additional arguments with the <em>table</em>
directive:</p>
<table class="align-left">
@@ -762,7 +762,7 @@
</table>
</section>
<section id="admonitions">
-<h4><a class="toc-backref" href="#toc-entry-58" role="doc-backlink"><span class="sectnum">2.14.4 </span>Admonitions</a></h4>
+<h4><a class="toc-backref" href="#toc-entry-58" role="doc-backlink"><span class="sectnum">2.14.4 </span>Admonitions</a><a class="self-link" title="link to this section" href="#admonitions"></a></h4>
<aside class="admonition attention">
<p class="admonition-title">Attention!</p>
<p>Directives at large.</p>
@@ -811,7 +811,7 @@
</aside>
</section>
<section id="topics-sidebars-and-rubrics">
-<h4><a class="toc-backref" href="#toc-entry-59" role="doc-backlink"><span class="sectnum">2.14.5 </span>Topics, Sidebars, and Rubrics</a></h4>
+<h4><a class="toc-backref" href="#toc-entry-59" role="doc-backlink"><span class="sectnum">2.14.5 </span>Topics, Sidebars, and Rubrics</a><a class="self-link" title="link to this section" href="#topics-sidebars-and-rubrics"></a></h4>
<p><em>Sidebars</em> are like miniature, parallel documents.</p>
<aside class="sidebar">
<p class="sidebar-title">Optional Sidebar Title</p>
@@ -835,7 +835,7 @@
allowed (e.g. inside a directive).</p>
</section>
<section id="target-footnotes">
-<h4><a class="toc-backref" href="#toc-entry-60" role="doc-backlink"><span class="sectnum">2.14.6 </span>Target Footnotes</a></h4>
+<h4><a class="toc-backref" href="#toc-entry-60" role="doc-backlink"><span class="sectnum">2.14.6 </span>Target Footnotes</a><a class="self-link" title="link to this section" href="#target-footnotes"></a></h4>
<aside class="footnote-list brackets">
<aside class="footnote brackets" id="footnote-7" role="doc-footnote">
<span class="label"><span class="fn-bracket">[</span>7<span class="fn-bracket">]</span></span>
@@ -897,11 +897,11 @@
</aside>
</section>
<section id="replacement-text">
-<h4><a class="toc-backref" href="#toc-entry-61" role="doc-backlink"><span class="sectnum">2.14.7 </span>Replacement Text</a></h4>
+<h4><a class="toc-backref" href="#toc-entry-61" role="doc-backlink"><span class="sectnum">2.14.7 </span>Replacement Text</a><a class="self-link" title="link to this section" href="#replacement-text"></a></h4>
<p>I recommend you try <a class="reference external" href="http://www.python.org/">Python, <em>the</em> best language around</a> <a class="brackets" href="#footnote-7" id="footnote-reference-20" role="doc-noteref"><span class="fn-bracket">[</span>7<span class="fn-bracket">]</span></a>.</p>
</section>
<section id="compound-paragraph">
-<h4><a class="toc-backref" href="#toc-entry-62" role="doc-backlink"><span class="sectnum">2.14.8 </span>Compound Paragraph</a></h4>
+<h4><a class="toc-backref" href="#toc-entry-62" role="doc-backlink"><span class="sectnum">2.14.8 </span>Compound Paragraph</a><a class="self-link" title="link to this section" href="#compound-paragraph"></a></h4>
<p>The <em>compound</em> directive is used to create a "compound paragraph", which
is a single logical paragraph containing multiple physical body
elements. For example:</p>
@@ -1007,7 +1007,7 @@
</div>
</section>
<section id="parsed-literal-blocks">
-<h4><a class="toc-backref" href="#toc-entry-63" role="doc-backlink"><span class="sectnum">2.14.9 </span>Parsed Literal Blocks</a></h4>
+<h4><a class="toc-backref" href="#toc-entry-63" role="doc-backlink"><span class="sectnum">2.14.9 </span>Parsed Literal Blocks</a><a class="self-link" title="link to this section" href="#parsed-literal-blocks"></a></h4>
<pre class="literal-block">This is a parsed literal block.
This line is indented. The next line is blank.
@@ -1026,7 +1026,7 @@
footnotes <a class="brackets" href="#footnote-1" id="footnote-reference-9" role="doc-noteref"><span class="fn-bracket">[</span>1<span class="fn-bracket">]</span></a>, <span class="target" id="hyperlink-targets">hyperlink targets</span>, and <a class="reference external" href="http://www.python.org/">references</a>.</pre>
</section>
<section id="code">
-<h4><a class="toc-backref" href="#toc-entry-64" role="doc-backlink"><span class="sectnum">2.14.10 </span>Code</a></h4>
+<h4><a class="toc-backref" href="#toc-entry-64" role="doc-backlink"><span class="sectnum">2.14.10 </span>Code</a><a class="self-link" title="link to this section" href="#code"></a></h4>
<p>Blocks of source code can be set with the <cite>code</cite> directive. If the code
language is specified, the content is parsed and tagged by the <a class="reference external" href="http://pygments.org/">Pygments</a> <a class="brackets" href="#footnote-8" id="footnote-reference-21" role="doc-noteref"><span class="fn-bracket">[</span>8<span class="fn-bracket">]</span></a>
syntax highlighter and can be formatted with a style sheet. (Code parsing
@@ -1058,19 +1058,19 @@
</code><small class="ln">2 </small><code data-lineno="2 ">.. footer:: Document footer</code></pre>
</section>
<section id="meta">
-<h4><a class="toc-backref" href="#toc-entry-65" role="doc-backlink"><span class="sectnum">2.14.11 </span>Meta</a></h4>
+<h4><a class="toc-backref" href="#toc-entry-65" role="doc-backlink"><span class="sectnum">2.14.11 </span>Meta</a><a class="self-link" title="link to this section" href="#meta"></a></h4>
<p>The <a class="reference external" href="https://docutils.sourceforge.io/docs/ref/rst/directives.html#metadata">“meta” directive</a> <a class="brackets" href="#footnote-16" id="footnote-reference-30" role="doc-noteref"><span class="fn-bracket">[</span>16<span class="fn-bracket">]</span></a> is used to specify metadata to be stored in,
e.g., HTML META tags or ODT file properties.</p>
</section>
</section>
<section id="substitution-definitions">
-<h3><a class="toc-backref" href="#toc-entry-34" role="doc-backlink"><span class="sectnum">2.15 </span>Substitution Definitions</a></h3>
+<h3><a class="toc-backref" href="#toc-entry-34" role="doc-backlink"><span class="sectnum">2.15 </span>Substitution Definitions</a><a class="self-link" title="link to this section" href="#substitution-definitions"></a></h3>
<p>An inline image (<img alt="EXAMPLE" src="../../../docs/user/rst/images/biohazard.png" />) example:</p>
<p>A Unicode example:</p>
<p>(Substitution definitions are only visible in the rST source.)</p>
</section>
<section id="comments">
-<h3><a class="toc-backref" href="#toc-entry-35" role="doc-backlink"><span class="sectnum">2.16 </span>Comments</a></h3>
+<h3><a class="toc-backref" href="#toc-entry-35" role="doc-backlink"><span class="sectnum">2.16 </span>Comments</a><a class="self-link" title="link to this section" href="#comments"></a></h3>
<p>Here's one:</p>
<!-- Comments begin with two dots and a space. Anything may
follow, except for the syntax of footnotes, hyperlink
@@ -1082,13 +1082,13 @@
<p>(View the HTML/LaTeX/... source to see the comment.)</p>
</section>
<section id="raw-text">
-<h3><a class="toc-backref" href="#toc-entry-36" role="doc-backlink"><span class="sectnum">2.17 </span>Raw text</a></h3>
+<h3><a class="toc-backref" href="#toc-entry-36" role="doc-backlink"><span class="sectnum">2.17 </span>Raw text</a><a class="self-link" title="link to this section" href="#raw-text"></a></h3>
<p>This does not necessarily look nice, because there may be missing white space.</p>
<p>It's just there to freeze the behavior.</p>
A test.Second test.<div class="myclass">Another test with myclass set.</div><p>This is the <span class="myrawroleclass">fourth test</span> with myrawroleclass set.</p>
Fifth test in HTML.<br />Line two.</section>
<section id="container">
-<h3><a class="toc-backref" href="#toc-entry-37" role="doc-backlink"><span class="sectnum">2.18 </span>Container</a></h3>
+<h3><a class="toc-backref" href="#toc-entry-37" role="doc-backlink"><span class="sectnum">2.18 </span>Container</a><a class="self-link" title="link to this section" href="#container"></a></h3>
<div class="custom docutils container">
<p>paragraph 1</p>
<p>paragraph 2</p>
@@ -1095,7 +1095,7 @@
</div>
</section>
<section id="colspanning-tables">
-<h3><a class="toc-backref" href="#toc-entry-38" role="doc-backlink"><span class="sectnum">2.19 </span>Colspanning tables</a></h3>
+<h3><a class="toc-backref" href="#toc-entry-38" role="doc-backlink"><span class="sectnum">2.19 </span>Colspanning tables</a><a class="self-link" title="link to this section" href="#colspanning-tables"></a></h3>
<p>This table has a cell spanning two columns:</p>
<table>
<thead>
@@ -1128,7 +1128,7 @@
</table>
</section>
<section id="rowspanning-tables">
-<h3><a class="toc-backref" href="#toc-entry-39" role="doc-backlink"><span class="sectnum">2.20 </span>Rowspanning tables</a></h3>
+<h3><a class="toc-backref" href="#toc-entry-39" role="doc-backlink"><span class="sectnum">2.20 </span>Rowspanning tables</a><a class="self-link" title="link to this section" href="#rowspanning-tables"></a></h3>
<p>Here's a table with cells spanning several rows:</p>
<table>
<thead>
@@ -1156,7 +1156,7 @@
</table>
</section>
<section id="complex-tables">
-<h3><a class="toc-backref" href="#toc-entry-40" role="doc-backlink"><span class="sectnum">2.21 </span>Complex tables</a></h3>
+<h3><a class="toc-backref" href="#toc-entry-40" role="doc-backlink"><span class="sectnum">2.21 </span>Complex tables</a><a class="self-link" title="link to this section" href="#complex-tables"></a></h3>
<p>Here's a complex table, which should test all features.</p>
<table>
<thead>
@@ -1199,7 +1199,7 @@
</table>
</section>
<section id="list-tables">
-<h3><a class="toc-backref" href="#toc-entry-41" role="doc-backlink"><span class="sectnum">2.22 </span>List Tables</a></h3>
+<h3><a class="toc-backref" href="#toc-entry-41" role="doc-backlink"><span class="sectnum">2.22 </span>List Tables</a><a class="self-link" title="link to this section" href="#list-tables"></a></h3>
<p>Here's a list table exercising all features:</p>
<table class="test" style="width: 95%;">
<caption>list table with integral header</caption>
@@ -1246,7 +1246,7 @@
</table>
</section>
<section id="custom-roles">
-<h3><a class="toc-backref" href="#toc-entry-42" role="doc-backlink"><span class="sectnum">2.23 </span>Custom Roles</a></h3>
+<h3><a class="toc-backref" href="#toc-entry-42" role="doc-backlink"><span class="sectnum">2.23 </span>Custom Roles</a><a class="self-link" title="link to this section" href="#custom-roles"></a></h3>
<ul>
<li><p>A role based on an existing role.</p>
<p><span class="custom docutils literal">one</span> <span class="custom docutils literal">two</span> <span class="custom docutils literal">three</span></p>
@@ -1275,7 +1275,7 @@
</section>
</section>
<section id="differences-to-the-html4css1-writer">
-<h2><a class="toc-backref" href="#toc-entry-43" role="doc-backlink"><span class="sectnum">3 </span>Differences to the <cite>html4css1</cite> Writer</a></h2>
+<h2><a class="toc-backref" href="#toc-entry-43" role="doc-backlink"><span class="sectnum">3 </span>Differences to the <cite>html4css1</cite> Writer</a><a class="self-link" title="link to this section" href="#differences-to-the-html4css1-writer"></a></h2>
<ul>
<li><p>Use only <a class="reference internal" href="#meta">meta</a> keywords recognized by HTML 5.
Add HTML5-compatible meta tags for docinfo items
@@ -1313,7 +1313,7 @@
</li>
</ul>
<section id="field-list-rendering">
-<h3><a class="toc-backref" href="#toc-entry-44" role="doc-backlink"><span class="sectnum">3.1 </span>Field List Rendering</a></h3>
+<h3><a class="toc-backref" href="#toc-entry-44" role="doc-backlink"><span class="sectnum">3.1 </span>Field List Rendering</a><a class="self-link" title="link to this section" href="#field-list-rendering"></a></h3>
<p>A <cite>field list</cite> is converted to a HTML <cite>definition list</cite> and given the
<span class="docutils literal"><span class="pre">field-list</span></span> class argument value to allow CSS styling.
With <span class="docutils literal">html_plain.css</span>, the layout is similar to <cite>html4css1</cite>:</p>
@@ -1337,11 +1337,11 @@
</dl>
</section>
<section id="styling-with-class-arguments">
-<h3><a class="toc-backref" href="#toc-entry-45" role="doc-backlink"><span class="sectnum">3.2 </span>Styling with Class Arguments</a></h3>
+<h3><a class="toc-backref" href="#toc-entry-45" role="doc-backlink"><span class="sectnum">3.2 </span>Styling with Class Arguments</a><a class="self-link" title="link to this section" href="#styling-with-class-arguments"></a></h3>
<p>The <span class="docutils literal">plain.css</span> style sheet comes with some pre-defined style variants
that can be chosen via a class argument.</p>
<section id="description-lists">
-<h4><a class="toc-backref" href="#toc-entry-46" role="doc-backlink"><span class="sectnum">3.2.1 </span>Description Lists</a></h4>
+<h4><a class="toc-backref" href="#toc-entry-46" role="doc-backlink"><span class="sectnum">3.2.1 </span>Description Lists</a><a class="self-link" title="link to this section" href="#description-lists"></a></h4>
<p>Definition lists with the "description" class argument:</p>
<dl class="description">
<dt>description lists</dt>
@@ -1380,7 +1380,7 @@
</dl>
</section>
<section id="details-disclosure-elements">
-<h4><a class="toc-backref" href="#toc-entry-47" role="doc-backlink"><span class="sectnum">3.2.2 </span>Details disclosure elements</a></h4>
+<h4><a class="toc-backref" href="#toc-entry-47" role="doc-backlink"><span class="sectnum">3.2.2 </span>Details disclosure elements</a><a class="self-link" title="link to this section" href="#details-disclosure-elements"></a></h4>
<p>Items of <a class="reference internal" href="#definition-lists">definition lists</a> with class argument "details" are converted
to <a class="reference external" href="https://www.w3.org/TR/html52/interactive-elements.html#the-details-element">details</a> <a class="brackets" href="#footnote-10" id="footnote-reference-23" role="doc-noteref"><span class="fn-bracket">[</span>10<span class="fn-bracket">]</span></a> disclosure elements with the term becoming the "summary".</p>
<div class="details" id="closed-details">
@@ -1398,7 +1398,7 @@
</div>
</section>
<section id="field-list-variants">
-<h4><a class="toc-backref" href="#toc-entry-48" role="doc-backlink"><span class="sectnum">3.2.3 </span>Field List Variants</a></h4>
+<h4><a class="toc-backref" href="#toc-entry-48" role="doc-backlink"><span class="sectnum">3.2.3 </span>Field List Variants</a><a class="self-link" title="link to this section" href="#field-list-variants"></a></h4>
<p>For field lists, the "compact/open", "narrow" and "run-in" styles are defined
in the style sheets <span class="docutils literal">plain.css</span> and <span class="docutils literal">responsive.css</span>.</p>
<dl class="simple">
@@ -1479,7 +1479,7 @@
</dl>
</section>
<section id="table-variants">
-<h4><a class="toc-backref" href="#toc-entry-49" role="doc-backlink"><span class="sectnum">3.2.4 </span>Table Variants</a></h4>
+<h4><a class="toc-backref" href="#toc-entry-49" role="doc-backlink"><span class="sectnum">3.2.4 </span>Table Variants</a><a class="self-link" title="link to this section" href="#table-variants"></a></h4>
<p>The following styles can be applied to individual tables via a class
argument or as document wide setting with the <a class="reference external" href="https://docutils.sourceforge.io/docs/user/config.html#table-style">table-style</a> <a class="brackets" href="#footnote-11" id="footnote-reference-24" role="doc-noteref"><span class="fn-bracket">[</span>11<span class="fn-bracket">]</span></a> configuration
setting (or command line argument).</p>
@@ -1554,7 +1554,7 @@
</blockquote>
</section>
<section id="numbered-figures">
-<h4><a class="toc-backref" href="#toc-entry-50" role="doc-backlink"><span class="sectnum">3.2.5 </span>Numbered Figures</a></h4>
+<h4><a class="toc-backref" href="#toc-entry-50" role="doc-backlink"><span class="sectnum">3.2.5 </span>Numbered Figures</a><a class="self-link" title="link to this section" href="#numbered-figures"></a></h4>
<p>Numbered figures can be achieved with the "numbered" <span class="docutils literal">:figclass:</span> option:</p>
<figure class="numbered">
<svg xmlns="http://www.w3.org/2000/svg" version="1.1" viewBox="0 0 240 32" style="width: 100%;">
@@ -1567,7 +1567,7 @@
</section>
</section>
<section id="text-level-semantics">
-<h3><a class="toc-backref" href="#toc-entry-51" role="doc-backlink"><span class="sectnum">3.3 </span>Text-Level Semantics</a></h3>
+<h3><a class="toc-backref" href="#toc-entry-51" role="doc-backlink"><span class="sectnum">3.3 </span>Text-Level Semantics</a><a class="self-link" title="link to this section" href="#text-level-semantics"></a></h3>
<p>This section describes the <a class="reference external" href="https://html.spec.whatwg.org/#text-level-semantics">HTML 5 tags for representation of text-level
semantics</a> <a class="brackets" href="#footnote-19" id="footnote-reference-33" role="doc-noteref"><span class="fn-bracket">[</span>19<span class="fn-bracket">]</span></a> and their reStructuredText equivalents.</p>
<dl class="description">
@@ -1779,7 +1779,7 @@
</aside>
</section>
<section id="indicating-edits">
-<h3><a class="toc-backref" href="#toc-entry-52" role="doc-backlink"><span class="sectnum">3.4 </span>Indicating Edits</a></h3>
+<h3><a class="toc-backref" href="#toc-entry-52" role="doc-backlink"><span class="sectnum">3.4 </span>Indicating Edits</a><a class="self-link" title="link to this section" href="#indicating-edits"></a></h3>
<p>The <a class="reference external" href="https://html.spec.whatwg.org/multipage/edits.html">HTML tags for representation of edits to the document</a> <a class="brackets" href="#footnote-20" id="footnote-reference-34" role="doc-noteref"><span class="fn-bracket">[</span>20<span class="fn-bracket">]</span></a> and their
reStructuredText equivalents are:</p>
<dl class="description">
@@ -1804,7 +1804,7 @@
</dl>
</section>
<section id="svg-images">
-<h3><a class="toc-backref" href="#toc-entry-53" role="doc-backlink"><span class="sectnum">3.5 </span>SVG Images</a></h3>
+<h3><a class="toc-backref" href="#toc-entry-53" role="doc-backlink"><span class="sectnum">3.5 </span>SVG Images</a><a class="self-link" title="link to this section" href="#svg-images"></a></h3>
<img alt="../../../docs/user/rst/images/biohazard.svg" class="align-left" src="../../../docs/user/rst/images/biohazard.svg" style="width: 48px; height: 48px;" />
<p>Scalable vector graphics (SVG) images are the only standards-compatible
way to include vector graphics in HTML documents. However, they are not
@@ -1901,7 +1901,7 @@
</section>
</section>
<section id="error-handling">
-<h2><a class="toc-backref" href="#toc-entry-54" role="doc-backlink"><span class="sectnum">4 </span>Error Handling</a></h2>
+<h2><a class="toc-backref" href="#toc-entry-54" role="doc-backlink"><span class="sectnum">4 </span>Error Handling</a><a class="self-link" title="link to this section" href="#error-handling"></a></h2>
<p>Any errors caught during processing will generate system messages.</p>
<p>There should be five messages in the following, auto-generated
section, "Docutils System Messages":</p>
Modified: trunk/docutils/test/functional/tests/length_units_html5.py
===================================================================
--- trunk/docutils/test/functional/tests/length_units_html5.py 2026-06-18 13:27:53 UTC (rev 10365)
+++ trunk/docutils/test/functional/tests/length_units_html5.py 2026-06-18 13:28:08 UTC (rev 10366)
@@ -15,4 +15,5 @@
settings_overrides = {
# location of stylesheets (relative to ``docutils/test/``)
'stylesheet_dirs': ('functional/input/data', ),
+ 'section_self_link': False,
}
Modified: trunk/docutils/test/test_writers/test_html5_template.py
===================================================================
--- trunk/docutils/test/test_writers/test_html5_template.py 2026-06-18 13:27:53 UTC (rev 10365)
+++ trunk/docutils/test/test_writers/test_html5_template.py 2026-06-18 13:28:08 UTC (rev 10366)
@@ -43,7 +43,8 @@
'template': template_path,
'stylesheet_path': '/test.css',
'embed_stylesheet': False,
- }).decode()
+ 'section_self_link': False,
+ }).decode()
self.assertEqual(case_expected, output)
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
|
From: <mi...@us...> - 2026-06-18 13:27:56
|
Revision: 10365
http://sourceforge.net/p/docutils/code/10365
Author: milde
Date: 2026-06-18 13:27:53 +0000 (Thu, 18 Jun 2026)
Log Message:
-----------
HTML5 writer: Change "initial_header_level" setting default to "auto".
Change the default value of the "initial_header_level" setting for the
HTML5 writer to "auto" (<h2> if there is a document title, else <h1>).
Produces a HTML document with clean "outline" for documents with
document title as well as documents without document title.
Modified Paths:
--------------
trunk/docutils/FAQ.rst
trunk/docutils/HISTORY.rst
trunk/docutils/RELEASE-NOTES.rst
trunk/docutils/docs/user/config.rst
trunk/docutils/docutils/writers/html5_polyglot/__init__.py
trunk/docutils/test/data/help/docutils.rst
trunk/docutils/test/functional/expected/standalone_rst_html5.html
trunk/docutils/test/functional/input/data/html5-features.rst
trunk/docutils/test/test_writers/test_html5_polyglot.py
Modified: trunk/docutils/FAQ.rst
===================================================================
--- trunk/docutils/FAQ.rst 2026-06-18 13:27:39 UTC (rev 10364)
+++ trunk/docutils/FAQ.rst 2026-06-18 13:27:53 UTC (rev 10365)
@@ -966,10 +966,9 @@
(``--no-doc-title`` option). This will interpret your document
differently from the standard settings, which might not be a good
idea. If you don't like the reuse of the H1 in the HTML output, you
- can tweak the `initial_header_level`_ setting
- (``--initial-header-level`` option) -- but unless you match its value
- to your specific document, you might end up with bad HTML (e.g. H3
- without H2).
+ can change the `initial_header_level`_ configuration setting
+ (``--initial-header-level`` option) to "auto"
+ (<h2> if there is a document title, else <h1>).
.. _doctitle_xform: docs/user/config.html#doctitle-xform
.. _initial_header_level: docs/user/config.html#initial-header-level
@@ -976,9 +975,8 @@
(Thanks to Mark McEahern for the question and much of the answer.)
- .. note:: For the `html5 writer`_, `initial_header_level`_ defaults to
- ``2`` because this is what the `HTML5 standard`__ expects as
- start value for headings nested in <section> elements.
+ .. note:: For the `html5 writer`_, `initial_header_level`_ defaults
+ to "auto" (since Docutils 1.0).
.. Sectioning content elements are always considered subsections of
their nearest ancestor *sectioning root* [#]_ or their nearest
@@ -991,7 +989,7 @@
I.e., a top-level <section> is a subsection of <body>.
- __ https://www.w3.org/TR/html53/sections.html#headings-and-sections
+ __ https://www.w3.org/TR/html53/sections.html#headings-and-sections
How are lists formatted in HTML?
Modified: trunk/docutils/HISTORY.rst
===================================================================
--- trunk/docutils/HISTORY.rst 2026-06-18 13:27:39 UTC (rev 10364)
+++ trunk/docutils/HISTORY.rst 2026-06-18 13:27:53 UTC (rev 10365)
@@ -109,6 +109,8 @@
* docutils/writers/html5_polyglot/*
+ - Change the default value of the initial_header_level_ setting to "auto"
+ (<h2> if there is a document title, else <h1>).
- Use normal font size and colour in CSS for informal titles of type "rubric".
- Use more specific CSS selectors for styling <aside> elements to avoid
problems with other elements using "topic" as class value, e.g. a docinfo
Modified: trunk/docutils/RELEASE-NOTES.rst
===================================================================
--- trunk/docutils/RELEASE-NOTES.rst 2026-06-18 13:27:39 UTC (rev 10364)
+++ trunk/docutils/RELEASE-NOTES.rst 2026-06-18 13:27:53 UTC (rev 10365)
@@ -119,9 +119,6 @@
__ https://html.spec.whatwg.org/#the-blockquote-element
- - Change the default value of the initial_header_level_ setting to "auto"
- (<h2> if there is a document title, else <h1>) in Docutils 1.0.
-
- Remove option ``--embed-images`` (obsoleted by "image_loading_")
in Docutils 2.0.
@@ -236,6 +233,8 @@
The input_encoding_ value ``None`` now stands for "utf-8".
- The use_latex_citations_ setting now defaults to True.
- The legacy_column_widths_ setting now defaults to False.
+ - The initial_header_level_ setting default for the HTML5 writer
+ changed to "auto".
Command line interface:
- Option ``-o`` sets the `output file path <output_path_>`__
Modified: trunk/docutils/docs/user/config.rst
===================================================================
--- trunk/docutils/docs/user/config.rst 2026-06-18 13:27:39 UTC (rev 10364)
+++ trunk/docutils/docs/user/config.rst 2026-06-18 13:27:53 UTC (rev 10365)
@@ -1203,7 +1203,7 @@
initial_header_level
~~~~~~~~~~~~~~~~~~~~
The level of the first *section* heading element
-(the `document title`_ always uses <h1>).
+(the optional `document title`_ always uses <h1>).
Supported values:
:1, ..., 6: <h1>, ..., <h6>,
@@ -1498,14 +1498,12 @@
""""""""""""""""""""""""
.. class:: run-in narrow
-:initial_header_level_: 2 (reserve <h1> for the `document title`_). [#]_
+:initial_header_level_: "auto" (changed from "2" in Docutils 1.0).
:`math_output`_: "MathML" (changed from "HTML math.css"in Docutils 0.22).
:`stylesheet_path <stylesheet_path [html writers]_>`__:
"minimal.css, plain.css".
:`xml_declaration <xml_declaration [html writers]_>`__: False.
-.. [#] The default will change to "auto" in Docutils 1.0.
-
image_loading
"""""""""""""
Indicate at which point images should be loaded.
Modified: trunk/docutils/docutils/writers/html5_polyglot/__init__.py
===================================================================
--- trunk/docutils/docutils/writers/html5_polyglot/__init__.py 2026-06-18 13:27:39 UTC (rev 10364)
+++ trunk/docutils/docutils/writers/html5_polyglot/__init__.py 2026-06-18 13:27:53 UTC (rev 10365)
@@ -71,9 +71,10 @@
'default': default_stylesheet_dirs}),
initial_header_level=(
'Specify the initial header level. Does not affect document '
- 'title & subtitle (see --no-doc-title). (default: 2 for "<h2>")',
+ 'title & subtitle (see --no-doc-title). '
+ 'Default: "auto" (<h2> if there is a document title, else <h1>).',
['--initial-header-level'],
- {'choices': '1 2 3 4 5 6 auto'.split(), 'default': '2',
+ {'choices': '1 2 3 4 5 6 auto'.split(), 'default': 'auto',
'metavar': '<level>'}),
no_xml_declaration=(
'Omit the XML declaration (default).',
Modified: trunk/docutils/test/data/help/docutils.rst
===================================================================
--- trunk/docutils/test/data/help/docutils.rst 2026-06-18 13:27:39 UTC (rev 10364)
+++ trunk/docutils/test/data/help/docutils.rst 2026-06-18 13:27:53 UTC (rev 10365)
@@ -167,7 +167,8 @@
--initial-header-level=<level>
Specify the initial header level. Does not affect
document title & subtitle (see --no-doc-title).
- (default: 2 for "<h2>")
+ Default: "auto" (<h2> if there is a document title,
+ else <h1>).
--footnote-references=<format>
Format for footnote references: one of "superscript"
or "brackets". (default: "brackets")
Modified: trunk/docutils/test/functional/expected/standalone_rst_html5.html
===================================================================
--- trunk/docutils/test/functional/expected/standalone_rst_html5.html 2026-06-18 13:27:39 UTC (rev 10364)
+++ trunk/docutils/test/functional/expected/standalone_rst_html5.html 2026-06-18 13:27:53 UTC (rev 10365)
@@ -884,7 +884,7 @@
</aside>
<aside class="footnote brackets" id="footnote-18" role="doc-footnote">
<span class="label"><span class="fn-bracket">[</span><a role="doc-backlink" href="#footnote-reference-32">18</a><span class="fn-bracket">]</span></span>
-<p><a class="reference external" href="https://stackoverflow.com/questions/39547412/same-font-size-for-h1-and-h2-in-article">https://stackoverflow.com/questions/39547412/same-font-size-for-h1-and-h2-in-article</a></p>
+<p><a class="reference external" href="https://html.spec.whatwg.org/multipage/sections.html#outline">https://html.spec.whatwg.org/multipage/sections.html#outline</a></p>
</aside>
<aside class="footnote brackets" id="footnote-19" role="doc-footnote">
<span class="label"><span class="fn-bracket">[</span><a role="doc-backlink" href="#footnote-reference-33">19</a><span class="fn-bracket">]</span></span>
@@ -1290,9 +1290,10 @@
<li><p>Put subtitles in <p> elements.</p></li>
<li><p>Use the new semantic tags <main>, <section>, <header>,
<footer>, <aside>, <figure>, and <figcaption>.
-See <span class="docutils literal">minimal.css</span> and <span class="docutils literal">responsive.css</span> for styling rule examples.</p>
-<p>Change the <cite>initial_header_level</cite> setting default to "2", as browsers
-use the <a class="reference external" href="https://stackoverflow.com/questions/39547412/same-font-size-for-h1-and-h2-in-article">same style for <h1> and <h2> when nested in a <section></a> <a class="brackets" href="#footnote-18" id="footnote-reference-32" role="doc-noteref"><span class="fn-bracket">[</span>18<span class="fn-bracket">]</span></a>.</p>
+See <span class="docutils literal">minimal.css</span> and <span class="docutils literal">responsive.css</span> for styling rule examples.</p></li>
+<li><p>Change the "initial_header_level" setting default to "auto"
+(<h2> if there is a document title, else <h1>) to ensure
+the HTML document has a clean <a class="reference external" href="https://html.spec.whatwg.org/multipage/sections.html#outline">outline</a> <a class="brackets" href="#footnote-18" id="footnote-reference-32" role="doc-noteref"><span class="fn-bracket">[</span>18<span class="fn-bracket">]</span></a>.</p>
</li>
<li><p>Use HTML5 tags <small>, <s>, <q>, <dfn>, <var>, <samp>, <kbd>,
<i>, <b>, <u>, <mark>, and <bdi> if a matching class value
Modified: trunk/docutils/test/functional/input/data/html5-features.rst
===================================================================
--- trunk/docutils/test/functional/input/data/html5-features.rst 2026-06-18 13:27:39 UTC (rev 10364)
+++ trunk/docutils/test/functional/input/data/html5-features.rst 2026-06-18 13:27:53 UTC (rev 10365)
@@ -23,10 +23,11 @@
<footer>, <aside>, <figure>, and <figcaption>.
See ``minimal.css`` and ``responsive.css`` for styling rule examples.
- Change the `initial_header_level` setting default to "2", as browsers
- use the `same style for <h1> and <h2> when nested in a <section\>`__.
+* Change the "initial_header_level" setting default to "auto"
+ (<h2> if there is a document title, else <h1>) to ensure
+ the HTML document has a clean outline__.
- __ https://stackoverflow.com/questions/39547412/same-font-size-for-h1-and-h2-in-article
+ __ https://html.spec.whatwg.org/multipage/sections.html#outline
* Use HTML5 tags <small>, <s>, <q>, <dfn>, <var>, <samp>, <kbd>,
<i>, <b>, <u>, <mark>, and <bdi> if a matching class value
Modified: trunk/docutils/test/test_writers/test_html5_polyglot.py
===================================================================
--- trunk/docutils/test/test_writers/test_html5_polyglot.py 2026-06-18 13:27:39 UTC (rev 10364)
+++ trunk/docutils/test/test_writers/test_html5_polyglot.py 2026-06-18 13:27:53 UTC (rev 10365)
@@ -187,15 +187,15 @@
""",
"""\
<section id="title">
-<h2>Title<a class="self-link" title="link to this section" href="#title"></a></h2>
+<h1>Title<a class="self-link" title="link to this section" href="#title"></a></h1>
<section id="not-a-subtitle">
-<h3>Not A Subtitle<a class="self-link" title="link to this section" href="#not-a-subtitle"></a></h3>
+<h2>Not A Subtitle<a class="self-link" title="link to this section" href="#not-a-subtitle"></a></h2>
<p>Some stuff</p>
<section id="section">
-<h4>Section<a class="self-link" title="link to this section" href="#section"></a></h4>
+<h3>Section<a class="self-link" title="link to this section" href="#section"></a></h3>
<p>Some more stuff</p>
<section id="another-section">
-<h5>Another Section<a class="self-link" title="link to this section" href="#another-section"></a></h5>
+<h4>Another Section<a class="self-link" title="link to this section" href="#another-section"></a></h4>
<p>And even more stuff</p>
</section>
</section>
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
|
From: <mi...@us...> - 2026-06-18 13:27:42
|
Revision: 10364
http://sourceforge.net/p/docutils/code/10364
Author: milde
Date: 2026-06-18 13:27:39 +0000 (Thu, 18 Jun 2026)
Log Message:
-----------
Inform when a directive has content above and below options.
Generate an INFO message if a directive that does not take arguments
has content above and below directive options.
Modified Paths:
--------------
trunk/docutils/HISTORY.rst
trunk/docutils/RELEASE-NOTES.rst
trunk/docutils/docutils/parsers/rst/states.py
trunk/docutils/test/test_transforms/test_messages.py
Modified: trunk/docutils/HISTORY.rst
===================================================================
--- trunk/docutils/HISTORY.rst 2026-06-18 07:56:49 UTC (rev 10363)
+++ trunk/docutils/HISTORY.rst 2026-06-18 13:27:39 UTC (rev 10364)
@@ -77,6 +77,8 @@
- Do not add "name" attribute to `<reference>` elements
nor set the internal attribute `indirect_reference_name`.
+ - Report INFO message, if a directive that does not take
+ arguments has content above and below directive options.
* docutils/readers/standalone.py
Modified: trunk/docutils/RELEASE-NOTES.rst
===================================================================
--- trunk/docutils/RELEASE-NOTES.rst 2026-06-18 07:56:49 UTC (rev 10363)
+++ trunk/docutils/RELEASE-NOTES.rst 2026-06-18 13:27:39 UTC (rev 10364)
@@ -79,10 +79,6 @@
Parsers
-------
-* The "rst" parser will issue an INFO, if a directive that does not take
- arguments has content above and below directive options in
- Docutils 0.24 or later.
-
* The "rst" parser will warn if a `"figure"`_ directive is missing both
caption and legend in Docutils 1.0.
Modified: trunk/docutils/docutils/parsers/rst/states.py
===================================================================
--- trunk/docutils/docutils/parsers/rst/states.py 2026-06-18 07:56:49 UTC (rev 10363)
+++ trunk/docutils/docutils/parsers/rst/states.py 2026-06-18 13:27:39 UTC (rev 10364)
@@ -2326,6 +2326,11 @@
options = {}
if arg_block and not (directive.required_arguments
or directive.optional_arguments):
+ if options and content:
+ self.reporter.info(
+ 'Directive content before and after options.',
+ nodes.literal_block('', '\n'.join(indented)),
+ line=content_offset)
content = arg_block + indented[i:]
content_offset = line_offset
arg_block = []
Modified: trunk/docutils/test/test_transforms/test_messages.py
===================================================================
--- trunk/docutils/test/test_transforms/test_messages.py 2026-06-18 07:56:49 UTC (rev 10363)
+++ trunk/docutils/test/test_transforms/test_messages.py 2026-06-18 13:27:39 UTC (rev 10364)
@@ -25,10 +25,13 @@
class TransformTestCase(unittest.TestCase):
+ maxDiff = None
+
def test_transforms(self):
parser = Parser()
settings = get_default_settings(Parser)
settings.warning_stream = ''
+ settings.report_level = 1
for name, (transforms, cases) in totest.items():
for casenum, (case_input, case_expected) in enumerate(cases):
with self.subTest(id=f'totest[{name!r}][{casenum}]'):
@@ -79,6 +82,31 @@
<paragraph>
Undefined substitution referenced: "unknown substitution".
"""],
+["""\
+.. note:: Directive content above
+ :class: custom
+
+ and below directive options can be confusing.
+""",
+"""\
+<document source="test data">
+ <note classes="custom">
+ <paragraph>
+ Directive content above
+ <paragraph>
+ and below directive options can be confusing.
+ <section classes="system-messages">
+ <title>
+ Docutils System Messages
+ <system_message level="1" line="3" source="test data" type="INFO">
+ <paragraph>
+ Directive content before and after options.
+ <literal_block xml:space="preserve">
+ Directive content above
+ :class: custom
+ \n\
+ and below directive options can be confusing.
+"""],
])
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
8 messages has been excluded from this view by a project administrator.
