Menu
▾
▴
[Docutils-checkins] SF.net SVN: docutils:[10272] trunk/docutils
|
From: <mi...@us...> - 2025-12-14 13:21:02
|
Revision: 10272
http://sourceforge.net/p/docutils/code/10272
Author: milde
Date: 2025-12-14 13:20:59 +0000 (Sun, 14 Dec 2025)
Log Message:
-----------
Documentation update
Announce change to "ids" handling in case of a name conflict between
explicit and implicit targets.
Update security howto.
Add hyperlink target for the description of the special syntax for
Standard Definition Files in the "include" directive documentation.
Small fixes and additions to documentation and comments.
Modified Paths:
--------------
trunk/docutils/RELEASE-NOTES.rst
trunk/docutils/docs/howto/security.rst
trunk/docutils/docs/index.rst
trunk/docutils/docs/ref/rst/directives.rst
trunk/docutils/docutils/nodes.py
trunk/docutils/docutils/utils/urischemes.py
trunk/docutils/docutils/writers/_html_base.py
Modified: trunk/docutils/RELEASE-NOTES.rst
===================================================================
--- trunk/docutils/RELEASE-NOTES.rst 2025-12-14 11:03:06 UTC (rev 10271)
+++ trunk/docutils/RELEASE-NOTES.rst 2025-12-14 13:20:59 UTC (rev 10272)
@@ -75,6 +75,11 @@
<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
-------
@@ -291,7 +296,8 @@
Release 0.22.4b1 (unpublished)
==============================
-.
+HTML writers:
+ - New value "auto" for the initial_header_level_ setting.
Release 0.22.3 (2025-11-06)
Modified: trunk/docutils/docs/howto/security.rst
===================================================================
--- trunk/docutils/docs/howto/security.rst 2025-12-14 11:03:06 UTC (rev 10271)
+++ trunk/docutils/docs/howto/security.rst 2025-12-14 13:20:59 UTC (rev 10272)
@@ -42,26 +42,26 @@
* Files may be **written to any location** accessible to the process.
* There are **no restrictions to** the **file names**.
-Special care must be taken when allowing users to configure the *output
-destination* or the `warning_stream`_, `record_dependencies`_, or
-`_destination`_ settings.
+Special care must be taken when allowing users to configure the `output`_
+(or `_destination`_), `warning_stream`_, or `record_dependencies`_ settings.
+.. _output: ../user/config.html#output
+.. _`_destination`: ../user/config.html#destination
.. _warning_stream: ../user/config.html#warning-stream
.. _record_dependencies: ../user/config.html#record-dependencies
-.. _`_destination`: ../user/config.html#destination
External Data Insertion
-----------------------
-There are several `reStructuredText directives`_ that can insert
-external data (files and URLs) into the output document. These
-directives are:
+There are several `reStructuredText directives`_ that can insert external
+data (files or content fetched from a URL) into the output document.
+These directives are:
* "include_", by its very nature,
* "raw_", through its ``:file:`` and ``:url:`` options,
* "csv-table_", through its ``:file:`` and ``:url:`` options,
-* "image_", if `embed_images`_ is true.
+* "image_" through its ``:loading:`` option.
The "include_" directive and the other directives' file insertion
features can be disabled by setting "file_insertion_enabled_" to
@@ -70,7 +70,7 @@
__ ../user/config.html#configuration-file-syntax
.. _reStructuredText directives: ../ref/rst/directives.html
.. _include: ../ref/rst/directives.html#include
-.. _raw: ../ref/rst/directives.html#raw-directive
+.. _raw: ../ref/rst/directives.html#raw
.. _csv-table: ../ref/rst/directives.html#csv-table
.. _image: ../ref/rst/directives.html#image
.. _embed_images: ../user/config.html#embed-images
@@ -80,15 +80,19 @@
Raw HTML Insertion
------------------
-The "raw_" directive is intended for the insertion of
-non-reStructuredText data that is passed untouched to the Writer.
-This directive can be abused to bypass site features or insert
-malicious JavaScript code into a web page. The "raw_" directive can
-be disabled by setting "raw_enabled_" to "false".
+Content of the "raw_" directive is passed untouched to the Writer.
+Docutils standard writers insert "raw" content with matching
+format_ into the output document without any checks or changes.
+This can be abused to bypass site features or insert malicious
+script code into a web page.
+A web-secure Writer must ignore or sanitize "raw" content.
+Alternatively, the "raw" directive can be disabled by setting
+"raw_enabled_" to "false".
+
.. _raw_enabled: ../user/config.html#raw-enabled
+.. _format: ../ref/doctree.html#format
-
CPU and memory utilization
--------------------------
Modified: trunk/docutils/docs/index.rst
===================================================================
--- trunk/docutils/docs/index.rst 2025-12-14 11:03:06 UTC (rev 10271)
+++ trunk/docutils/docs/index.rst 2025-12-14 13:20:59 UTC (rev 10272)
@@ -126,7 +126,7 @@
become reference material. Successful specs evolve into refs.
Docutils-general:
- * `The Docutils Document Tree <ref/doctree.html>`__ (incomplete)
+ * `The Docutils Document Tree <ref/doctree.html>`__
* `Docutils Generic DTD <ref/docutils.dtd>`__
* `OASIS XML Exchange Table Model Declaration Module
<ref/soextblx.dtd>`__ (CALS tables DTD module)
Modified: trunk/docutils/docs/ref/rst/directives.rst
===================================================================
--- trunk/docutils/docs/ref/rst/directives.rst 2025-12-14 11:03:06 UTC (rev 10271)
+++ trunk/docutils/docs/ref/rst/directives.rst 2025-12-14 13:20:59 UTC (rev 10272)
@@ -1627,11 +1627,14 @@
If an included document fragment contains section structure, the title
adornments must match those of the master document.
-Standard data files intended for inclusion in reStructuredText
-documents are distributed with the Docutils source code, located in
+.. _include Standard Definition files:
+
+`reStructuredText Standard Definition Files`_
+intended for inclusion in reStructuredText documents
+are distributed with the Docutils source code, located in
the "docutils" package in the ``docutils/parsers/rst/include``
-directory. To access these files, use the special syntax for standard
-"include" data files, angle brackets around the file name::
+directory. To access these files, use the *special syntax for standard
+definition files*: angle brackets around the file name, e.g. ::
.. include:: <isonum.txt>
Modified: trunk/docutils/docutils/nodes.py
===================================================================
--- trunk/docutils/docutils/nodes.py 2025-12-14 11:03:06 UTC (rev 10271)
+++ trunk/docutils/docutils/nodes.py 2025-12-14 13:20:59 UTC (rev 10272)
@@ -1995,14 +1995,14 @@
# "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
+ # TODO: Postpone ID creation and register reference name instead of ID?
id = self.set_id(target, msgnode)
self.set_name_id_map(target, id, msgnode, explicit=False)
def note_explicit_target(
self, target: Element, msgnode: Element | None = None) -> None:
+ # TODO: if the id matching the name is applied to an implicid target,
+ # transfer it to this target and put a "disambiguated" id on the other.
id = self.set_id(target, msgnode)
self.set_name_id_map(target, id, msgnode, explicit=True)
Modified: trunk/docutils/docutils/utils/urischemes.py
===================================================================
--- trunk/docutils/docutils/utils/urischemes.py 2025-12-14 11:03:06 UTC (rev 10271)
+++ trunk/docutils/docutils/utils/urischemes.py 2025-12-14 13:20:59 UTC (rev 10272)
@@ -35,7 +35,7 @@
'(facsimiles); RFC 2806',
'feed': 'NetNewsWire feed',
'file': 'Host-specific file names; RFC 1738',
- 'finger': '',
+ 'finger': 'Querying user information using the Finger protocol',
'freenet': '',
'ftp': 'File Transfer Protocol; RFC 1738',
'go': 'go; RFC 3368',
@@ -99,7 +99,7 @@
'rx': 'Remote Execution',
'sdp': '',
'service': 'service location; RFC 2609',
- 'shttp': 'secure hypertext transfer protocol',
+ 'shttp': 'secure hypertext transfer protocol (OBSOLETE)',
'sip': 'Session Initiation Protocol; RFC 3261',
'sips': 'secure session intitiaion protocol; RFC 3261',
'smb': 'SAMBA filesystems.',
@@ -124,7 +124,7 @@
'urn': 'Uniform Resource Name; RFC 2141',
'uuid': '',
'vemmi': 'versatile multimedia interface; RFC 2122',
- 'videotex': '',
+ 'videotex': 'videotex (historical)',
'view-source': 'displays HTML code that was generated with JavaScript',
'wais': 'Wide Area Information Servers; RFC 4156',
'whodp': '',
Modified: trunk/docutils/docutils/writers/_html_base.py
===================================================================
--- trunk/docutils/docutils/writers/_html_base.py 2025-12-14 11:03:06 UTC (rev 10271)
+++ trunk/docutils/docutils/writers/_html_base.py 2025-12-14 13:20:59 UTC (rev 10272)
@@ -637,6 +637,9 @@
return
child['classes'].append(class_)
+ # Visitor methods
+ # ---------------
+
def visit_Text(self, node) -> None:
text = node.astext()
encoded = self.encode(text)
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|