Adding upstream version 7.3.7.upstream/7.3.7upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 25 insertions, 257 deletions

diff --git a/doc/usage/restructuredtext/roles.rst b/doc/usage/restructuredtext/roles.rst
index e468de9..b21a2b7 100644
--- a/doc/usage/restructuredtext/roles.rst
+++ b/doc/usage/restructuredtext/roles.rst
@@ -15,267 +15,28 @@ They are written as ``:rolename:`content```.
    :rst:role:`any` role to find anything or the :rst:role:`py:obj` role to find
    Python objects are very useful for this.
 
-See :doc:`/usage/restructuredtext/domains` for roles added by domains.
+See :doc:`/usage/domains/index` for roles added by domains.
 
 
-.. _xref-syntax:
-
 Cross-referencing syntax
 ------------------------
 
-Cross-references are generated by many semantic interpreted text roles.
-Basically, you only need to write ``:role:`target```, and a link will be
-created to the item named *target* of the type indicated by *role*.  The link's
-text will be the same as *target*.
-
-There are some additional facilities, however, that make cross-referencing
-roles more versatile:
-
-* You may supply an explicit title and reference target, like in reST direct
-  hyperlinks: ``:role:`title <target>``` will refer to *target*, but the link
-  text will be *title*.
-
-* If you prefix the content with ``!``, no reference/hyperlink will be created.
-
-* If you prefix the content with ``~``, the link text will only be the last
-  component of the target.  For example, ``:py:meth:`~Queue.Queue.get``` will
-  refer to ``Queue.Queue.get`` but only display ``get`` as the link text.  This
-  does not work with all cross-reference roles, but is domain specific.
-
-  In HTML output, the link's ``title`` attribute (that is e.g. shown as a
-  tool-tip on mouse-hover) will always be the full target name.
-
-
-.. _any-role:
-
-Cross-referencing anything
-^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-.. rst:role:: any
-
-   .. versionadded:: 1.3
-
-   This convenience role tries to do its best to find a valid target for its
-   reference text.
-
-   * First, it tries standard cross-reference targets that would be referenced
-     by :rst:role:`doc`, :rst:role:`ref` or :rst:role:`option`.
-
-     Custom objects added to the standard domain by extensions (see
-     :meth:`.Sphinx.add_object_type`) are also searched.
-
-   * Then, it looks for objects (targets) in all loaded domains.  It is up to
-     the domains how specific a match must be.  For example, in the Python
-     domain a reference of ``:any:`Builder``` would match the
-     ``sphinx.builders.Builder`` class.
-
-   If none or multiple targets are found, a warning will be emitted.  In the
-   case of multiple targets, you can change "any" to a specific role.
-
-   This role is a good candidate for setting :confval:`default_role`.  If you
-   do, you can write cross-references without a lot of markup overhead.  For
-   example, in this Python function documentation::
-
-      .. function:: install()
-
-         This function installs a `handler` for every signal known by the
-         `signal` module.  See the section `about-signals` for more information.
-
-   there could be references to a glossary term (usually ``:term:`handler```), a
-   Python module (usually ``:py:mod:`signal``` or ``:mod:`signal```) and a
-   section (usually ``:ref:`about-signals```).
-
-   The :rst:role:`any` role also works together with the
-   :mod:`~sphinx.ext.intersphinx` extension: when no local cross-reference is
-   found, all object types of intersphinx inventories are also searched.
-
-Cross-referencing objects
-^^^^^^^^^^^^^^^^^^^^^^^^^
-
-These roles are described with their respective domains:
-
-* :ref:`Python <python-roles>`
-* :ref:`C <c-roles>`
-* :ref:`C++ <cpp-roles>`
-* :ref:`JavaScript <js-roles>`
-* :ref:`ReST <rst-roles>`
-
-
-.. _ref-role:
-
-Cross-referencing arbitrary locations
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-.. rst:role:: ref
-
-   To support cross-referencing to arbitrary locations in any document, the
-   standard reST labels are used.  For this to work label names must be unique
-   throughout the entire documentation.  There are two ways in which you can
-   refer to labels:
-
-   * If you place a label directly before a section title, you can reference to
-     it with ``:ref:`label-name```.  For example::
-
-        .. _my-reference-label:
-
-        Section to cross-reference
-        --------------------------
-
-        This is the text of the section.
-
-        It refers to the section itself, see :ref:`my-reference-label`.
-
-     The ``:ref:`` role would then generate a link to the section, with the
-     link title being "Section to cross-reference".  This works just as well
-     when section and reference are in different source files.
-
-     Automatic labels also work with figures. For example::
-
-        .. _my-figure:
-
-        .. figure:: whatever
-
-           Figure caption
-
-     In this case, a  reference ``:ref:`my-figure``` would insert a reference
-     to the figure with link text "Figure caption".
-
-     The same works for tables that are given an explicit caption using the
-     :dudir:`table` directive.
-
-   * Labels that aren't placed before a section title can still be referenced,
-     but you must give the link an explicit title, using this syntax:
-     ``:ref:`Link title <label-name>```.
-
-   .. note::
+See :doc:`/usage/referencing/`.
 
