SF.net SVN: docutils:[10271 ] trunk/docutils/docs/ref/ rst/restructuredtext.rst

Revision: 10271
          http://sourceforge.net/p/docutils/code/10271
Author:   milde
Date:     2025-12-14 11:03:06 +0000 (Sun, 14 Dec 2025)
Log Message:
-----------
Fix statement in rST Specification example.

The rST specification states in one example that
"A footnote contains body elements, consistently indented by at least 3 spaces."
The minimal indentation in rST is one space.

Fix the example.
Add more examples.
Sort.

Cf. https://stackoverflow.com/a/48313531/12090995
Fixes [bugs:#515]

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

Modified: trunk/docutils/docs/ref/rst/restructuredtext.rst
===================================================================
--- trunk/docutils/docs/ref/rst/restructuredtext.rst	2025-12-03 11:38:54 UTC (rev 10270)
+++ trunk/docutils/docs/ref/rst/restructuredtext.rst	2025-12-14 11:03:06 UTC (rev 10271)
@@ -179,8 +179,11 @@
   - Footnotes_::
 
         .. [1] A footnote contains body elements, consistently
-           indented by at least 3 spaces.
+         indented by at least 1 space.
 
+            The least indented line sets the reference
+            indentation, so this is a nested block quote.
+
   - Citations_::
 
         .. [CIT2002] Just like a footnote, except the label is
@@ -249,7 +252,19 @@
 Indentation
 -----------
 
-Indentation is used to indicate -- and is only significant in
+When a paragraph or other construct consists of more than one line of
+text, the lines must be left-aligned::
+
+    This is a paragraph.  The lines of
+    this paragraph are aligned at the left.
+
+        This paragraph has problems.  The
+    lines are not left-aligned.  In addition
+      to potential misinterpretation, warning
+        and/or error messages will be generated
+      by the parser.
+
+*Indentation* is used to indicate -- and is only significant in
 indicating -- block quotes, definitions (in `definition lists`_),
 and local nested content:
 
@@ -272,9 +287,12 @@
 
         Paragraph 2 of the first-level block quote.
 
-Multiple levels of indentation within a block quote will result in
-more complex structures::
+.. _reference indentation:
 
+Multiple levels of indentation within a block will result in more
+complex structures.  The least indented line of a block sets the
+*reference indentation*::
+
     This is a top-level paragraph.
 
         This paragraph belongs to a first-level block quote.
@@ -285,22 +303,15 @@
 
             This paragraph belongs to a second-level block quote.
 
-        This paragraph belongs to a first-level block quote.  The
-        second-level block quote above is inside this first-level
-        block quote.
+        This paragraph belongs to a first-level block quote.
+        The second-level block quote above is inside this
+        first-level block quote.
 
-When a paragraph or other construct consists of more than one line of
-text, the lines must be left-aligned::
+    Every block has its own reference indentation::
 
-    This is a paragraph.  The lines of
-    this paragraph are aligned at the left.
+            This paragraph belongs to a first-level block quote
+            because there is no less indented line in the block.
 
-        This paragraph has problems.  The
-    lines are not left-aligned.  In addition
-      to potential misinterpretation, warning
-        and/or error messages will be generated
-      by the parser.
-
 Several constructs begin with a marker, and the body of the construct
 must be indented relative to the marker.  For constructs using simple
 markers (`bullet lists`_, `enumerated lists`_), the level of
@@ -320,20 +331,34 @@
      this paragraph does not belong to the list
      item (it's a block quote following the list).
 
+The first line of text may start below the marker::
+
+    1.
+     This is the first line of an enumeration
+     item's paragraph.
+
+      This indented paragraph is interpreted
+      as a block quote.
+
+     This paragraph still belongs to the list
+     item
+
+    This paragraph ends the list.
+
 The body of `explicit markup blocks`_, `field lists`_, and `option
 lists`_ ends above the first line with the same or less indentation
 than the marker.  For example, field lists may have very long markers
 (containing the field names)::
 
-    :Hello: This field has a short field name, so aligning the field
-            body with the first line is feasible.
+    :Hello: This field has a short field name, so aligning
+            the field body with the first line is feasible.
+    :Long field name: It would be inconvenient to align the
+        field body with the left edge of the first line.
+    :Number of African swallows required to carry a coconut:
+        Sometimes, it is preferable to begin the body
+        on the next line.
 
-    :Number-of-African-swallows-required-to-carry-a-coconut: It would
-        be very difficult to align the field body with the left edge
-        of the first line.  It may even be preferable not to begin the
-        body on the same line as the marker.
 
-
 .. _escape:
 
 Escaping Mechanism

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