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

milde--- via Docutils-checkins <[email protected]>
Newsgroups gmane.text.docutils.cvs
Message-ID <[email protected]> 
Revision: 9865
          http://sourceforge.net/p/docutils/code/9865
Author:   milde
Date:     2024-08-07 23:35:42 +0000 (Wed, 07 Aug 2024)
Log Message:
-----------
Documentation update: clarify URI use.

RFC 3986 introduces the term "URI-reference" for
either a URI (with mandatory scheme part) or a "relative reference"
(without scheme part) which may be, e.g., an absolute or relative path.

Cf. [bugs: #493].

Modified Paths:
--------------
    trunk/docutils/docs/howto/rst-directives.txt
    trunk/docutils/docs/ref/doctree.txt
    trunk/docutils/docs/ref/rst/directives.txt
    trunk/docutils/docs/ref/rst/restructuredtext.txt
    trunk/docutils/docs/user/latex.txt

Modified: trunk/docutils/docs/howto/rst-directives.txt
===================================================================
--- trunk/docutils/docs/howto/rst-directives.txt	2024-08-07 15:56:42 UTC (rev 9864)
+++ trunk/docutils/docs/howto/rst-directives.txt	2024-08-07 23:35:42 UTC (rev 9865)
@@ -169,8 +169,8 @@
 - ``path``: Returns the path argument unwrapped (with newlines
   removed).  Raises ``ValueError`` if no argument is found.
 
-- ``uri``: Returns the URI argument with whitespace removed.  Raises
-  ``ValueError`` if no argument is found.
+- ``uri``: Returns the value (URI-reference) with whitespace removed.
+  Raises ``ValueError`` if no argument is found.
 
 - ``nonnegative_int``: Checks for a nonnegative integer argument,
   and raises ``ValueError`` if not.

Modified: trunk/docutils/docs/ref/doctree.txt
===================================================================
--- trunk/docutils/docs/ref/doctree.txt	2024-08-07 15:56:42 UTC (rev 9864)
+++ trunk/docutils/docs/ref/doctree.txt	2024-08-07 23:35:42 UTC (rev 9865)
@@ -4603,7 +4603,7 @@
 
 Attribute type: `CDATA`_.  Default value: none.
 
-The ``refuri`` attribute contains an external reference to a URI/URL.
+The ``refuri`` attribute contains an external reference to a URI.
 It is used by the `\<target>`_, `\<reference>`_,
 `\<footnote_reference>`_, and `\<citation_reference>`_ elements
 (via the `%reference.atts`_ parameter entity).
@@ -4645,7 +4645,7 @@
 
 Attribute type: `CDATA`_.  Default value: none.
 
-The ``source`` attribute is used to store the path or URL to the
+The ``source`` attribute is used to store the path or URI of the
 source text that was used to produce the document tree.
 
 It is one of the `common attributes`_, declared for all Docutils
@@ -4725,10 +4725,14 @@
 
 Attribute type: `CDATA`_.  Default value: none.
 
-The ``uri`` attribute is used in the `\<image>`_ and `\<figure>`_ elements
-to refer to the image via its Universal Resource Indicator.
+The ``uri`` attribute is used in the `\<image>`_ and `\<figure>`_
+elements to refer to the image via a `URI Reference`_ (URI or
+`relative reference`_).
 
+.. _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
 
+
 ``valign``
 ==========
 
@@ -4976,7 +4980,7 @@
 ---------------
 
 The ``%refuri.att`` parameter entity contains the refuri_ attribute,
-an external reference to a URI/URL.
+an external reference to a URI.
 
 Entity definition::
 
@@ -5232,13 +5236,6 @@
 Bibliography
 ------------
 
-.. [tm9901]     .. _XML Exchange Table Model DTD:
-                .. _Exchange Table Model:
-
-                `XML Exchange Table Model DTD`,
-                OASIS Technical Memorandum 9901:1999,
-                http://www.oasis-open.org/html/tm9901.html.
-
 .. [DocBook5.1] `DocBook 5.1: The Definitive Guide`,
                 Norman Walsh,
                 https://tdg.docbook.org/tdg/5.1/.
@@ -5249,6 +5246,13 @@
                 https://html.spec.whatwg.org.
 
 .. [xml1.0]    `Extensible Markup Language (XML) 1.0`,
+
+.. [tm9901]     .. _XML Exchange Table Model DTD:
+                .. _Exchange Table Model:
+
+                `XML Exchange Table Model DTD`,
+                OASIS Technical Memorandum 9901:1999,
+                http://www.oasis-open.org/html/tm9901.html.
                 W3C Recommendation,
                 https://www.w3.org/TR/xml/.
 

Modified: trunk/docutils/docs/ref/rst/directives.txt
===================================================================
--- trunk/docutils/docs/ref/rst/directives.txt	2024-08-07 15:56:42 UTC (rev 9864)
+++ trunk/docutils/docs/ref/rst/directives.txt	2024-08-07 23:35:42 UTC (rev 9865)
@@ -216,7 +216,7 @@
 
     .. image:: picture.png
 
-The URI for the image source file is specified in the directive
+An 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
@@ -296,7 +296,7 @@
 
 ``target`` : URI_ or `reference name`_
     Nest the image in a hyperlink reference element (make it "clickable").
-    The option argument may be a URI_ 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
@@ -1007,7 +1007,7 @@
     .. _`url`:
 
 ``url`` : URI_
-    An Internet 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
@@ -1706,7 +1706,7 @@
     The local filesystem path of a raw data file to be included.
 
 ``url`` : URI_
-    An Internet URI reference to a raw data file to be included.
+    A URI-reference to a raw data file to be included.
 
 
 .. _class directive:
@@ -2165,63 +2165,49 @@
 Common Option Value Types
 -------------------------
 
-*"keyword"*
-  recognized keywords.
+.. class:: run-in narrow
+
+:"keyword": recognized keywords
+
   Used without quotes in the reStructuredText source.
 
-  .. _character:
+:_`character`: single character
 
-*character*
-  single character.
   May be specified as literal character or as Unicode `character code`_
   (cf. the unicode_ directive).
 
-  .. _encoding:
+:_`encoding`: text encoding name
 
-*encoding*
-  text encoding name.
   Docutils looks it up in the list of registered codecs_
   (see also `Standard Encodings`_).
 
-  .. _flag:
+:_`flag`: no value
 
-*flag*
-  no value.
+:_`integer`: integer number
 
-  .. _integer:
-
-*integer*
   A _`list of integers` may be comma- or whitespace-separated.
 
-  .. _length:
+:_`length`: number followed by one of the supported `length units`_
 
-*length*
-  number followed by one of the supported `length units`_.
+:_`path`: local filesystem path
 
-  .. _path:
+  Newlines are removed.
 
-*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
   directory".
 
-  .. _text:
+:_`text`: free text
 
-*text*
-  free text (with possible restrictions in parentheses).
+  Possible restrictions are given in parentheses.
 
-  .. _URI:
+:_`URI`: _`URI-reference` (URI or `relative reference`_, cf. :RFC:`3986`)
 
-*URI*
-  `Uniform Resource Identifier`__.
-  Whitespace is removed, cf. `external hyperlink targets`_ in the
-  reStructuredText specification..
+  Whitespace is removed (cf. `external hyperlink targets`_ in the
+  reStructuredText specification).
 
-  __ https://en.wikipedia.org/wiki/Uniform_Resource_Identifier
-
-
 .. _codecs: https://docs.python.org/3/library/codecs.html
+.. _relative reference: https://www.rfc-editor.org/rfc/rfc3986.html#section-4.2
 .. _Standard Encodings:
     https://docs.python.org/3/library/codecs.html#standard-encodings
 

Modified: trunk/docutils/docs/ref/rst/restructuredtext.txt
===================================================================
--- trunk/docutils/docs/ref/rst/restructuredtext.txt	2024-08-07 15:56:42 UTC (rev 9864)
+++ trunk/docutils/docs/ref/rst/restructuredtext.txt	2024-08-07 23:35:42 UTC (rev 9865)
@@ -381,9 +381,10 @@
 
      r"""This is a raw docstring.  Backslashes (\) are not touched."""
 
-.. [#uri-context] In contexts where Docutils expects a URI (the link
-   block of `external hyperlink targets`_ or the argument of an `"image"`_
-   or `"figure"`_ directive), whitespace is ignored by default
+.. [#uri-context] In contexts where Docutils expects a `URI-reference`_
+   (the link block of `external hyperlink targets`_ or the argument of an
+   `"image"`_
+   or `"figure"`_ directive), whitespace is ignored by default.
 
 .. [#literal-context]
    In literal context (`literal blocks`_ and `inline literals`_,
@@ -1950,9 +1951,8 @@
        * second item, with hyperlink target.
 
 
-2. _`External hyperlink targets` have an absolute or relative URI or
-   email address in their link blocks.  For example, take the
-   following input::
+2. _`External hyperlink targets` have a URI-reference_ or email address
+   in their link blocks.  For example, take the following input::
 
        See the Python_ home page for info.
 
@@ -2897,9 +2897,9 @@
     `HTML Element: <c>\ `_.
 
 The reference text may also be omitted, in which case the URI will be
-duplicated for use as the reference text.  This is useful for relative
-URIs where the address or file name is also the desired reference
-text::
+duplicated for use as the reference text.  This is useful for
+URI-references_ where the address or file name is also the desired
+reference text::
 
     See `<a_named_relative_link>`_ or
     `<an_anonymous_relative_link>`__ for details.
@@ -3050,7 +3050,7 @@
 
    With queries, fragments, and %-escape sequences, URIs can become quite
    complicated.  A reStructuredText parser must be able to recognize any
-   URI, as defined in RFC2396_ and RFC2732_.
+   URI, as defined in RFC3936.
 
 2. Standalone email addresses, which are treated as if they were
    URIs with a "mailto:" scheme.  Example::
@@ -3065,7 +3065,7 @@
 
 .. [#URI] Uniform Resource Identifier.  URIs are a general form of
    URLs (Uniform Resource Locators).  For the syntax of URIs see
-   RFC2396_ and RFC2732_.
+   RFC3986_.
 
 
 Units
@@ -3276,9 +3276,10 @@
     http://www.iana.org/assignments/uri-schemes
 .. _Retired Index of WWW Addressing Schemes:
     https://www.w3.org/Addressing/schemes.html
-.. _RFC822: https://www.rfc-editor.org/rfc/rfc822.txt
-.. _RFC2396: https://www.rfc-editor.org/rfc/rfc2396.txt
-.. _RFC2732: https://www.rfc-editor.org/rfc/rfc2732.txt
+.. _RFC822: https://www.rfc-editor.org/rfc/rfc822
+.. _RFC3986: https://www.rfc-editor.org/rfc/rfc3986
+.. _URI-references:
+.. _URI-reference: https://www.rfc-editor.org/rfc/rfc3986.html#section-4.1
 .. _World Wide Web Consortium: https://www.w3.org/
 .. _Zope: http://www.zope.com/
 

Modified: trunk/docutils/docs/user/latex.txt
===================================================================
--- trunk/docutils/docs/user/latex.txt	2024-08-07 15:56:42 UTC (rev 9864)
+++ trunk/docutils/docs/user/latex.txt	2024-08-07 23:35:42 UTC (rev 9865)
@@ -93,7 +93,7 @@
 LaTeX supports all `length units`_ defined for Docutils plus the
 following less common units:
 
-.. class:: narrow 
+.. class:: narrow
 
 :dd: didôt (1 dd = 1238/1157 pt)
 :cc: cîcero (1 cc = 12 dd)
@@ -1749,7 +1749,7 @@
 the ``\DUtitle`` command which can be re-defined in the corresponding
 DUCLASS environment.
 
-* The re-definition is local to the environment, so you don't need to 
+* The re-definition is local to the environment, so you don't need to
   save/restore the original function.
 
 * In the nested function redefinition, the argument placeholder requires
@@ -1799,7 +1799,7 @@
 
 Note:
   8-bit LaTeX comes with two options for UTF-8 support,
-  
+
   .. class:: field-indent-4em
 
   :utf8:  by the standard `inputenc`_ package with only limited coverage
@@ -1987,11 +1987,11 @@
 
 The Rubber_ wrapper can be used for automatic image conversion.
 
-Docutils expects an URI as pointer to the image file. The latex writer
-transforms this URI to a local path. By default, LaTeX does not accept
-spaces and more than one dot in the filename. If using "traditional"
-filenames is not an option, adding grffile_ to the `style sheets`_
-can help.
+Docutils expects a URI-reference_ as pointer to the image ressource.
+LaTeX requires it to refer to a local file.
+By default, LaTeX does not accept spaces and more than one dot in the
+filename. If using "traditional" filenames is not an option, loading the
+grffile_ package may help.
 
 __ ../ref/rst/directives.html#images
 .. _grfguide.pdf:

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
lmpx.com only provides a reader for public news (NNTP) servers. It is not affiliated with the servers or forums shown here and is not responsible for the content of articles, which is written by their respective authors.