SF.net SVN: docutils:[9548 ] trunk/docutils/docs/ref/r st

Revision: 9548
          http://sourceforge.net/p/docutils/code/9548
Author:   milde
Date:     2024-02-26 11:51:40 +0000 (Mon, 26 Feb 2024)
Log Message:
-----------
Restructure documentation of custom roles.

Move the description of base-role-dependent options for the "role" directive
to the documentation of the "role" directive.
Shorten and clarify descriptions, add cross-links.

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

Modified: trunk/docutils/docs/ref/rst/directives.txt
===================================================================
--- trunk/docutils/docs/ref/rst/directives.txt	2024-02-17 10:38:15 UTC (rev 9547)
+++ trunk/docutils/docs/ref/rst/directives.txt	2024-02-26 11:51:40 UTC (rev 9548)
@@ -573,8 +573,7 @@
 specified, the content is parsed by the Pygments_ syntax highlighter and
 tokens are stored in nested `inline elements`_ with class arguments
 according to their syntactic category. The actual highlighting requires
-a style-sheet (e.g. one `generated by Pygments`__, see the
-`sandbox/stylesheets`__ for examples).
+a custom style-sheet, see the `sandbox/stylesheets`_ for examples.
 
 For example, the content of the following directive ::
 
@@ -603,8 +602,7 @@
     Precede every line with a line number.
     The optional argument is the number of the first line (default 1).
 
-__ https://pygments.org/docs/cmdline/#generating-styles
-__ https://docutils.sourceforge.io/sandbox/stylesheets/
+.. _sandbox/stylesheets: https://docutils.sourceforge.io/sandbox/stylesheets/
 .. _Pygments: https://pygments.org/
 .. _syntax_highlight: ../../user/config.html#syntax-highlight
 .. _supported languages and markup formats: https://pygments.org/languages/
@@ -800,7 +798,7 @@
 
 :Directive Type: "container"
 :Doctree Element: `\<container>`_
-:Directive Arguments: one or more, optional (class names)
+:Directive Arguments: one or more, optional (`class names`_)
 :Directive Options: name_
 :Directive Content: Interpreted as body elements.
 
@@ -1868,7 +1866,7 @@
 :Doctree Element: none; affects subsequent parsing
 :Directive Arguments: two; one required (new `role name`_), one optional
                       (base role name, in parentheses)
