Menu
▾
▴
[Docutils-checkins] SF.net SVN: docutils:[10185] trunk/docutils
|
From: <mi...@us...> - 2025-07-28 20:10:48
|
Revision: 10185
http://sourceforge.net/p/docutils/code/10185
Author: milde
Date: 2025-07-28 20:10:46 +0000 (Mon, 28 Jul 2025)
Log Message:
-----------
Documentation additions and fixes.
Announce future changes to the ID generation.
Cf. Sphinx issue #1961 (https://github.com/sphinx-doc/sphinx/issues/1961).
Glossary entry for "unit proportion" in doctree doc.
TODO-comment: use imagesize.py to get dimensions from image files.
Faster than PIL, also handles SVG. (cf. Sphinx)
Various small fixes.
Modified Paths:
--------------
trunk/docutils/RELEASE-NOTES.rst
trunk/docutils/docs/ref/doctree.rst
trunk/docutils/docs/ref/rst/directives.rst
trunk/docutils/docs/user/html.rst
trunk/docutils/docs/user/latex.rst
trunk/docutils/docutils/nodes.py
trunk/docutils/docutils/writers/_html_base.py
Modified: trunk/docutils/RELEASE-NOTES.rst
===================================================================
--- trunk/docutils/RELEASE-NOTES.rst 2025-07-11 12:41:40 UTC (rev 10184)
+++ trunk/docutils/RELEASE-NOTES.rst 2025-07-28 20:10:46 UTC (rev 10185)
@@ -217,6 +217,12 @@
Misc
----
+* 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
+
* Revise the `String I/O`__ interface used by the `publish_string()`
and `publish_from_doctree()` publisher convenience functions.
(In Python 3, name and behaviour no longer match.)
Modified: trunk/docutils/docs/ref/doctree.rst
===================================================================
--- trunk/docutils/docs/ref/doctree.rst 2025-07-11 12:41:40 UTC (rev 10184)
+++ trunk/docutils/docs/ref/doctree.rst 2025-07-28 20:10:46 UTC (rev 10185)
@@ -972,7 +972,7 @@
Via the `%tbl.colspec.att`_ parameter entity, <colspec>
also accepts the `common attributes`_ and `stub`_.
- .. [#] Docutils ignores all but colwidth_.
+ .. [#] Docutils ignores all attributes except colwidth_.
__ https://www.oasis-open.org/specs/tm9901.html#AEN446
@@ -4516,8 +4516,9 @@
The attribute is defined in the `Exchange Table Model`_
(which `see for details`__) as either a *proportional measure*
-(positive number followed by "*", e.g., "5*" for 5 times the unit proportion,
-or just "*" for one unit proportion) or a *fixed measure* (e.g., 2.5cm).
+(positive number followed by "*", e.g., "5*" for 5 times the
+`unit proportion`_ , or just "*" for one unit proportion)
+or a *fixed measure* (e.g., 2.5cm).
Docutils supports only proportional measures.
.. important::
@@ -5594,7 +5595,25 @@
tabs, newlines, carriage returns, or form feeds, are replaced by a
single space. Leading and trailing whitespace is removed.
+_`Unit proportion`
+ is a length unit used in the definition of relative `table column widths`_
+ in the `Exchange Table Model`_.
+ Its definition boils down to
+
+ …, the *unit proportion* is determined by starting with the target
+ table width […].
+ Reduce that by the sum of border widths, column ruling widths, and
+ the fixed colwidths to get the available proportional width. […]
+ Then the unit proportion is the available proportional width divided
+ by the sum of the proportionality factors.
+
+ --- `Exchange Table Model, section 3.2.1`__
+
+ .. _table column widths: colwidth_
+ __ https://www.oasis-open.org/specs/tm9901.html#AEN285
+
+
------------
Bibliography
------------
Modified: trunk/docutils/docs/ref/rst/directives.rst
===================================================================
--- trunk/docutils/docs/ref/rst/directives.rst 2025-07-11 12:41:40 UTC (rev 10184)
+++ trunk/docutils/docs/ref/rst/directives.rst 2025-07-28 20:10:46 UTC (rev 10185)
@@ -151,14 +151,13 @@
--------
There are two directives to include images: image_ and figure_.
+The table below provides a non exhaustive overview of
+supported image formats.
.. attention::
- Images are not supported by the `manpage`_ writer.
-
It is up to the author to ensure compatibility of the image data format
- with the output format or user agent (LaTeX engine, `HTML browser`__).
- The following, non exhaustive table provides an overview.
+ with the output format or user agent (LaTeX engine, `HTML browser`__, …).
.. _image formats:
@@ -173,6 +172,8 @@
LaTeX_ [#]_ ✓ [#]_ ✓ ✓ ✓
+manpage_
+
ODT_ ✓ ✓ ✓ ✓ ✓
=========== ====== ====== ===== ===== ===== ===== ===== ===== ===== =====
@@ -188,7 +189,8 @@
.. [#] When compiling with ``pdflatex``, ``xelatex``, or ``lualatex``.
The original ``latex`` engine supports only the EPS image format.
Some build systems, e.g. rubber_ support additional formats
- via on-the-fly image conversion.
+ via on-the-fly image conversion. For details, see section
+ `image inclusion`__ in the LaTeX writer documentation.
.. [#] New in Docutils 0.22.
The `"svg" package`_ must be listed in the stylesheet__ setting.
@@ -198,10 +200,12 @@
.. _html4 writer: ../../user/html.html#html4css1
.. _HTML5:
.. _html5 writer: ../../user/html.html#html5
-.. _LaTeX: ../../user/latex.html#image-inclusion
+.. _LaTeX:
+.. _LaTeX writer: ../../user/latex.html
.. _ODT: ../../user/odt.html
.. _manpage: ../../user/manpage.html
.. _rubber: https://gitlab.com/latex-rubber/rubber
+__ ../../user/latex.html#image-inclusion
.. _"svg" package: https://ctan.org/pkg/svg
__ ../../user/config.html#stylesheet-latex-writers
@@ -849,7 +853,8 @@
supplies. Tables may be given titles with the "table_" directive.
Sometimes reStructuredText tables are inconvenient to write, or table
data in a standard format is readily available. The "csv-table_"
-directive supports CSV [#CSV]_ data.
+directive supports CSV [#CSV]_ data, the "list-table_" directive uses
+a list-based input format.
.. _table syntax: restructuredtext.html#tables
@@ -863,7 +868,7 @@
:Doctree Element: `\<table>`_
:Directive Arguments: one, optional (table caption)
:Directive Options: `see below <table options_>`__
-:Directive Content: A normal `reStructuredText table`_.
+:Directive Content: one reStructuredText `grid table`_ or `simple table`_
:Configuration Setting: table_style_
The "table" directive is used to provide a table caption
@@ -1052,6 +1057,8 @@
CSV dialect with the backslash as escape character.
+.. _list-table:
+
List Table
==========
@@ -2283,6 +2290,7 @@
.. _external hyperlink target:
.. _external hyperlink targets:
restructuredtext.html#external-hyperlink-targets
+.. _grid table: restructuredtext.html#grid-tables
.. _hyperlink reference:
.. _hyperlink references: restructuredtext.html#hyperlink-references
.. _hyperlink targets:
@@ -2290,7 +2298,7 @@
.. _supported length units: restructuredtext.html#length-units
.. _reference name:
.. _reference names: restructuredtext.html#reference-names
-.. _reStructuredText table: restructuredtext.html#tables
+.. _simple table: restructuredtext.html#simple-tables
.. _reStructuredText Interpreted Text Roles:
.. _interpreted text role: roles.html
Modified: trunk/docutils/docs/user/html.rst
===================================================================
--- trunk/docutils/docs/user/html.rst 2025-07-11 12:41:40 UTC (rev 10184)
+++ trunk/docutils/docs/user/html.rst 2025-07-28 20:10:46 UTC (rev 10185)
@@ -35,7 +35,7 @@
html5
-----
-:aliases: _`html5_polyglot`
+:aliases: _`html5_polyglot`, xhtml
:front-end: rst2html5_
:config: `[html5 writer]`_
@@ -84,7 +84,7 @@
html4css1
---------
-:aliases: html4, html_
+:aliases: html4, html_, xhtml10
:front-end: rst2html4_
:config: `[html4css1 writer]`_
Modified: trunk/docutils/docs/user/latex.rst
===================================================================
--- trunk/docutils/docs/user/latex.rst 2025-07-11 12:41:40 UTC (rev 10184)
+++ trunk/docutils/docs/user/latex.rst 2025-07-28 20:10:46 UTC (rev 10185)
@@ -171,7 +171,6 @@
.. contents:: :local:
-.. _option:
.. _setting:
.. _settings:
@@ -178,17 +177,16 @@
Options/Settings
----------------
-Docutils configuration settings can be specified as
+`Docutils configuration settings`_ can be specified as
+*command-line options* or *configuration settings*.
-* command-line options, or
-
-* configuration settings.
-
-Run ``rst2latex --help`` to get a list of available options;
+Run ``rst2latex --help`` to get a list of available options or
see `Docutils Configuration`_ for details.
+.. _Docutils configuration settings:
.. _Docutils Configuration: config.html
+
Classes
-------
@@ -564,7 +562,7 @@
.. _role directive: ../ref/rst/directives.html#role
.. _text roles: ../ref/rst/roles.html
-.. _class directive: ../ref/rst/directives.html#class
+.. _class directive: ../ref/rst/directives.html#class-directive
definition lists
----------------
@@ -1665,8 +1663,8 @@
------------
A pre-configured *table style* can be globally selected via the table_style_
-setting or set for individual tables via a `class directive`_ or the class
-option of the `table directive`_.
+setting or set for individual tables via a `class directive`_ or the
+``class`` option of the `table directive`_.
Supported values:
@@ -1681,7 +1679,7 @@
colwidths-auto
Column width determination by LaTeX.
- Overridden by the `table directive`_'s "widths" option.
+ Overridden by the `table directive`_'s ``widths`` option.
.. warning::
@@ -1697,7 +1695,7 @@
By default, *column widths* are computed from the source column widths.
The `legacy_column_widths`_ setting selects the conversion algorithm.
-Custom column widths can be set with the "widths" option of the `table
+Custom column widths can be set with the ``widths`` option of the `table
directive`_.
See also the section on problems with tables_ below.
@@ -1726,7 +1724,7 @@
* The depth of the ToC and PDF-bookmarks can be configured
- + with the "depth" argument of the `contents directive`_, or
+ + with the ``depth`` option of the `contents directive`_, or
+ in a style sheet with e.g. ``\setcounter{tocdepth}{5}``.
@@ -1735,7 +1733,7 @@
.. note::
Minitoc supports local ToCs only at "part" and top section level
- ("chapter" or "section"). Local `contents` directives at lower levels
+ ("chapter" or "section"). Local "contents" directives at lower levels
are ignored (a warning is issued).
This is an intended feature of the minitoc_ package. If you really
@@ -2141,7 +2139,7 @@
```````````````````````
Initially both were implemented using figure floats, because hyperlinking
-back and forth seemed to be impossible. Later the `figure` directive was
+back and forth seemed to be impossible. Later the `figure directive`_ was
added that puts images into figure floats.
This results in footnotes, citations, and figures possibly being mixed at
@@ -2158,6 +2156,7 @@
group, i.e. ``[cite1]_ [cite2]_`` results in ``\cite{cite1,cite2}``.
The appearance in the output can be configured in a `style sheet`_.
+.. _figure directive: ../ref/rst/directives.html#figure
.. _use_latex_citations: config.html#use-latex-citations
@@ -2193,5 +2192,5 @@
* Pdfbookmark level 4 (and greater) does not work (might be settable but
complicated).
-* Hyperlinks are not hyphenated; this leads to bad spacing. See
- docs/user/rst/demo.rst 2.14 directives.
+* Hyperlinks are not hyphenated; this leads to bad spacing.
+ See ``docs/user/rst/demo.rst`` section 2.14 "directives".
Modified: trunk/docutils/docutils/nodes.py
===================================================================
--- trunk/docutils/docutils/nodes.py 2025-07-11 12:41:40 UTC (rev 10184)
+++ trunk/docutils/docutils/nodes.py 2025-07-28 20:10:46 UTC (rev 10185)
@@ -1911,6 +1911,9 @@
.. [#] Do not clear the name-to-id map or invalidate the old target if
both old and new targets refer to identical URIs or reference names.
The new target is invalidated regardless.
+
+ Provisional. There will be changes to prefer explicit reference names
+ as base for an element's ID.
"""
for name in tuple(node['names']):
if name in self.nameids:
@@ -1989,6 +1992,9 @@
# "note" here is an imperative verb: "take note of".
def note_implicit_target(
self, target: Element, msgnode: Element | None = None) -> None:
+ # TODO: Postpone ID creation. Register reference name instead of ID
+ # to allow for IDs based on explicit target pointing to the same
+ # element. https://github.com/sphinx-doc/sphinx/issues/1961
id = self.set_id(target, msgnode)
self.set_name_id_map(target, id, msgnode, explicit=False)
Modified: trunk/docutils/docutils/writers/_html_base.py
===================================================================
--- trunk/docutils/docutils/writers/_html_base.py 2025-07-11 12:41:40 UTC (rev 10184)
+++ trunk/docutils/docutils/writers/_html_base.py 2025-07-28 20:10:46 UTC (rev 10185)
@@ -448,6 +448,8 @@
def read_size_with_PIL(self, node) -> tuple[int, int] | None:
# Try reading size from image file.
# Internal auxiliary method called from `self.image_size()`.
+ # TODO: use https://github.com/shibukawa/imagesize_py
+ # faster, also handles SVG, attention: bug
reading_problems = []
uri = node['uri']
if not PIL:
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
