SF.net SVN: docutils:[10166 ] trunk/docutils
milde--- via Docutils-checkins <[email protected]> Mon, 16 Jun 2025 09:45:12 +0000
| Newsgroups | gmane.text.docutils.cvs |
|---|---|
| Message-ID | <[email protected]> |
Revision: 10166
http://sourceforge.net/p/docutils/code/10166
Author: milde
Date: 2025-06-16 09:45:10 +0000 (Mon, 16 Jun 2025)
Log Message:
-----------
Documentation edits.
Fixes and clarifications.
Modified Paths:
--------------
trunk/docutils/HISTORY.rst
trunk/docutils/RELEASE-NOTES.rst
trunk/docutils/docs/api/transforms.rst
trunk/docutils/docs/ref/rst/directives.rst
trunk/docutils/docs/user/latex.rst
trunk/docutils/docutils/transforms/misc.py
trunk/docutils/docutils/transforms/references.py
Modified: trunk/docutils/HISTORY.rst
===================================================================
--- trunk/docutils/HISTORY.rst 2025-06-10 20:46:23 UTC (rev 10165)
+++ trunk/docutils/HISTORY.rst 2025-06-16 09:45:10 UTC (rev 10166)
@@ -37,8 +37,10 @@
- Replace `Writer.bibtex_reference_resolver()` with a transform.
- `LaTeXTranslator.visit_inline()` now inserts labels for the
node's IDs.
- - Disable "hyperref" footnote handling to avoid "empty anchor" warnings.
- - Re-style system messages.
+ - Disable footnote handling by the "hyperref" LaTeX package (Docutils'
+ ``\DUfootnotemark`` and ``\DUfootnotetext`` macros implement
+ hyperlinks and backlinks). Avoids "empty anchor" warnings.
+ - Fix target position and re-style system messages.
- Don't merge paragraphs if there is a target between them.
* docutils/writers/manpage.py
@@ -56,9 +58,9 @@
* docutils/parsers/rst/states.py
- - Remove the list`states.RSTStateMachine.memo.section_parents`
+ - Remove the `states.RSTStateMachine.memo.section_parents` cache
(introduced in Docutils 0.22rc1) that broke 3rd-party applications
- setting up a "mock memo".
+ employing a "mock memo".
- Use `types.SimpleNamespace` instead of a local definition for
the auxilliary class `states.Struct`.
@@ -155,7 +157,7 @@
- Pass the included file's path to the parser when the
"include" directive is used with :parser: option.
- Enables system messages with correct source/line indication.
+ Enables system messages with correct source/line info.
* docutils/parsers/rst/directives/tables.py
@@ -192,7 +194,7 @@
* docutils/transforms/writer_aux.py
- - Removed `Compound` class.
+ - Removed `Compound` transform.
* docutils/transforms/references.py
@@ -200,7 +202,8 @@
* docutils/transforms/universal.py
- - `Messages` also handles "loose" system messages generated by the parser.
+ - `Messages` transform now also handles "loose" system messages
+ generated by the parser.
* docutils/utils/__init__.py
@@ -241,10 +244,10 @@
* docutils/writers/latex2e/__init__.py
- `LaTeXTranslator.to_latex_length()`:
- remove optional argument `pxunit` (ignored since at least 2012),
- drop trailing zeroes from length values,
- move XeTeX-specific code to the "xetex" writer.
Handle CSS3 `length units`_.
+ Remove optional argument `pxunit` (ignored since at least 2012).
+ Drop trailing zeroes from length values.
+ Move XeTeX-specific code to the "xetex" writer.
- Don't wrap references with custom reference-label_ in
a ``\hyperref`` command.
- Mark the main language when loading "babel".
@@ -251,10 +254,10 @@
- Provide an "unknown_references_resolver" (cf. `docutils/TransformSpec`)
for citation references resolved with BibTeX (cf. `use_bibtex`_ setting).
- Support SVG image inclusion with the "svg" LaTeX package (see the
- `stylesheet`__ configuration setting).
+ `stylesheet`__ configuration setting). Solves feature-request #83
- Add "template" to the parts returned by `Writer.assemble_parts()`.
- Use standard `dict` for `LaTeXTranslator.requirements`
- and`LaTeXTranslator.fallbacks`.
+ and `LaTeXTranslator.fallbacks`.
- Use <document> "title" attribute in pdfinfo.
- Encode <meta> element content in pdfinfo.
- Improve formatting of docinfo fields.
@@ -303,7 +306,7 @@
* tools/rst2odt_prepstyles.py
- - Removed. Use `docutils.writers.odf_odt.prepstyles`.
+ - Removed. Use ``python -m docutils.writers.odf_odt.prepstyles``.
.. _length units: docs/ref/rst/restructuredtext.html#length-units
Modified: trunk/docutils/RELEASE-NOTES.rst
===================================================================
--- trunk/docutils/RELEASE-NOTES.rst 2025-06-10 20:46:23 UTC (rev 10165)
+++ trunk/docutils/RELEASE-NOTES.rst 2025-06-16 09:45:10 UTC (rev 10166)
@@ -173,7 +173,7 @@
in Docutils 1.0. Use a transform_,
see `transforms.references.CitationReferences` for an example.
-* Ignore `transforms.references.DanglingReferences` and
+* Don't call `transforms.references.DanglingReferences` and
`transforms.references.DanglingReferencesVisitor` in Docutils 1.0;
remove them in Docutils 2.0. [rationale__]
@@ -186,7 +186,7 @@
* Remove the "rawsource" argument from `nodes.Text.__init__()`
in Docutils 2.0.
-* Remove attributes `nodes.Element.known_attributes`,
+* Remove the internal attributes `nodes.Element.known_attributes`,
`nodes.Element.basic_attributes`, and `nodes.Element.local_attributes`,
in Docutils 2.0.
@@ -246,12 +246,13 @@
Nothing yet.
+
Release 0.22rc3 (2025-06-10)
============================
New objects
- `transforms.references.`CitationReferences`
- Mark citation_references as resolved if the backend (LaTeX)
+ `transforms.references.CitationReferences`
+ Mark citation_references as resolved if the backend
uses a BibTeX database.
Output changes
@@ -259,6 +260,7 @@
manpage:
Do not drop text of internal targets.
+
Release 0.22rc2 (2025-05-22)
============================
@@ -303,13 +305,17 @@
Output changes
LaTeX:
- Don't wrap references with custom reference-label_ in a ``\hyperref``
+ Don't wrap references with custom reference_label_ in a ``\hyperref``
command. The "hyperref" package generates hyperlinks for labels by
- default, so there is no change in the PDF (except for "ref*").
+ default, so there is no change in the PDF
+ (except for the starred forms like ``reference_label = \ref*``).
- Stop requiring "ifthen.sty". Replace use of
- ``\ifthenelse{\isundefined...`` with the eTeX primitive ``\ifdefined``.
+ Stop requiring "ifthen.sty". Add "ifthen" to the stylesheet__ setting
+ or replace use of ``\ifthenelse{\isundefined...`` with the eTeX
+ primitive ``\ifdefined``.
+ __ docs/user/config.html#stylesheet-2
+
HTML5:
Unitless image_ size measures__ are written as <img> "width" and
"hight" values instead of "style" rules. The current behaviour
@@ -320,8 +326,9 @@
manpage:
Don't UPPERCASE section headings.
- Handle hyperlink references (see text_references_).
+ Handle hyperlink references (see the text_references_ setting).
+
null:
The "null" writer output changed from None to the empty string.
@@ -1505,7 +1512,7 @@
docs/user/config.html#old-format-configuration-files
.. _output:
.. _output_path: docs/user/config.html#output-path
-.. _reference-label: docs/user/config.html#reference-label
+.. _reference_label: docs/user/config.html#reference-label
.. _root_prefix: docs/user/config.html#root-prefix
.. _SmartQuotes: docs/user/config.html#smart-quotes
.. _sources: docs/user/config.html#sources
Modified: trunk/docutils/docs/api/transforms.rst
===================================================================
--- trunk/docutils/docs/api/transforms.rst 2025-06-10 20:46:23 UTC (rev 10165)
+++ trunk/docutils/docs/api/transforms.rst 2025-06-16 09:45:10 UTC (rev 10166)
@@ -137,10 +137,10 @@
* (t): Transform
* (/p): Via a `\<pending>`_ element
-.. [#dangling] `references.DanglingReferences` will be split into a
- transform resolving refnames__ to refids__ and a transform reporting
- unresolved references to make space for reference-resolving transforms
- added by extensions or applications
+.. [#dangling] `references.DanglingReferences` will be replaced by
+ separate transforms for resolving refnames__ to refids__
+ and for reporting unresolved references to make space for
+ reference-resolving transforms added by extensions or applications
(cf. `Release Notes`__).
__ ../ref/doctree.html#refname
Modified: trunk/docutils/docs/ref/rst/directives.rst
===================================================================
--- trunk/docutils/docs/ref/rst/directives.rst 2025-06-10 20:46:23 UTC (rev 10165)
+++ trunk/docutils/docs/ref/rst/directives.rst 2025-06-16 09:45:10 UTC (rev 10166)
@@ -610,7 +610,7 @@
The parsing can be turned off with the syntax_highlight_ configuration
setting and command line option or by specifying the language as
-`class <class option>`_ option instead of directive argument.
+`class <class option_>`_ option instead of directive argument.
This also avoids warnings when Pygments_ is not installed or the language
is not in the `supported languages and markup formats`_.
@@ -1317,13 +1317,20 @@
:Directive Options: `class <class option_>`_, name_
:Directive Content: none
-The "target-notes" directive creates a footnote for each external
-target in the text, and corresponding footnote references after each
-reference. For every explicit target (of the form, ``.. _target name:
-URL``) in the text, a footnote will be generated containing the
-visible URL as content.
+The "target-notes" directive generates a list of referenced URIs.
+This ensures the information is not lost in a hardcopy.
+For every explicit [#]_ `external hyperlink target`_ in the document,
+the "target-notes" directive inserts a `\<footnote>`_ showing the URL
+at the place of the directive and a `\<footnote_reference>`_ after each
+matching `hyperlink reference`_.
+The value of the `class option`_ is passed to the generated footnote
+references.
+
+.. [#] `Embedded URIs`_ like ```this <http://example.org>`_`` are skipped.
+
+
Footnotes
=========
@@ -1640,8 +1647,8 @@
where a negative value prevents expansion of hard tabs.
Defaults to the tab_width_ configuration setting.
-With ``code`` or ``literal`` the common options `class <class option_>`_ and name_
-are recognized as well.
+With ``code`` or ``literal``, the common options `class <class option_>`_
+and name_ are recognized as well.
Combining ``start-line``/``end-line`` and ``start-after``/``end-before``
is possible. The text markers will be searched in the specified lines
@@ -1748,13 +1755,13 @@
elements.
The "class" directive sets the `classes attribute`_ value on its content
-or on the first immediately following [#]_ non-comment element [#]_.
+or on the next visible [#]_ element. [#]_
The directive argument consists of one or more space-separated class
names. The names are transformed to conform to the regular expression
``[a-z](-?[a-z0-9]+)*`` (see `Identifier Normalization`_ below).
-.. tip:: For reStructuredText directives, it is recommended to use the
- `class option`_ option instead of wrapping them in a "class" directive.
+.. tip:: For reStructuredText directives, the `class option`_ provides
+ a more compact markup alternative.
Examples::
@@ -1789,40 +1796,38 @@
<paragraph classes="multiple">
Second paragraph.
+Indented text after the directive is interpreted as content block.
+To set a classes attribute value on a `block quote`_, the
+"class" directive must be followed by a comment::
-.. [#] This is also true, if the class directive is "nested" at the end of
- an indented text block, for example::
+ .. class:: special
+ ..
- .. note:: the class values set in this directive-block do not apply to
- the note but the next paragraph.
+ Special block quote.
- .. class:: special
+results in this doctree_ fragment::
- This is a paragraph with class value "special".
+ <comment xml:space="preserve">
+ <block_quote classes="special">
+ <paragraph>
+ Special block quote.
+.. [#] Elements that are not shown in the output (comments_,
+ `substitution definitions`_, `hyperlink targets`_, ...) as well as
+ "header_" and "footer_" directives are skipped.
+
+.. [#] This also works if the class directive is "nested" at the end of
+ an indented text block.
This allows the "classification" of individual list items (except the
first, as a preceding class directive applies to the list as a whole)::
* bullet list
- .. class:: classy item
+ .. class:: classy-item
* second item, with class argument
-.. [#] To set a `classes attribute`_ value on a block quote, the
- "class" directive must be followed by an empty comment::
- .. class:: highlights
- ..
-
- Block quote text.
-
- Without the empty comment, the indented text would be interpreted as the
- "class" directive's content, and the classes would be applied to each
- element (paragraph, in this case) individually, instead of to the block
- quote as a whole.
-
-
Identifier Normalization
~~~~~~~~~~~~~~~~~~~~~~~~
@@ -1839,7 +1844,7 @@
* leading hyphens and number characters, and
* trailing hyphens.
-For example ``"Rot.Gelb&Grün:+2008"`` becomes ``"rot-gelb-grun-2008"`` and
+For example ``"Rot.Gelb&Grün::2008+"`` becomes ``"rot-gelb-grun-2008"`` and
``"1000_Steps!"`` becomes ``"steps"``.
.. topic:: Rationale:
@@ -2048,7 +2053,7 @@
:Directive Options: none
:Directive Content: Must contain a flat `field list`_.
-The "meta" directive is used to specify metadata\ [#]_ to be stored
+The "meta" directive is used to specify metadata [#]_ to be stored
in, e.g., `HTML meta elements`_ or as `ODT file properties`_. The
LaTeX writer passes it to the ``pdfinfo`` option of the hyperref_
package. If an output format does not support "invisible" metadata,
@@ -2259,12 +2264,18 @@
https://docs.python.org/3/library/codecs.html#standard-encodings
.. _reStructuredText Markup Specification: restructuredtext.html
-.. _Directives: restructuredtext.html#directives
+.. _block quote: restructuredtext.html#block-quotes
+.. _comments: restructuredtext.html#comments
+.. _directives: restructuredtext.html#directives
.. _document title: restructuredtext.html#document-title
+.. _embedded URIs: restructuredtext.html#embedded-uris-and-aliases
.. _escaping mechanism: restructuredtext.html#escaping-mechanism
+.. _external hyperlink target:
.. _external hyperlink targets:
restructuredtext.html#external-hyperlink-targets
+.. _hyperlink reference:
.. _hyperlink references: restructuredtext.html#hyperlink-references
+.. _hyperlink targets:
.. _hyperlink target: restructuredtext.html#hyperlink-targets
.. _supported length units: restructuredtext.html#length-units
.. _reference name:
Modified: trunk/docutils/docs/user/latex.rst
===================================================================
--- trunk/docutils/docs/user/latex.rst 2025-06-10 20:46:23 UTC (rev 10165)
+++ trunk/docutils/docs/user/latex.rst 2025-06-16 09:45:10 UTC (rev 10166)
@@ -91,9 +91,10 @@
The LaTeX writer supports all `reStructuredText length units`_
with the following peculiarities:
-* In LaTeX, the size of the *pixel unit* `can be configured
- <size of a "px"_>`__. It defaults to **1 px = 1/72 in**
+* In LaTeX, the size of the *pixel unit* defaults to **1 px = 1/72 in**
while the `CSS3 pixel unit`_ is defined as 1 px = 1/96 in.
+ The LaTeX conversion factor can be configured,
+ see below for the `size of a "px"`_.
* LaTeX uses "pt" for the `American point`_ (*TeX point*), 1 pt = 1/72.25 in.
The `DTP point`_ (*Postscript point*) used in CSS is available in LaTeX
Modified: trunk/docutils/docutils/transforms/misc.py
===================================================================
--- trunk/docutils/docutils/transforms/misc.py 2025-06-10 20:46:23 UTC (rev 10165)
+++ trunk/docutils/docutils/transforms/misc.py 2025-06-16 09:45:10 UTC (rev 10166)
@@ -38,7 +38,7 @@
"""
Move the "class" attribute specified in the "pending" node into the
- immediately following non-comment element.
+ next visible element.
"""
default_priority = 210
Modified: trunk/docutils/docutils/transforms/references.py
===================================================================
--- trunk/docutils/docutils/transforms/references.py 2025-06-10 20:46:23 UTC (rev 10165)
+++ trunk/docutils/docutils/transforms/references.py 2025-06-16 09:45:10 UTC (rev 10166)
@@ -862,7 +862,10 @@
if not getattr(self.document.settings, 'use_bibtex', []):
return
for node in self.document.findall(nodes.citation_reference):
- # Skip nodes that are resolved or have a matching target:
+ # Skip nodes that are resolved or have a matching target
+ # and will be resolved by `DanglingReferences`:
+ # TODO: drop the second condition when `DanglingReferences` is
+ # replaced by two separate transitions.
if node.resolved or self.document.nameids.get(node.get('refname')):
continue
if node.astext(): # ensure text content (becomes the BibTeX key)
@@ -875,6 +878,13 @@
"""
Check for dangling references (incl. footnote & citation) and for
unreferenced targets.
+
+ Provisional : pending deprecation
+ Docutils readers will add separate transforms for resolving
+ refnames to refids and for reporting unresolved references
+ instead of this transform (to make space for reference-resolving
+ transforms added by extensions or applications) in Docutils 1.0.
+ This transform will be removed in Docutils 2.0.
"""
default_priority = 850
@@ -908,7 +918,13 @@
class DanglingReferencesVisitor(nodes.SparseNodeVisitor):
+ """Provisional : pending deprecation
+ This auxiliary class is used by the `DanglingReferences` transform
+ which will no longer be used in Docutils 1.0.
+ It will be removed in Docutils 2.0.
+ """
+
def __init__(self, document, unknown_reference_resolvers) -> None:
nodes.SparseNodeVisitor.__init__(self, document)
self.document = document
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
_______________________________________________
Docutils-checkins mailing list
[email protected]
https://lists.sourceforge.net/lists/listinfo/docutils-checkins