-:Directive Options: Possible (depends on base role).
+:Directive Options: `see below <role options_>`__
 :Directive Content: depends on base role.
 
 The "role" directive dynamically creates a custom `interpreted text
@@ -1888,11 +1886,9 @@
         <inline classes="custom">
             interpreted text
 
-The role must be declared in a document before it can be used.
-
 .. _role name:
 
-Role names are case insensitive and must conform to the rules of
+*Role names* are case insensitive and must conform to the rules of
 simple `reference names`_ (but do not share a namespace with
 hyperlinks, footnotes, and citations).
 
@@ -1919,40 +1915,49 @@
 
 If no base role is explicitly specified, a generic custom role is
 automatically used.  Subsequent interpreted text will produce an
-"inline" element with a `classes attribute`_, as in the first example
-above.
+`\<inline>`_ element with a `classes attribute`_, as in the first
+example above.
 
-With most roles, the ":class:" option can be used to set a "classes"
-attribute that is different from the role name.  For example::
+.. _role options:
 
-    .. role:: custom
-       :class: special
+Depending on the base role, the following options may be recognized by the
+"role" directive:
 
-    :custom:`interpreted text`
+.. _class-option (role directive):
 
-This is the parsed result::
+class : space separated list of `class names`_
+    Set the `classes attribute`_ value on the element produced
+    when the custom interpreted text role is used.
+    Default value is the directive argument (role name).
 
-    <paragraph>
-        <inline classes="special">
-            interpreted text
+    For example ::
 
-.. _role class:
+      .. role:: custom
+         :class: special
 
-The following option is recognized by the "role" directive for most
-base roles:
+      :custom:`interpreted text`
 
-``class`` : space separated list of `class names`_
-    Set the `classes attribute`_ value on the element produced
-    (``inline``, or element associated with a base class) when the
-    custom interpreted text role is used.  If no directive options are
-    specified, a "class" option with the directive argument (role
-    name) as the value is implied.  See the `class directive`_ above.
+    is parsed as ::
 
-Specific base roles may support other options and/or directive
-content.  See the `reStructuredText Interpreted Text Roles`_ document
-for details.
+      <paragraph>
+          <inline classes="special">
+              interpreted text
 
+    The "class" option is recognized with all interpreted text roles.
+
+_`format` : space-separated list of output format names (`writer names`_)
+    Specify the generated <raw> element's `format attribute`_.
+
+    Only recognized with the `:raw:`_ base role.
+
+_`language` : text
+    Name of a formal language, passed to Pygments_ for syntax highlighting.
+    See `supported languages and markup formats`_ for recognized values.
+
+    Only recognized with the `:code:`_ base role.
+
 .. _reStructuredText Interpreted Text Roles: roles.html
+.. _writer names: ../../user/config.html#writer-docutils-application
 
 
 .. _default-role:
@@ -2223,16 +2228,21 @@
     restructuredtext.html#external-hyperlink-targets
 .. _hyperlink references: restructuredtext.html#hyperlink-references
 .. _hyperlink target: restructuredtext.html#hyperlink-targets
-.. _interpreted text role: roles.html
 .. _length units: restructuredtext.html#length-units
 .. _percentage: restructuredtext.html#percentage-units
 .. _reference name:
 .. _reference names: restructuredtext.html#reference-names
+
+.. _interpreted text role: roles.html
+.. _`:code:`: roles.html#code
+.. _`:raw:`: roles.html#raw
+
 .. _identifier keys: ../doctree.html#ids-type
 .. _inline elements: ../doctree.html#inline-elements
 .. _class names: ../doctree.html#classname
 .. _classes:
 .. _classes attribute: ../doctree.html#classes
+.. _format attribute: ../doctree.html#format
 .. _ids attribute: ../doctree.html#ids
 .. _names attribute: ../doctree.html#names
 .. _root_prefix: ../../user/config.html#root-prefix
@@ -2255,6 +2265,7 @@
 .. _<header>: ../doctree.html#header
 .. _<hint>: ../doctree.html#hint
 .. _<image>: ../doctree.html#image
+.. _<inline>: ../doctree.html#inline
 .. _<important>: ../doctree.html#important
 .. _<legend>: ../doctree.html#legend
 .. _<line_block>: ../doctree.html#line-block

Modified: trunk/docutils/docs/ref/rst/roles.txt
===================================================================
--- trunk/docutils/docs/ref/rst/roles.txt	2024-02-17 10:38:15 UTC (rev 9547)
+++ trunk/docutils/docs/ref/rst/roles.txt	2024-02-26 11:51:40 UTC (rev 9548)
@@ -74,16 +74,16 @@
 
 :Aliases:         None
 :Doctree Element: `\<literal>`_
-:Customization_ options: class_, language_
+:Customization_ options: `class <"class" option_>`__,
+                         `language <"language" option_>`__
 
 (New in Docutils 0.9.)
 
 The :code: role marks its content as code in a formal language.
 
-For syntax highlight of inline code, the `"role" directive`_ can be used to
-build `custom roles`_ with the code language specified in the "language_"
-option.
-
+For syntax highlight of inline code, the `"role" directive`_ can
+be used to create `custom roles`_ with the code language specified
+in the `"language" option`_.
 For example, the following creates a LaTeX-specific "latex" role::
 
   .. role:: latex(code)
@@ -90,17 +90,11 @@
      :language: latex
 
 Content of the new role is parsed and tagged by the Pygments_ syntax
-highlighter. See the `"code" directive`_ for more info on parsing and display
-of code in reStructuredText.
+highlighter. See the `"code" directive`_ for more info on parsing
+and display of code in reStructuredText.
 
-In addition to "class_", the following option is recognized:
-
-_`language` : text
-    Name of the code's language.
-    See `supported languages and markup formats`_ for recognized values.
-
+.. _customization: `custom roles`_
 .. _Pygments: https://pygments.org/
-.. _supported languages and markup formats: https://pygments.org/languages/
 
 
 ----------
@@ -218,9 +212,7 @@
       It is recommended to use `hyperlink references`_ for
       anything more complex than a single RFC number.
 
-.. _hyperlink references: restructuredtext.html#hyperlink-references
 
-
 --------
 :strong:
 --------
@@ -329,9 +321,6 @@
 must be used to obtain a ``title_reference`` element.
 
 
-.. _pseudo-XML: ../doctree.html#pseudo-xml
-
-
 Specialized Roles
 =================
 
@@ -343,7 +332,8 @@
 
 :Aliases:         None
 :Doctree Element: `\<raw>`_
-:Customization_ options: class_, format_
+:Customization_ options: `class <"class" option_>`__,
+                         `format <"format" option_>`__
 
 The "raw" role indicates non-reStructuredText data that is to be
 passed untouched to the Writer.  It is the inline equivalent of the
@@ -351,8 +341,8 @@
 semantics.
 
 **The "raw" role cannot be used directly.**  The `"role" directive`_ must
-first be used to build `custom roles`_ based on the "raw" role.  One or
-more formats (Writer names) must be provided in a "format" option.
+first be used to create `custom roles`_ based on the "raw" role.  One or
+more formats (Writer names) must be provided in a `"format" option`_.
 
 .. WARNING::
    The "raw" role is a stop-gap measure allowing the author to bypass
@@ -385,41 +375,43 @@
    they are not mistaken for reStructuredText markup.  Using a "raw-"
    prefix for role names is recommended.
 
-In addition to "class_", the following option is recognized:
 
-_`format` : text
-    One or more space-separated output format names (Writer names).
-
-
-.. _customization:
-
 Custom Roles
 ============
 
 Custom interpreted text roles can be defined in a document with the
 `"role" directive`_. The new role may be based on an existing role.
+The "role" directive may be called with options_ to customize the
+generated roles.
 
-The "class_" option is recognized by the "role" directive for
-all interpreted text roles.
-Specific base roles may support additional options and/or directive
-content. Details are listed with the respective roles.
 
-
 .. References
 
 .. _reStructuredText Markup Specification: restructuredtext.html
 .. _Interpreted Text: restructuredtext.html#interpreted-text
+.. _hyperlink references: restructuredtext.html#hyperlink-references
+
 .. _The Docutils Document Tree: ../doctree.html
+.. _class names: ../doctree.html#classname
+.. _classes attribute: ../doctree.html#classes
+.. _format attribute: ../doctree.html#format
+.. _pseudo-XML: ../doctree.html#pseudo-xml
+
 .. _Docutils Generic DTD: ../docutils.dtd
 .. _Creating reStructuredText Interpreted Text Roles:
     ../../howto/rst-roles.html
+.. _writer names: ../../user/config.html#writer-docutils-application
 
+.. _"class" directive:        directives.html#role-class
 .. _"code" directive:         directives.html#code
 .. _"default-role" directive: directives.html#default-role
 .. _"role" directive:         directives.html#role
 .. _"math" directive:         directives.html#math
-.. _"raw" directive:          directives.html#raw-directive
-.. _class:                    directives.html#role-class
+.. _"raw" directive:          directives.html#raw
+.. _options:                  directives.html#role-options
+.. _"class" option:           directives.html#class-option-role-directive
+.. _"format" option:          directives.html#format
+.. _"language" option:        directives.html#language
 
 .. _<abbreviation>:    ../doctree.html#abbreviation
 .. _<acronym>:         ../doctree.html#acronym

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