SF.net SVN: docutils:[9883 ] trunk/docutils/docs/ref

Revision: 9883
          http://sourceforge.net/p/docutils/code/9883
Author:   milde
Date:     2024-08-12 19:18:38 +0000 (Mon, 12 Aug 2024)
Log Message:
-----------
Clarify documentation of the "URI reference" data type in elements and directives.

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

Modified: trunk/docutils/docs/ref/doctree.txt
===================================================================
--- trunk/docutils/docs/ref/doctree.txt	2024-08-11 07:18:41 UTC (rev 9882)
+++ trunk/docutils/docs/ref/doctree.txt	2024-08-12 19:18:38 UTC (rev 9883)
@@ -4726,13 +4726,15 @@
 Attribute type: `CDATA`_.  Default value: none.
 
 The ``uri`` attribute is used in the `\<image>`_ and `\<figure>`_
-elements to refer to the image via a `URI Reference`_ (URI or
-`relative reference`_).
+elements to refer to the image via a `URI Reference`_ [#]_. [rfc3986]_
 
-.. _URI Reference: https://www.rfc-editor.org/rfc/rfc3986.html#section-4.1
-.. _relative reference: https://www.rfc-editor.org/rfc/rfc3986.html#section-4.2
+.. [#] Examples are a full URI, an *absolute-path reference* (begins with
+   a single slash character) or a *relative-path reference* (does not
+   begin with a slash character).
 
+.. _URI reference: https://www.rfc-editor.org/rfc/rfc3986.html#section-4.1
 
+
 ``valign``
 ==========
 
@@ -5245,7 +5247,10 @@
                 WHATWG (Apple, Google, Mozilla, Microsoft),
                 https://html.spec.whatwg.org.
 
-.. [xml1.0]    `Extensible Markup Language (XML) 1.0`,
+.. [rfc3986]    Berners-Lee, T., Fielding, R., and L. Masinter,
+                `Uniform Resource Identifier (URI): Generic Syntax`,
+                STD 66, RFC 3986, DOI 10.17487/RFC3986, January 2005,
+                https://www.rfc-editor.org/info/rfc3986.
 
 .. [tm9901]     .. _XML Exchange Table Model DTD:
                 .. _Exchange Table Model:
@@ -5256,6 +5261,8 @@
                 W3C Recommendation,
                 https://www.w3.org/TR/xml/.
 
+.. [xml1.0]    `Extensible Markup Language (XML) 1.0`,
+
 .. _DocBook: https://tdg.docbook.org/tdg/5.1/.
 .. _DocBook <caution>: https://tdg.docbook.org/tdg/5.1/caution.html
 .. _DocBook <footnote>: https://tdg.docbook.org/tdg/5.1/footnote.html

Modified: trunk/docutils/docs/ref/rst/directives.txt
===================================================================
--- trunk/docutils/docs/ref/rst/directives.txt	2024-08-11 07:18:41 UTC (rev 9882)
+++ trunk/docutils/docs/ref/rst/directives.txt	2024-08-12 19:18:38 UTC (rev 9883)
@@ -217,7 +217,7 @@
 
     .. image:: picture.png
 
-An URI-reference_ to the image source file is specified in the directive
+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
 begin in an indented text block immediately following, with no
@@ -297,7 +297,7 @@
 
 ``target`` : URI_ or `reference name`_
     Nest the image in a hyperlink reference element (make it "clickable").
-    The option argument may be a URI-reference_ or a `reference name`_
+    The option argument may be a URI reference or a reference name
     with underscore suffix (e.g. ```a name`_``).
 
 ``width`` : length_ or percentage_ of the current line width
@@ -1008,7 +1008,7 @@
     .. _`url`:
 
 ``url`` : URI_
-    A URI-reference to a CSV data file.
+    A URI reference to a CSV data file.
 
 ``width`` : length_ or percentage_ of the current line width
     Sets the width of the table to the specified length or percentage
@@ -1709,7 +1709,7 @@
     The local filesystem path of a raw data file to be included.
 
 ``url`` : URI_
-    A URI-reference to a raw data file to be included.
+    A URI reference to a raw data file to be included.
 
 
 .. _class directive:
@@ -2208,9 +2208,8 @@
 :_`path`: local filesystem path
 
   Newlines are removed.
-
   The `root_prefix`_ configuration setting can be used to tell Docutils
-  to interpret absolute paths (starting with "/") relative to a "project
+  to interpret root paths (starting with "/") relative to a "project
   directory".
 
 :_`text`: free text
@@ -2217,8 +2216,10 @@
 
   Possible restrictions are given in parentheses.
 
-:_`URI`: _`URI-reference` (URI or `relative reference`_, cf. :RFC:`3986`)
+:_`URI`: _`URI reference`
 
+  Full URI or `relative reference`_ (absolute or relative path reference),
+  cf. :RFC:`3986`.
   Whitespace is removed (cf. `external hyperlink targets`_ in the
   reStructuredText specification).
 
@@ -2278,6 +2279,7 @@
 .. _loading attribute: ../doctree.html#loading
 .. _names attribute: ../doctree.html#names
 .. _title attribute: ../doctree.html#title-attribute
+.. _uri attribute: ../doctree.html#uri
 .. _width attribute: ../doctree.html#width
 .. _<admonition>: ../doctree.html#admonition
 .. _<attention>: ../doctree.html#attention

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