SF.net SVN: docutils:[10214 ] trunk/docutils

Revision: 10214
          http://sourceforge.net/p/docutils/code/10214
Author:   milde
Date:     2025-08-20 09:39:58 +0000 (Wed, 20 Aug 2025)
Log Message:
-----------
Documentation fixes.

Fix docstring: `directives.misc.Include.insert_into_input_lines()`
returns None. (The empty list is returned by `Include.run()`.)

Small edits in the Document Tree Guide.

Modified Paths:
--------------
    trunk/docutils/docs/ref/doctree.rst
    trunk/docutils/docutils/parsers/rst/directives/misc.py

Modified: trunk/docutils/docs/ref/doctree.rst
===================================================================
--- trunk/docutils/docs/ref/doctree.rst	2025-08-20 08:32:28 UTC (rev 10213)
+++ trunk/docutils/docs/ref/doctree.rst	2025-08-20 09:39:58 UTC (rev 10214)
@@ -4385,8 +4385,8 @@
 The ``auto`` attribute is used to indicate automatically-numbered
 `\<footnote>`_, `\<footnote_reference>`_ and `\<title>`_ elements
 (via the `%auto.att`_ parameter entity).
-In <footnote> and <footnote_reference> elements, it also carries information
-about the label type: "1": auto-numbered_, "*": auto-symbol_.
+In `\<footnote>`_ and `\<footnote_reference>`_ elements, it also carries
+information about the label type ("1": auto-numbered_, "*": auto-symbol_).
 
 
 ``backrefs``
@@ -4925,11 +4925,14 @@
 The ``title`` attribute is used in the `\<document>`_ element to store the
 document's *metadata title*.
 
-It is set by the `"title" directive`_ or the `DocTitle transform`_.
-This title is typically not part of the rendered document.
-It is, for example, used as `HTML <title> element`_ and shown in a
-browser's title bar, in a user's history or bookmarks, or in search results.
+The attribute is set by the `"title" directive`_ or the
+`DocTitle transform`_.  It is typically not part of the rendered document
+but, for example, used as `HTML <title> element`_ and shown in a
+browser's title bar, a user's history or bookmarks, or search results.
 
+Its value may may differ from the *displayed title* which is stored in a
+`\<title>`_ element.
+
 .. _HTML <title> element:
     https://html.spec.whatwg.org/multipage/semantics.html#the-title-element
 

Modified: trunk/docutils/docutils/parsers/rst/directives/misc.py
===================================================================
--- trunk/docutils/docutils/parsers/rst/directives/misc.py	2025-08-20 08:32:28 UTC (rev 10213)
+++ trunk/docutils/docutils/parsers/rst/directives/misc.py	2025-08-20 09:39:58 UTC (rev 10214)
@@ -236,8 +236,6 @@
     def insert_into_input_lines(self, text: str) -> None:
         """Insert file content into the rST input of the calling parser.
 
-        Returns an empty list to comply with the API of `Directive.run()`.
-
         Provisional.
         """
         source = self.options['source']

This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.