SF.net SVN: docutils:[9992] trunk/docutils/docs

Revision: 9992
          http://sourceforge.net/p/docutils/code/9992
Author:   milde
Date:     2024-12-03 13:12:26 +0000 (Tue, 03 Dec 2024)
Log Message:
-----------
Documentation fixes

Add crosslinks from related directives to "root_prefix" setting.

The "loading" directive option and "image_loading" setting work with figures, too.

Update config file syntax quote.
Move some hyperlink targets to the "references" section.

Modified Paths:
--------------
    trunk/docutils/docs/ref/doctree.rst
    trunk/docutils/docs/ref/rst/directives.rst
    trunk/docutils/docs/user/config.rst

Modified: trunk/docutils/docs/ref/doctree.rst
===================================================================
--- trunk/docutils/docs/ref/doctree.rst	2024-11-25 20:45:27 UTC (rev 9991)
+++ trunk/docutils/docs/ref/doctree.rst	2024-12-03 13:12:26 UTC (rev 9992)
@@ -4194,8 +4194,8 @@
 Attribute type: EnumeratedType_, one of "embed", "link", or "lazy".
 Default value: none.
 
-The ``loading`` attribute is used in the `\<image>`_ element to
-indicate the preferred handling by the Docutils writer_. [#]_
+The ``loading`` attribute is used in the `\<image>`_ and `\<figure>`_
+elements to indicate the preferred handling by the Docutils writer_. [#]_
 The default depends on the writer and the image_loading_
 configuration setting.
 

Modified: trunk/docutils/docs/ref/rst/directives.rst
===================================================================
--- trunk/docutils/docs/ref/rst/directives.rst	2024-11-25 20:45:27 UTC (rev 9991)
+++ trunk/docutils/docs/ref/rst/directives.rst	2024-12-03 13:12:26 UTC (rev 9992)
@@ -275,6 +275,8 @@
     option is also specified, they are combined.  For example, a height of
     200px and a scale of 50 is equivalent to a height of 100px with no scale.
 
+    .. _loading:
+
 ``loading`` : "embed", "link", or "lazy"
     Set the `loading attribute`_ to indicate the
     preferred handling by the Docutils Writer. [#]_
@@ -912,7 +914,7 @@
 :Directive Options: `see below <csv-table options_>`__
 :Directive Content: A CSV (comma-separated values) table
                     or (with the `file`_ or `url`_ options) none.
-:Configuration Settings: table_style_, file_insertion_enabled_
+:Configuration Settings: table_style_, file_insertion_enabled_, root_prefix_
 
 .. WARNING::
 
@@ -1529,7 +1531,7 @@
 :Directive Arguments: one, required (path_ to the file to include)
 :Directive Options: `see below <include options_>`__
 :Directive Content: none
-:Configuration Setting: file_insertion_enabled_
+:Configuration Setting: file_insertion_enabled_, root_prefix_
 
 .. WARNING::
 
@@ -1645,7 +1647,7 @@
 :Directive Options: `see below <raw options_>`__
 :Directive Content: Stored verbatim, uninterpreted.
                     None (empty) if a ``file`` or ``url`` option given.
-:Configuration Settings: raw_enabled_, file_insertion_enabled_
+:Configuration Settings: raw_enabled_, file_insertion_enabled_, root_prefix_
 
 .. WARNING::
 

Modified: trunk/docutils/docs/user/config.rst
===================================================================
--- trunk/docutils/docs/user/config.rst	2024-11-25 20:45:27 UTC (rev 9991)
+++ trunk/docutils/docs/user/config.rst	2024-12-03 13:12:26 UTC (rev 9992)
@@ -89,17 +89,19 @@
 
 Configuration files are UTF-8-encoded text files.  The ConfigParser.py_
 module from Python_'s standard library is used to read them.
-From its documentation:
+From its documentation__:
 
-    The configuration file consists of sections, lead by a "[section]"
-    header and followed by "name: value" entries, with continuations
-    in the style of `RFC 822`_; "name=value" is also accepted.  Note
-    that leading whitespace is removed from values.  ...  Lines
-    beginning with "#" or ";" are ignored and may be used to provide
-    comments.
 
-.. Note:: No format string interpolation is done.
+    A configuration file consists of sections, each led by a ``[section]``
+    header, followed by key/value entries separated by a specific string
+    (``=`` or ``:`` by default).
+    […] Leading and trailing whitespace is removed from keys and values.
+    […] Configuration files may include comments, prefixed by specific
+    characters (``#`` and ``;`` by default).
 
+__ https://docs.python.org/3/library/configparser.html
+   #supported-ini-file-structure
+
 The following conventions apply to Docutils configuration files:
 
 * Configuration file **entry names** correspond to internal `runtime
@@ -139,7 +141,11 @@
 
       expose_internals: source:line
 
+* No `format string interpolation`__ is done.
 
+__ https://docs.python.org/3/library/configparser.html#interpolation-of-values
+
+
 Example
 ~~~~~~~
 
@@ -464,9 +470,7 @@
 
 *Default*: "en" (English).  *Options*: ``--language``, ``-l``.
 
-.. _class attribute: ../ref/doctree.html#classes
 
-
 output
 ------
 
@@ -696,9 +700,7 @@
 :Default: None (the displayed `document title`_).
 :Option:  ``--title``.
 
-.. _title attribute: ../ref/doctree.html#title-attribute
 
-
 toc_backlinks
 -------------
 
@@ -1471,8 +1473,10 @@
 image_loading
 """""""""""""
 Indicate at which point images should be loaded.
-Overridden by the `"image" directive`_'s ``:loading:`` option.
 
+Overridden by the `"loading"`_ option of the `"image"`_ and `"figure"`_
+directives.
+
 Supported values:
 
 :embed: Embed still images into the HTML document
@@ -2504,6 +2508,9 @@
 .. _Docutils Generic document type definition:
 .. _Docutils Document Tree:
 .. _Document Tree: ../ref/doctree.html
+.. _class attribute: ../ref/doctree.html#classes
+.. _title attribute: ../ref/doctree.html#title-attribute
+.. _"uri" attribute: ../ref/doctree.html#uri
 
 .. _Docutils Runtime Settings:
 .. _runtime settings: ../api/runtime-settings.html
@@ -2520,8 +2527,10 @@
 .. _"class" directive: ../ref/rst/directives.html#class
 .. _"code": ../ref/rst/directives.html#code
 .. _"csv-table": ../ref/rst/directives.html#csv-table
-.. _"image" directive: ../ref/rst/directives.html#image
+.. _"figure": ../ref/rst/directives.html#figure
+.. _"image": ../ref/rst/directives.html#image
 .. _"include": ../ref/rst/directives.html#include
+.. _"loading": ../ref/rst/directives.html#loading
 .. _"math" directive: ../ref/rst/directives.html#math
 .. _"parsed-literal": ../ref/rst/directives.html#parsed-literal
 .. _"raw":

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