Menu
▾
▴
[Docutils-checkins] SF.net SVN: docutils:[10176] trunk/docutils
|
From: <mi...@us...> - 2025-06-18 14:03:37
|
Revision: 10176
http://sourceforge.net/p/docutils/code/10176
Author: milde
Date: 2025-06-18 14:03:25 +0000 (Wed, 18 Jun 2025)
Log Message:
-----------
Make targets from hyperlink references with embedded URI or alias implicit.
Embedding a URI or alias name in a hyperlink reference is no explicit request
for a target (cf. bug #502). Downgrade the priority of the generated targets from
explicit to implicit to avoid surprising warnings in case of name duplication.
(Anonymous references can be used to avoid the warnings but, in case of a typo,
the warnings/errors have no source/line information.)
Modified Paths:
--------------
trunk/docutils/HISTORY.rst
trunk/docutils/RELEASE-NOTES.rst
trunk/docutils/docs/ref/rst/restructuredtext.rst
trunk/docutils/docutils/nodes.py
trunk/docutils/docutils/parsers/rst/states.py
trunk/docutils/test/test_parsers/test_rst/test_inline_markup.py
trunk/docutils/test/test_parsers/test_rst/test_targets.py
Modified: trunk/docutils/HISTORY.rst
===================================================================
--- trunk/docutils/HISTORY.rst 2025-06-17 13:10:08 UTC (rev 10175)
+++ trunk/docutils/HISTORY.rst 2025-06-18 14:03:25 UTC (rev 10176)
@@ -17,28 +17,31 @@
Release 0.22rc5 (unpublished)
=============================
-.
+* docutils/docutils/parsers/rst/states.py
+ - "Downgrade" targets generated from hyperlink references with embedded
+ URI or alias from explicit to implicit (cf. bug #502).
+
Release 0.22rc4 (2025-06-17)
============================
* docutils/nodes.py
- Don't include a "backlink" reference in system messages, if the
- referenced element is an external target (not visible in the output).
+ - Don't include a "backlink" reference in system messages, if the
+ referenced element is an external target (not visible in the output).
* docutils/parsers/rst/directives/references.py
- Remove "name" from `TargetNotes.option_spec`.
- The "target-notes" directive generates one footnote element per
- external target but "name" must be unique across the document.
- So far, the name was silently dropped.
+ - Remove "name" from `TargetNotes.option_spec`.
+ The "target-notes" directive generates one footnote element per
+ external target but "name" must be unique across the document.
+ So far, the name was silently dropped.
* docutils/parsers/rst/languages/en.py
- Add alias "rst-class" for the "class" directive to improve the
- compatibility with Sphinx.
+ - Add alias "rst-class" for the "class" directive to improve the
+ compatibility with Sphinx.
Release 0.22rc3 (2025-06-10)
Modified: trunk/docutils/RELEASE-NOTES.rst
===================================================================
--- trunk/docutils/RELEASE-NOTES.rst 2025-06-17 13:10:08 UTC (rev 10175)
+++ trunk/docutils/RELEASE-NOTES.rst 2025-06-18 14:03:25 UTC (rev 10176)
@@ -247,9 +247,15 @@
Release 0.22rc5 (unpublished)
=============================
-.
+Targets generated from hyperlink references with embedded URI or alias
+are no longer "explicit" but "implicit" (i.e. with the same priority as
+auto-generated section targets, see `implicit hyperlink targets`__).
+__ https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html
+ #implicit-hyperlink-targets
+
+
Release 0.22rc4 (2025-06-17)
============================
Modified: trunk/docutils/docs/ref/rst/restructuredtext.rst
===================================================================
--- trunk/docutils/docs/ref/rst/restructuredtext.rst 2025-06-17 13:10:08 UTC (rev 10175)
+++ trunk/docutils/docs/ref/rst/restructuredtext.rst 2025-06-18 14:03:25 UTC (rev 10176)
@@ -1877,7 +1877,7 @@
:Doctree element: `\<citation>`_
:See also: `citation references`_
-Citations are identical to footnotes except that they use only
+Citations are identical to footnotes_ except that they use only
non-numeric labels such as ``[note]`` or ``[GVR2001]``. Citation
labels are simple `reference names`_ (case-insensitive single words
consisting of alphanumerics plus internal hyphens, underscores, and
@@ -2451,18 +2451,19 @@
This is a block quote.
+.. _implicit hyperlink target:
+
Implicit Hyperlink Targets
==========================
:Doctree element: `\<target>`_
-Implicit hyperlink targets are generated by `section titles`_, footnotes_,
-and citations_, and may also be generated by extension constructs.
-Implicit hyperlink targets otherwise behave identically to explicit
-`hyperlink targets`_.
+Implicit hyperlink targets are generated by `section titles`_,
+auto-numbered footnotes_, and hyperlink references with `embedded URIs
+and aliases`_. They may also be generated by extension constructs.
-Problems of ambiguity due to conflicting duplicate implicit and
-explicit reference names are avoided by following this procedure:
+Implicit hyperlink targets behave identically to explicit `hyperlink
+targets`_ except in case of duplicate reference names:
1. `Explicit hyperlink targets`_ override any implicit targets having
the same reference name. The implicit hyperlink targets are
@@ -2475,10 +2476,12 @@
hyperlink targets.
3. Duplicate explicit hyperlink targets are removed, and level-2
- (warning) system messages are inserted. Exception: duplicate
- `external hyperlink targets`_ (identical hyperlink names and
- referenced URIs) do not conflict, and are not removed.
+ (warning) system messages are inserted.
+4. Exception: duplicate `external hyperlink targets`_ (identical
+ reference names and referenced URIs) do not conflict, and are not
+ removed.
+
System messages are inserted where target links have been removed.
See "Error Handling" in `PEP 258`_.
@@ -2875,7 +2878,7 @@
This `link <Python home page_>`_ is an alias to the link above.
-This is exactly equivalent to::
+This is equivalent to::
See the `Python home page`_ for info.
@@ -2887,12 +2890,13 @@
The bracketed URI must be preceded by whitespace and be the last text
before the end string.
-With a single trailing underscore, the reference is *named* -- the
-`reference name`_ should be unique and may be referred to again.
-With two trailing underscores, the reference and target are both
-anonymous_ and the target cannot be referred to again. These are
-"one-off" hyperlinks. For example::
+With a single trailing underscore, the reference is *named*
+and generates an `implicit hyperlink target`_.
+With two trailing underscores, the reference is anonymous_
+and the link text cannot be re-used as reference name.
+These are "one-off" hyperlinks. For example::
+
`RFC 2396 <https://www.rfc-editor.org/rfc/rfc2396.txt>`__ and `RFC
2732 <https://www.rfc-editor.org/rfc/rfc2732.txt>`__ together
define the syntax of URIs.
@@ -2922,7 +2926,7 @@
be backslash-escaped or an escaped space should follow. For example, here
are three references to titles describing a tag::
- See `HTML Element: \<a>`_, `HTML Element: <b\> `_, and
+ See `HTML Element: \<a>`_, `HTML Element: <b\>`_, and
`HTML Element: <c>\ `_.
The reference text may also be omitted, in which case the URI will be
Modified: trunk/docutils/docutils/nodes.py
===================================================================
--- trunk/docutils/docutils/nodes.py 2025-06-17 13:10:08 UTC (rev 10175)
+++ trunk/docutils/docutils/nodes.py 2025-06-18 14:03:25 UTC (rev 10176)
@@ -1929,18 +1929,21 @@
self.nametypes[name] = old_explicit or explicit
- if explicit:
+ if (old_id is not None and 'refuri' in node
+ and node['refuri'] == old_node.get('refuri')):
+ # external targets with same URI -> keep old target
+ level = 1
+ ref = node["refuri"]
+ s = f'Duplicate name "{name}" for external target "{ref}".'
+ dupname(node, name)
+ elif explicit:
if old_explicit:
level = 2
s = f'Duplicate explicit target name: "{name}".'
dupname(node, name)
if old_id is not None:
- if ('refuri' in node and 'refuri' in old_node
- and node['refuri'] == old_node['refuri']):
- level = 1 # keep old target, just inform
- else:
- dupname(old_node, name)
- self.nameids[name] = None
+ dupname(old_node, name)
+ self.nameids[name] = None
else: # new explicit, old implicit -> override
self.nameids[name] = id
if old_id is not None:
Modified: trunk/docutils/docutils/parsers/rst/states.py
===================================================================
--- trunk/docutils/docutils/parsers/rst/states.py 2025-06-17 13:10:08 UTC (rev 10175)
+++ trunk/docutils/docutils/parsers/rst/states.py 2025-06-18 14:03:25 UTC (rev 10176)
@@ -858,7 +858,7 @@
else:
reference['refuri'] = alias
# target.note_referenced_by(name=refname)
- self.document.note_explicit_target(target, self.parent)
+ self.document.note_implicit_target(target, self.parent)
node_list.append(target)
else:
reference['refname'] = refname
Modified: trunk/docutils/test/test_parsers/test_rst/test_inline_markup.py
===================================================================
--- trunk/docutils/test/test_parsers/test_rst/test_inline_markup.py 2025-06-17 13:10:08 UTC (rev 10175)
+++ trunk/docutils/test/test_parsers/test_rst/test_inline_markup.py 2025-06-18 14:03:25 UTC (rev 10176)
@@ -1167,15 +1167,15 @@
Report duplicate refname.
<paragraph>
Explicit targets: \n\
- <target dupnames="file.txt" ids="file-txt">
+ <target ids="file-txt" names="file.txt">
file.txt
, \n\
<target ids="file-html" names="file.html">
file.html
.
- <system_message level="2" line="6" source="test data" type="WARNING">
+ <system_message level="1" line="6" source="test data" type="INFO">
<paragraph>
- Duplicate explicit target name: "file.txt".
+ Duplicate implicit target name: "file.txt".
<paragraph>
Embedded URI: named \n\
<reference name="file.txt" refuri="file.txt">
@@ -1300,9 +1300,9 @@
<target ids="tg2" names="tg2">
tg2
.
- <system_message backrefs="link-1" level="2" line="6" source="test data" type="WARNING">
+ <system_message backrefs="link-1" level="1" line="6" source="test data" type="INFO">
<paragraph>
- Duplicate explicit target name: "link".
+ Duplicate implicit target name: "link".
<paragraph>
References with embedded alias: \n\
<reference name="link" refname="tg1">
Modified: trunk/docutils/test/test_parsers/test_rst/test_targets.py
===================================================================
--- trunk/docutils/test/test_parsers/test_rst/test_targets.py 2025-06-17 13:10:08 UTC (rev 10175)
+++ trunk/docutils/test/test_parsers/test_rst/test_targets.py 2025-06-18 14:03:25 UTC (rev 10176)
@@ -218,11 +218,11 @@
<target ids="target" names="target" refuri="first">
<system_message level="1" line="5" source="test data" type="INFO">
<paragraph>
- Duplicate explicit target name: "target".
+ Duplicate name "target" for external target "first".
<target dupnames="target" ids="target-1" refuri="first">
"""],
["""\
-Duplicate external targets (same URIs):
+Duplicate external targets (embedded/explicit, same URIs):
See the `example <example.rst>`_
@@ -233,7 +233,7 @@
"""\
<document source="test data">
<paragraph>
- Duplicate external targets (same URIs):
+ Duplicate external targets (embedded/explicit, same URIs):
<paragraph>
See the \n\
<reference name="example" refuri="example.rst">
@@ -245,7 +245,7 @@
example
<system_message level="1" line="7" source="test data" type="INFO">
<paragraph>
- Duplicate explicit target name: "example".
+ Duplicate name "example" for external target "example.rst".
<target dupnames="example" ids="example-1" refuri="example.rst">
"""],
["""\
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