-      Reference labels must start with an underscore. When referencing a label,
-      the underscore must be omitted (see examples above).
+Cross-reference roles include:
 
-   Using :rst:role:`ref` is advised over standard reStructuredText links to
-   sections (like ```Section title`_``) because it works across files, when
-   section headings are changed, will raise warnings if incorrect, and works
-   for all builders that support cross-references.
+* :rst:role:`any`
+* :rst:role:`doc`
+* :rst:role:`download`
+* :rst:role:`envvar`
+* :rst:role:`keyword`
+* :rst:role:`numref`
+* :rst:role:`option` (and the deprecated :rst:role:`!cmdoption`)
+* :rst:role:`ref`
+* :rst:role:`term`
+* :rst:role:`token`
 
 
-Cross-referencing documents
-^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-.. versionadded:: 0.6
-
-There is also a way to directly link to documents:
-
-.. rst:role:: doc
-
-   Link to the specified document; the document name can be specified in
-   absolute or relative fashion.  For example, if the reference
-   ``:doc:`parrot``` occurs in the document ``sketches/index``, then the link
-   refers to ``sketches/parrot``.  If the reference is ``:doc:`/people``` or
-   ``:doc:`../people```, the link refers to ``people``.
-
-   If no explicit link text is given (like usual: ``:doc:`Monty Python members
-   </people>```), the link caption will be the title of the given document.
-
-
-Referencing downloadable files
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-.. versionadded:: 0.6
-
-.. rst:role:: download
-
-   This role lets you link to files within your source tree that are not reST
-   documents that can be viewed, but files that can be downloaded.
-
-   When you use this role, the referenced file is automatically marked for
-   inclusion in the output when building (obviously, for HTML output only).
-   All downloadable files are put into a ``_downloads/<unique hash>/``
-   subdirectory of the output directory; duplicate filenames are handled.
-
-   An example::
-
-      See :download:`this example script <../example.py>`.
-
-   The given filename is usually relative to the directory the current source
-   file is contained in, but if it absolute (starting with ``/``), it is taken
-   as relative to the top source directory.
-
-   The ``example.py`` file will be copied to the output directory, and a
-   suitable link generated to it.
-
-   Not to show unavailable download links, you should wrap whole paragraphs that
-   have this role::
-
-      .. only:: builder_html
-
-         See :download:`this example script <../example.py>`.
-
-Cross-referencing figures by figure number
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-.. versionadded:: 1.3
-
-.. versionchanged:: 1.5
-   `numref` role can also refer sections.
-   And `numref` allows `{name}` for the link text.
-
-.. rst:role:: numref
-
-   Link to the specified figures, tables, code-blocks and sections; the standard
-   reST labels are used.  When you use this role, it will insert a reference to
-   the figure with link text by its figure number like "Fig. 1.1".
-
-   If an explicit link text is given (as usual: ``:numref:`Image of Sphinx (Fig.
-   %s) <my-figure>```), the link caption will serve as title of the reference.
-   As placeholders, `%s` and `{number}` get replaced by the figure
-   number and  `{name}` by the figure caption.
-   If no explicit link text is given, the :confval:`numfig_format` setting is
-   used as fall-back default.
-
-   If :confval:`numfig` is ``False``, figures are not numbered,
-   so this role inserts not a reference but the label or the link text.
-
-Cross-referencing other items of interest
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-The following roles do possibly create a cross-reference, but do not refer to
-objects:
-
-.. rst:role:: envvar
-
-   An environment variable.  Index entries are generated.  Also generates a link
-   to the matching :rst:dir:`envvar` directive, if it exists.
-
-.. rst:role:: token
-
-   The name of a grammar token (used to create links between
-   :rst:dir:`productionlist` directives).
-
-.. rst:role:: keyword
-
-   The name of a keyword in Python.  This creates a link to a reference label
-   with that name, if it exists.
-
-.. rst:role:: option
-
-   A command-line option to an executable program.  This generates a link to
-   a :rst:dir:`option` directive, if it exists.
-
-
-The following role creates a cross-reference to a term in a
-:ref:`glossary <glossary-directive>`:
-
-.. rst:role:: term
-
-   Reference to a term in a glossary.  A glossary is created using the
-   ``glossary`` directive containing a definition list with terms and
-   definitions.  It does not have to be in the same file as the ``term`` markup,
-   for example the Python docs have one global glossary in the ``glossary.rst``
-   file.
-
-   If you use a term that's not explained in a glossary, you'll get a warning
-   during build.
-
 Inline code highlighting
 ------------------------
 
