[TASK] Overhaul text roles reference page

The page was a two-line summary plus a tabbed snippet dump with no
explanation of what each role does or when to use it. Give :abbr:,
:path:, :file:, and :issue: their own entries with rendered examples,
and add a callout on the backslash-escaping gotcha (`\Vendor\Ext\Class`
silently drops its backslashes; :file:/:php:/:php-short: are
exceptions). Point to the pages that already cover :guilabel:/:kbd:,
:composer:/:t3ext:, :t3src:, and the code roles instead of duplicating
them here.

Cross-reference the backslash callout from InlineCode.rst's existing
plain-literal example, and reword CodingGuidelines.rst's GUI section to
lead with "use :guilabel: for any visible label" instead of only
covering click-path separators, adding a single-label example to match.

Not verified with the Docker render pipeline: this environment has no
network access to resolve docs.typo3.org's intersphinx inventory.

Assisted-by: Claude Sonnet 5 <noreply@anthropic.com>
Signed-off-by: Lina Wolf

Author: linawolf

Documentation/Advanced/CodingGuidelines.rst

@@ -272,9 +272,10 @@ For this to work, `ext_core` must be defined in :file:`Settings.cfg`:
 Referring to GUI elements
 =========================
 
-If you describe something that needs to be selected from a menu or other GUI
-element or clicked one after the other, use *>* as separator and use
-:ref:`text role guilabel <text-roles>`.
+Use :ref:`text role guilabel <text-roles>` for any label that is visible in
+the GUI: a backend module, a tab, a button, a field, or a menu entry. If you
+describe several of these being selected or clicked one after the other, use
+`>` as separator inside a single :rst:`:guilabel:`.
 
 ..  important::
 
@@ -296,6 +297,13 @@ How it looks:
 How it looks:
     Click on :guilabel:`ADMIN TOOLS > Extensions` in the backend.
 
+..  code-block:: rst
+
+    Manage extensions in the :guilabel:`Extension Manager` module.
+
+How it looks:
+    Manage extensions in the :guilabel:`Extension Manager` module.
+
 
 ..  index::
     reST; Keystrokes

Documentation/Reference/ReStructuredText/Code/InlineCode.rst

@@ -94,8 +94,11 @@ those cases a plain literal reads more honestly:
 
 *   When you are talking about a concept rather than naming a specific,
     resolvable class — for example "a PreviewRenderer" used generically,
-    not `\Vendor\Ext\PreviewRenderer` — a plain literal fits better, since
-    there is no single class the infobox could point to.
+    not `\\Vendor\\Ext\\PreviewRenderer` — a plain literal fits better,
+    since there is no single class the infobox could point to. Note the
+    doubled backslashes: unlike :rst:`:php:`, a plain literal drops a
+    single backslash instead of printing it — see
+    `Supported named inline text roles <https://docs.typo3.org/permalink/h2document:text-roles-backslash>`_.
 
 *   Headlines are the one place to leave roles out entirely, including
     :rst:`:php:`/:rst:`:php-short:` — use plain backticks there even for

Documentation/Reference/ReStructuredText/InlineMarkup/TextRoles/Index.rst

@@ -7,26 +7,132 @@
 Supported named inline text roles
 =================================
 
-In general we support any text roles in reStructuredText that were previously
-supported by Sphinx.
+A named inline text role marks up a short piece of text inline, in the
+middle of a sentence. Write the role name surrounded by colons
+(:rst:`:role-name:`), immediately followed — with no space — by the text
+it applies to, enclosed in backticks. Some roles expect that text to
+follow a particular syntax, for example a link target, an issue number,
+or a fully-qualified class name.
 
-The TYPO3 Documentation Rendering Container also supports the
+In general we support any text roles in reStructuredText that were
+previously supported by Sphinx. The TYPO3 Documentation Rendering
+Container also supports the
 `Docutils Standard Text Roles <https://docutils.sourceforge.io/docs/ref/rst/roles.html#standard-roles>`_
-except for `:raw:`, as that could pose security issues.
+except for :rst:`:raw:`, as that could pose security issues.
 
-..  seealso::
+The roles below are the ones most commonly used across TYPO3
+documentation that are not already covered on their own page.
 
