SF.net SVN: docutils:[10266 ] trunk/docutils
milde--- via Docutils-checkins <[email protected]> Fri, 28 Nov 2025 13:52:10 +0000
| Newsgroups | gmane.text.docutils.cvs |
|---|---|
| Message-ID | <[email protected]> |
Revision: 10266
http://sourceforge.net/p/docutils/code/10266
Author: milde
Date: 2025-11-28 13:52:09 +0000 (Fri, 28 Nov 2025)
Log Message:
-----------
Documentation update and fixes.
Announce upcoming changes.
The "raw" directive can be used in substitution definitions.
Hide documentation for deprecated "line-block" directive in a
details/disclosure list.
Small edits for improved clarity.
Modified Paths:
--------------
trunk/docutils/RELEASE-NOTES.rst
trunk/docutils/docs/ref/doctree.rst
trunk/docutils/docs/ref/rst/directives.rst
trunk/docutils/docs/ref/rst/restructuredtext.rst
trunk/docutils/docs/user/config.rst
trunk/docutils/docs/user/rst/demo.rst
trunk/docutils/docutils/writers/html5_polyglot/__init__.py
trunk/docutils/docutils/writers/latex2e/__init__.py
Modified: trunk/docutils/RELEASE-NOTES.rst
===================================================================
--- trunk/docutils/RELEASE-NOTES.rst 2025-11-28 13:51:57 UTC (rev 10265)
+++ trunk/docutils/RELEASE-NOTES.rst 2025-11-28 13:52:09 UTC (rev 10266)
@@ -56,9 +56,6 @@
* The <footnote> element's first child (<label>) will become mandatory
in Docutils 1.0.
-* The "rst" parser will warn if a `"figure"`_ directive is missing both
- caption and legend in Docutils 1.0.
-
* Inline `\<target>`_ elements and <target> elements with content will be
deprecated in Docutils 1.0 and invalid in Docutils 2.0.
The "rst" parser will use <inline> elements for inline targets
@@ -74,6 +71,15 @@
The rST parser will handle a `doctest block`_ similar to a "code" directive
with language "pycon" (Python console) and generate a <literal_block>.
+Parsers
+-------
+
+* The "rst" parser will warn, if a directive that does not take arguments
+ has content above and below directive options in Docutils 0.23.
+
+* The "rst" parser will warn if a `"figure"`_ directive is missing both
+ caption and legend in Docutils 1.0.
+
Writers
-------
@@ -93,6 +99,11 @@
* "html5" writer:
+ - If a section title has several IDs, use the last one (from the first
+ `explicit target`__) as self-link_ in Docutils 0.23.
+
+ __ docs/ref/rst/restructuredtext.html#explicit-hyperlink-targets
+
- Move attribution behind the blockquote to comply with the
`"HTML living standard"`__ [#]_ and adapt CSS stylesheets
in Docutils 1.0.
@@ -107,8 +118,9 @@
* "latex2e" writer:
- - Only write ``\label`` commands for IDs that are referenced in the
- current document in Docutils 0.23.
+ - Only write ``\label`` commands for explicit IDs and IDs that are
+ referenced in the current document (i.e. not for un-referenced
+ section titles) in Docutils 0.23.
- Change default of use_latex_citations_ setting to True
in Docutils 1.0.
@@ -1560,6 +1572,7 @@
.. _output_path: docs/user/config.html#output-path
.. _reference_label: docs/user/config.html#reference-label
.. _root_prefix: docs/user/config.html#root-prefix
+.. _self-link: docs/user/config.html#section-self-link
.. _SmartQuotes: docs/user/config.html#smart-quotes
.. _sources: docs/user/config.html#sources
.. _use_latex_citations: docs/user/config.html#use-latex-citations
Modified: trunk/docutils/docs/ref/doctree.rst
===================================================================
--- trunk/docutils/docs/ref/doctree.rst 2025-11-28 13:51:57 UTC (rev 10265)
+++ trunk/docutils/docs/ref/doctree.rst 2025-11-28 13:52:09 UTC (rev 10266)
@@ -3854,8 +3854,9 @@
:Children: one or more `body elements`_
:Attributes: backrefs_, level_, line_, type_, and the `common attributes`_.
-In Docutils, the generation of system messages can be configured with the
-`"report_level"`_ setting.
+In Docutils, system messages with a level lower than the
+`"report_level"`_ setting are removed by the `universal.FilterMessages`
+transform_.
Examples
--------
@@ -4249,8 +4250,9 @@
:Category: `Structural Elements`_
-:Analogues: <topic> is analogous to the DocBook_ <simplesect> element
- and the HTML_ <aside> element.
+:Analogues: <topic> is analogous to the HTML_ <aside> element.
+ The DocBook_ <simplesect> element is similar, but you cannot
+ place `body elements`_ after a <simplesect>.
:Processing: A <topic> element should be set off from the rest of the
document somehow, such as with indentation or a border.
@@ -5794,7 +5796,7 @@
.. _namespace:
Almost all elements in a document share a common *namespace*
- for reference names, comparison ignores case.
+ for reference names and match them ignoring case.
Only `\<substitution_definition>`_ and `\<substitution_reference>`_
elements use a distinct namespace with `case-sensitive but forgiving`_
matching of reference names.
Modified: trunk/docutils/docs/ref/rst/directives.rst
===================================================================
--- trunk/docutils/docs/ref/rst/directives.rst 2025-11-28 13:51:57 UTC (rev 10265)
+++ trunk/docutils/docs/ref/rst/directives.rst 2025-11-28 13:52:09 UTC (rev 10266)
@@ -453,8 +453,8 @@
A topic is like a block quote with a title, or a self-contained
section with no subsections. Use the "topic" directive to indicate a
self-contained idea that is separate from the flow of the document.
-Topics may occur anywhere a section or transition may occur and
-in sidebars. Body elements and topics may not contain nested topics.
+Topics may be nested in the document, a section, or a
+sidebar_. Body elements and topics may not contain topics.
The directive's sole argument is interpreted as the topic title; the
next line must be blank. All subsequent lines make up the topic body,
@@ -511,13 +511,6 @@
Line Block
==========
-.. admonition:: Deprecated
-
- The "line-block" directive is deprecated. Use the `line block
- syntax`_ instead.
-
- .. _line block syntax: restructuredtext.html#line-blocks
-
.. class:: field-indent-13em
:Directive Type: "line-block"
@@ -526,28 +519,31 @@
:Directive Options: `class <class option_>`_, name_
:Directive Content: Becomes the body of the line block.
-The "line-block" directive constructs an element where line breaks and
-initial indentation is significant and inline markup is supported. It
-is equivalent to a `parsed literal block`_ with different rendering:
-typically in an ordinary serif typeface instead of a
-typewriter/monospaced face, and not automatically indented. (Have the
-line-block directive begin a block quote to get an indented line
-block.) Line blocks are useful for address blocks and verse (poetry,
-song lyrics), where the structure of lines is significant. For
-example, here's a classic::
+.. class:: details
- "To Ma Own Beloved Lassie: A Poem on her 17th Birthday", by
- Ewan McTeagle (for Lassie O'Shea):
+**Deprecated.** Use the `line block syntax`_ instead.
+ The "line-block" directive constructs an element where line breaks and
+ initial indentation is significant and inline markup is supported. It
+ is comparable to a `parsed literal block`_ with different rendering:
+ typically in an ordinary serif typeface instead of a
+ typewriter/monospaced face, and not automatically indented. (Have the
+ line-block directive begin a block quote to get an indented line
+ block.) Line blocks are useful for address blocks and verse (poetry,
+ song lyrics), where the structure of lines is significant. For
+ example, here's a classic::
- .. line-block::
+ "To Ma Own Beloved Lassie: A Poem on her 17th Birthday", by
+ Ewan McTeagle (for Lassie O'Shea):
- Lend us a couple of bob till Thursday.
- I'm absolutely skint.
- But I'm expecting a postal order and I can pay you back
- as soon as it comes.
- Love, Ewan.
+ .. line-block::
+ Lend us a couple of bob till Thursday.
+ I'm absolutely skint.
+ But I'm expecting a postal order and I can pay you back
+ as soon as it comes.
+ Love, Ewan.
+
.. _parsed-literal:
Parsed Literal Block
@@ -1171,9 +1167,9 @@
:Directive Content: none
:Configuration Settings: toc_backlinks_, use_latex_toc_, generate_oowriter_toc_
-The "contents" directive generates a table of contents (TOC) in
+The "contents" directive generates a table of contents (ToC) in
a `\<topic>`_ element. Topics, and therefore tables of contents,
-may occur anywhere a section or transition may occur and in sidebars.
+may be nested in the document, a section, or a sidebar_.
Body elements and topics may not contain tables of contents.
Here's the directive in its simplest form::
@@ -1284,6 +1280,8 @@
Document Header & Footer
========================
+.. class:: field-indent-13em
+
:Directive Types: "header" and "footer"
:Doctree Elements: `\<decoration>`_, `\<header>`_, `\<footer>`_
:Directive Arguments: none
@@ -1411,18 +1409,13 @@
Directives for Substitution Definitions
-----------------------------------------
-The directives introduced in this section may be used in
-`substitution definitions`_. They may not be used directly,
-in standalone context (except for the image_ directive).
+This section lists directives that may be used in `substitution definitions`_.
-.. _substitution definitions:
-.. _substitution definition: restructuredtext.html#substitution-definitions
-
Inline Images
=============
-The `image`_ directive can be used both, stand-alone (to define
+The "`image`_" directive can be used both, stand-alone (to define
block-level images) and in substitution definitions to define
inline images. [#no-inline-name]_
@@ -1430,6 +1423,15 @@
a substitution definition. [#substitution-limits]_
+Inline Raw
+==========
+
+The "raw_" directive can be used stand-alone and in substitution definitions.
+
+"Raw data pass-through" in inline context is also possible with
+a `custom role`_ derived from the `"raw" role`_.
+
+
.. _replace:
Replacement Text
@@ -1464,10 +1466,11 @@
.. |Python| replace:: Python, *the* best language around
.. _Python: https://www.python.org/
-.. [#substitution-limits] As a substitution may be referenced more than
- one time, a substitution definition may not contain references to
- `anonymous hyperlinks`_, `auto-numbered`_ or `auto-symbol`_ footnotes
- and no `hyperlink targets`__ (names and identifiers must be unique).
+.. [#substitution-limits]
+ A substitution definition may not contain references to `anonymous
+ hyperlinks`_, `auto-numbered`_ or `auto-symbol`_ footnotes and no
+ `hyperlink targets`__ because a substitution may be referenced more
+ than once but names and identifiers must be unique.
__ restructuredtext.html#inline-internal-targets
@@ -1768,6 +1771,8 @@
Inline equivalents of the "raw" directive can be defined via
`custom interpreted text roles`_ derived from the `"raw" role`_.
+The "raw" directive can also be used directly in a `substitution
+definition`_.
.. _raw options:
@@ -1788,8 +1793,8 @@
.. _class directive:
.. _rst-class:
-Class
-=====
+Setting Class Attributes
+========================
.. class:: field-indent-13em
@@ -1949,6 +1954,7 @@
.. _role:
+.. _custom role:
Custom Interpreted Text Roles
=============================
@@ -2342,10 +2348,13 @@
.. _hyperlink references: restructuredtext.html#hyperlink-references
.. _hyperlink targets:
.. _hyperlink target: restructuredtext.html#hyperlink-targets
+.. _line block syntax: restructuredtext.html#line-blocks
.. _reference name:
.. _reference names: restructuredtext.html#reference-names
.. _section title style hierarchy: restructuredtext.html#title-styles
.. _simple table: restructuredtext.html#simple-tables
+.. _substitution definitions:
+.. _substitution definition: restructuredtext.html#substitution-definitions
.. _supported length units: restructuredtext.html#length-units
.. _reStructuredText Interpreted Text Roles:
Modified: trunk/docutils/docs/ref/rst/restructuredtext.rst
===================================================================
--- trunk/docutils/docs/ref/rst/restructuredtext.rst 2025-11-28 13:51:57 UTC (rev 10265)
+++ trunk/docutils/docs/ref/rst/restructuredtext.rst 2025-11-28 13:52:09 UTC (rev 10266)
@@ -88,7 +88,7 @@
1. This is an enumerated list.
- 2. Enumerators may be arabic numbers, letters, or roman
+ 2. Enumerators may be arabic numerals, letters, or roman
numerals.
3. `Definition lists`_::
@@ -204,7 +204,7 @@
- Comments_::
- .. Comments begin with two dots and a space. Anything may
+ .. Comments begin with two dots and whitespace. Anything may
follow, except for the syntax of footnotes/citations,
hyperlink targets, directives, or substitution definitions.
@@ -359,7 +359,7 @@
itself. (A literal backslash can be specified by two backslashes in a
row -- the first backslash escapes the second. [#caveat]_)
-* Escaped whitespace characters are removed from the output document
+* _`Escaped whitespace` characters are removed from the output document
together with the escaping backslash. This allows for `character-level
inline markup`_.
@@ -743,7 +743,7 @@
Enumerated lists (a.k.a. "ordered" lists) are similar to bullet lists,
but use enumerators instead of bullets. An enumerator consists of an
enumeration sequence member and formatting, followed by whitespace.
-The following enumeration sequences are recognized:
+The following *enumeration sequences* are recognized:
- arabic numerals: 1, 2, 3, ... (no upper limit).
- uppercase alphabet characters: A, B, C, ..., Z.
@@ -753,10 +753,10 @@
In addition, the auto-enumerator, ``#``, may be used to automatically
enumerate a list. Auto-enumerated lists may begin with explicit
-enumeration, which sets the sequence. Fully auto-enumerated lists use
-arabic numerals and begin with 1.
+enumeration, which sets the sequence and start value.
+Fully auto-enumerated lists use arabic numerals and begin with 1.
-The following formatting types are recognized:
+The following *formatting types* are recognized:
- suffixed with a period: ``1.``, ``A.``, ``a.``, ``I.``, ``i.``.
- surrounded by parentheses: ``(1)``, ``(A)``, ``(a)``, ``(I)``, ``(i)``.
@@ -1377,7 +1377,7 @@
-- Sherlock Holmes
-A block quote may end with an attribution: a text block beginning with
+A block quote may end with an _`attribution`: a paragraph beginning with
``--``, ``---``, or a true em-dash, flush left within the block quote. If
the attribution consists of multiple lines, the left edges of the
second and subsequent lines must align.
@@ -2299,9 +2299,14 @@
The following *inline-compatible directives* are implemented in Docutils:
+:`"date"`_: inserts the current local date.
+
:`"image"`_: can be used for block-level images as well as in a
substitution definition for `inline images`_.
+:`"raw"`_: can be used in block-level context as well as in a
+ substitution definition.
+
:`"replace"`_: allows simple macro substitution.
It also provides a workaround__ for the still missing support of
nested inline markup.
@@ -2310,8 +2315,6 @@
:`"unicode"`_: converts Unicode character codes to characters.
-:`"date"`_: inserts the current local date.
-
Applications may find other use cases for the substitution mechanism.
The following are ideas that have not been implemented in Docutils.
Modified: trunk/docutils/docs/user/config.rst
===================================================================
--- trunk/docutils/docs/user/config.rst 2025-11-28 13:51:57 UTC (rev 10265)
+++ trunk/docutils/docs/user/config.rst 2025-11-28 13:52:09 UTC (rev 10266)
@@ -1521,8 +1521,8 @@
section_self_link
"""""""""""""""""
-Append an empty anchor element with a ``href`` to the section to
-section headings. See ``responsive.css`` for an example how this can be
+Extend section headings with an empty <a> element with a ``href`` to
+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.
Modified: trunk/docutils/docs/user/rst/demo.rst
===================================================================
--- trunk/docutils/docs/user/rst/demo.rst 2025-11-28 13:51:57 UTC (rev 10265)
+++ trunk/docutils/docs/user/rst/demo.rst 2025-11-28 13:52:09 UTC (rev 10266)
@@ -546,7 +546,7 @@
Here's one:
-.. Comments begin with two dots and a space. Anything may
+.. Comments begin with two dots and whitespace. Anything may
follow, except for the syntax of footnotes, hyperlink
targets, directives, or substitution definitions.
Modified: trunk/docutils/docutils/writers/html5_polyglot/__init__.py
===================================================================
--- trunk/docutils/docutils/writers/html5_polyglot/__init__.py 2025-11-28 13:51:57 UTC (rev 10265)
+++ trunk/docutils/docutils/writers/html5_polyglot/__init__.py 2025-11-28 13:52:09 UTC (rev 10266)
@@ -388,6 +388,8 @@
def section_title_tags(self, node):
start_tag, close_tag = super().section_title_tags(node)
ids = node.parent['ids']
+ # TODO: use ``ids[-1]``
+ # (IDs from explicit targets are appended to the implicit ID)
if (ids and getattr(self.settings, 'section_self_link', None)
and not isinstance(node.parent, nodes.document)):
self_link = ('<a class="self-link" title="link to this section"'
Modified: trunk/docutils/docutils/writers/latex2e/__init__.py
===================================================================
--- trunk/docutils/docutils/writers/latex2e/__init__.py 2025-11-28 13:51:57 UTC (rev 10265)
+++ trunk/docutils/docutils/writers/latex2e/__init__.py 2025-11-28 13:52:09 UTC (rev 10266)
@@ -2600,23 +2600,21 @@
self.depart_inline(node)
self.out.append('}')
- # Literal blocks are used for '::'-prefixed literal-indented
- # blocks of text, where the inline markup is not recognized,
- # but are also the product of the "parsed-literal" directive,
- # where the markup is respected.
+ # <literal_block> elements are used
+ # for literal blocks (where content is not parsed),
+ # for the "code" directive (where content may be parsed by Pygments), and
+ # for the "parsed-literal" directive (where rST inline markup is parsed).
#
- # In both cases, we want to use a typewriter/monospaced typeface.
- # For "real" literal-blocks, we can use \verbatim, while for all
- # the others we must use \ttfamily and \raggedright.
+ # In all cases, we want to use a monospaced typeface.
+ # If the <literal_block> contains only text, we can use a "verbatim-like"
+ # environment, for mixed content we must use \ttfamily and \raggedright.
#
- # We can distinguish between the two kinds by the number of
- # siblings that compose this node: if it is composed by a
- # single element, it's either
- # * a real one,
- # * a parsed-literal that does not contain any markup, or
- # * a parsed-literal containing just one markup construct.
+ # We can distinguish between the use cases looking at the element's
+ # children: if there is a single <Text> child, it is either
+ # * a "real" literal block or
+ # * a parsed-literal that does not contain any markup.
def is_plaintext(self, node):
- """Check whether a node can be typeset verbatim"""
+ """Check whether `node` contains only text"""
return (len(node) == 1) and isinstance(node[0], nodes.Text)
def visit_literal_block(self, node) -> None:
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