@@ -414,6 +175,10 @@ different style:
    ``:manpage:`ls(1)``` displays :manpage:`ls(1)`. Creates a hyperlink to an
    external site rendering the manpage if :confval:`manpages_url` is defined.
 
+   .. versionchanged:: 7.3
+      Allow specifying a target with ``<>``, like hyperlinks.
+      For example, ``:manpage:`blah <ls(1)>``` displays :manpage:`blah <ls(1)>`.
+
 .. rst:role:: menuselection
 
    Menu selections should be marked using the ``menuselection`` role.  This is
@@ -468,14 +233,17 @@ different style:
 
    A piece of literal text, such as code.  Within the contents, you can use
    curly braces to indicate a "variable" part, as in :rst:role:`file`.  For
-   example, in ``:samp:`print 1+{variable}```, the part ``variable`` would be
-   emphasized: :samp:`print 1+{variable}`
+   example, in ``:samp:`print(1+{variable})```, the part ``variable`` would be
+   emphasized: :samp:`print(1+{variable})`
 
    If you don't need the "variable part" indication, use the standard
    :rst:role:`code` role instead.
 
    .. versionchanged:: 1.8
-      Allowed to escape curly braces with backslash
+      Allowed to escape curly braces with double backslash.  For example, in
+      ``:samp:`print(f"answer=\\{1+{variable}*2\\}")```, the part ``variable``
+      would be emphasized and the escaped curly braces would be displayed:
+      :samp:`print(f"answer=\\{1+{variable}*2\\}")`
 
 There is also an :rst:role:`index` role to generate index entries.
 
@@ -508,7 +276,7 @@ the standard reST markup for that purpose.
 Substitutions
 -------------
 
-The documentation system provides three substitutions that are defined by
+The documentation system provides some substitutions that are defined by
 default. They are set in the build configuration file.
 
 .. describe:: |release|
@@ -532,5 +300,5 @@ default. They are set in the build configuration file.
 .. describe:: |translation progress|
 
    Replaced by the translation progress of the document.
-   This substitution is intented for use by document translators
+   This substitution is intended for use by document translators
    as a marker for the translation progress of the document.