-    *   `Basic inline markup (bold, italic etc.) <https://docs.typo3.org/permalink/h2document:rest-bold-italic>`_
-    *   `Inline code with or without overlays <https://docs.typo3.org/permalink/h2document:inline-code>`_
-        for roles like `:php:`, `:typoscript:`, etc.
-    *   `Links in ReStructured Text <https://docs.typo3.org/permalink/h2document:how-to-document-hyperlinks>`_
+..  _text-roles-backslash:
+
+..  attention::
+
+    For most roles, a lone backslash inside the backticks is treated as
+    an escape character and silently disappears from the output instead
+    of being printed. This trips people up in Windows paths and PHP
+    namespaces:
+
+    ..  code-block:: rst
+
+        `\Vendor\Ext\MyClass`        renders as: VendorExtMyClass
+        `\\Vendor\\Ext\\MyClass`     renders as: \Vendor\Ext\MyClass
+
+    Double every backslash you want to keep. :rst:`:file:`, :rst:`:php:`
+    and :rst:`:php-short:` are exceptions -- they take the text verbatim,
+    so a single backslash there already prints as-is. If you are not
+    sure how a given role handles it, check the rendered output rather
+    than assuming.
+
+..  index:: reST roles; abbr
+..  _text-roles-abbr:
+
+`:abbr:`
+========
+
+Marks a piece of text as an abbreviation or acronym. Write the
+abbreviation followed by its expansion in parentheses; the expansion is
+shown as a tooltip on hover and is not printed inline.
+
+..  code-block:: rst
+
+    :abbr:`LIFO (last-in, first-out)`
+
+How it looks:
+    :abbr:`LIFO (last-in, first-out)`
+
+..  index:: reST roles; path
+..  _text-roles-path:
+
+`:path:`
+========
+
+Refers to a directory or folder path, as opposed to a specific file. Use
+:ref:`:file: <text-roles-file>` instead when the path ends in a file name.
+
+..  code-block:: rst
 
-..  tabs::
+    The extension stores its data in :path:`public/fileadmin`.
 
-    ..  group-tab:: Output
+How it looks:
+    The extension stores its data in :path:`public/fileadmin`.
 
-        ..  include:: _snippets/_text-roles.rst.txt
+..  index:: reST roles; file
+..  _text-roles-file:
 
-    ..  group-tab:: reST
+`:file:`
+========
 
-        ..  literalinclude:: _snippets/_text-roles.rst.txt
+Refers to a specific file, including its name and, if helpful, its path.
+Use :ref:`:path: <text-roles-path>` instead when referring to a directory
+rather than a single file.
+
+..  code-block:: rst
+
+    Edit :file:`config/system/settings.php` to change the setting.
+
+How it looks:
+    Edit :file:`config/system/settings.php` to change the setting.
+
+..  index:: reST roles; issue
+..  _text-roles-issue:
+
+`:issue:`
+=========
+
+Links to an issue on `TYPO3 Forge <https://forge.typo3.org>`_ by its
+number. By default the link text is `forge#<number>`; pass a custom link
+text before the number in angle brackets to show different text instead.
+
+..  code-block:: rst
+
+    See also :issue:`102056` or :issue:`this issue <99508>`.
+
+How it looks:
+    See also :issue:`102056` or :issue:`this issue <99508>`.
+
+..  _text-roles-elsewhere:
+
+More text roles, documented on their own pages
+==============================================
+
+A few text roles are common enough, or involved enough, to have a full
+page to themselves rather than a short entry here:
+
+*   :rst:`:guilabel:` for GUI labels — backend modules, tabs, buttons,
+    fields — and click paths through them, and :rst:`:kbd:` for keyboard
+    shortcuts — see
+    `Referring to GUI elements and keystrokes <https://docs.typo3.org/permalink/h2document:rest-refer-to-gui-elements>`_.
+*   :rst:`:composer:` and :rst:`:t3ext:` for linking Composer packages and
+    TER extensions — see
+    `Linking Composer packages and TYPO3 extensions <https://docs.typo3.org/permalink/h2document:linking-extensions>`_.
+*   :rst:`:t3src:` for linking source files of the TYPO3 Core — see
+    `Linking source files of the TYPO3 Core <https://docs.typo3.org/permalink/h2document:linking-core-source>`_.
+*   :rst:`:php:`, :rst:`:php-short:`, :rst:`:typoscript:` and other code
+    roles with an infobox — see
+    `Inline code with or without infoboxes <https://docs.typo3.org/permalink/h2document:inline-code>`_.
+
+..  seealso::
+
+    *   `Basic inline markup (bold, italic etc.) <https://docs.typo3.org/permalink/h2document:rest-bold-italic>`_
+    *   `Links in ReStructured Text <https://docs.typo3.org/permalink/h2document:how-to-document-hyperlinks>`_
+    *   `Docutils: Interpreted Text Roles <http://docutils.sourceforge.io/docs/ref/rst/roles.html>`_