Menu
▾
▴
[Docutils-checkins] SF.net SVN: docutils:[10380] trunk/docutils
|
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.
|
