[Docutils-checkins] SF.net SVN: docutils:[10253] trunk/docutils/docs

[<mi...@us...>]

Revision: 10253
          http://sourceforge.net/p/docutils/code/10253
Author:   milde
Date:     2025-10-06 12:29:47 +0000 (Mon, 06 Oct 2025)
Log Message:
-----------
Documentation update/fixes.

Describe intended behaviour and add cross-links to the related TODO list item
for possible future "footnotes" and "citation" directives.

Correct terms in "image" directive documentation.

Simple example for auto-nubered footnotes.

Modified Paths:
--------------
    trunk/docutils/docs/dev/todo.rst
    trunk/docutils/docs/ref/rst/directives.rst
    trunk/docutils/docs/ref/rst/restructuredtext.rst

Modified: trunk/docutils/docs/dev/todo.rst
===================================================================
--- trunk/docutils/docs/dev/todo.rst	2025-09-24 16:22:33 UTC (rev 10252)
+++ trunk/docutils/docs/dev/todo.rst	2025-10-06 12:29:47 UTC (rev 10253)
@@ -2030,7 +2030,7 @@
 
   Collect and move footnotes & citations to the end of a document or the
   place of a "footnotes" or "citations" directive
-  (see `<./ref/rst/directives.html>_`)
+  (see `<../ref/rst/directives.html#references>`_)
 
   Footnotes:
     Collect all footnotes that are referenced in the document before the

Modified: trunk/docutils/docs/ref/rst/directives.rst
===================================================================
--- trunk/docutils/docs/ref/rst/directives.rst	2025-09-24 16:22:33 UTC (rev 10252)
+++ trunk/docutils/docs/ref/rst/directives.rst	2025-10-06 12:29:47 UTC (rev 10253)
@@ -228,16 +228,17 @@
 
 A `URI reference`_ to the image source file is specified in the directive
 argument.  As with hyperlink targets, the image URI may begin on the
-same line as the explicit markup start and target name, or it may
+same line as the explicit markup start and directive name, or it may
 begin in an indented text block immediately following, with no
 intervening blank lines.  If there are multiple lines in the link
 block, they are stripped of leading and trailing whitespace and joined
 together.
 
-Optionally, the image link block may contain a flat field list, the
+Optionally, the image directive may contain a flat field list, the
 `image options`_.  For example::
 
-    .. image:: picture.jpeg
+    .. image::
+       https://example.com/images/picture.jpeg
        :height: 100px
        :width: 200 px
        :scale: 50 %
@@ -245,10 +246,9 @@
        :alt: alternate text
        :align: right
 
+`Inline images`_ can be defined with an "image" directive in a
+`substitution definition`_, e.g. ::
 
-*Inline images* can be defined with an "image" directive in a `substitution
-definition`_, e.g. ::
-
     |Red light| means stop, |green light| means go.
 
     .. |red light|    image:: red_light.png
@@ -277,6 +277,8 @@
     Alternate text: a short description of the image, displayed by
     applications that cannot display images, or spoken by applications
     for visually impaired users.
+    Defaults to the image URI or, in a `substitution definition`_ to the
+    substitution text.
 
 ``height`` : length_
     The desired height of the image.
@@ -1355,7 +1357,11 @@
 =========
 
 **NOT IMPLEMENTED YET**
+(`see todo item <../../dev/todo.html#footnote-citation-gathering>`_)
 
+Collect `footnotes <footnote_>`__ and move them to the place of this
+directive.
+
 .. class:: field-indent-13em
 
 :Directive Type: "footnotes"
@@ -1371,12 +1377,19 @@
 =========
 
 **NOT IMPLEMENTED YET**
+(`see todo item <../../dev/todo.html#footnote-citation-gathering>`_)
 
+Collect `citations <citation_>`__ or generate them for all
+`citation references`_ from a database [#]_ and move them
+to the place of this directive.
+
+.. [#] For example a BibTeX file (cf. the use_bibtex_ LaTeX writer setting).
+
 .. class:: field-indent-13em
 
 :Directive Type: "citations"
 :Doctree Elements: `\<pending>`_, `\<topic>`_
-:Directive Arguments: none?
+:Directive Arguments: optional (database)?
 :Directive Options: Possible?
 :Directive Content: none
 
@@ -1398,9 +1411,9 @@
  Directives for Substitution Definitions
 -----------------------------------------
 
-The directives introduced in this section may only be used in
+The directives introduced in this section may be used in
 `substitution definitions`_.  They may not be used directly,
-in standalone context.
+in standalone context (except for the image_ directive).
 
 .. _substitution definitions:
 .. _substitution definition: restructuredtext.html#substitution-definitions
@@ -2300,6 +2313,8 @@
 
 .. _reStructuredText Markup Specification: restructuredtext.html
 .. _block quote: restructuredtext.html#block-quotes
+.. _citation references: restructuredtext.html#citation-references
+.. _citation: restructuredtext.html#citations
 .. _comments: restructuredtext.html#comments
 .. _directives: restructuredtext.html#directives
 .. _document title: restructuredtext.html#document-title
@@ -2308,6 +2323,7 @@
 .. _external hyperlink target:
 .. _external hyperlink targets:
     restructuredtext.html#external-hyperlink-targets
+.. _footnote: restructuredtext.html#footnotes
 .. _grid table: restructuredtext.html#grid-tables
 .. _hyperlink reference:
 .. _hyperlink references: restructuredtext.html#hyperlink-references
@@ -2326,6 +2342,7 @@
 .. _"raw" role: roles.html#raw
 
 .. Docutils Configuration
+.. _use_bibtex: ../../user/config.html#use-bibtex
 .. _file_insertion_enabled: ../../user/config.html#file-insertion-enabled
 .. _generate_oowriter_toc: ../../user/config.html#generate-oowriter-toc
 .. _image_loading: ../../user/config.html#image-loading

Modified: trunk/docutils/docs/ref/rst/restructuredtext.rst
===================================================================
--- trunk/docutils/docs/ref/rst/restructuredtext.rst	2025-09-24 16:22:33 UTC (rev 10252)
+++ trunk/docutils/docs/ref/rst/restructuredtext.rst	2025-10-06 12:29:47 UTC (rev 10253)
@@ -1764,17 +1764,21 @@
 
 A number sign (``#``) may be used as the first character of a footnote
 label to request automatic numbering of the footnote or footnote
-reference.
+reference::
 
+    Footnotes may be auto-numbered. [#]_
+
+    .. [#] This is an auto-numbered footnote.
+
 The first footnote to request automatic numbering is assigned the
 label "1", the second is assigned the label "2", and so on (assuming
 there is no conflict with another reference name; see also
 `Mixed Manual and Auto-Numbered Footnotes`_ below).
-If the footnote label is a single ``#``, the assigned number is also used
-as reference name.
 
 .. _autonumber label:
 
+If the footnote label is a single ``#``, the assigned number is also used
+as reference name.
 A custom reference name can be specified appending a `simple reference
 name`_ to the number sign to form an *autonumber label*.
 For example::
@@ -2969,9 +2973,10 @@
 `footnote label`_ followed by a trailing underscore.
 For example::
 
-    Please RTFM [1]_.
+    Please RTFM [1]_. [#]_
 
     .. [1] Read The Fine Manual
+    .. [#] See "footnotes_" for the format of the *footnote label*.
 
 `Inline markup recognition rules`_ may require whitespace in front of the
 footnote reference. To remove the whitespace from the output, use an

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