[TASK] Improve documentation on headline anchors (#448)

* [TASK] Improve documentation on headline anchors * [TASK] Bugfix: do not use interlinks to the own repository * Update Documentation/Reference/ReStructuredText/Content/Links.rst Co-authored-by: Sandra Erbel <[email protected]> * Update Documentation/Reference/ReStructuredText/Menus/HeadlinesAndSection.rst Co-authored-by: Sandra Erbel <[email protected]> * Update Documentation/Reference/ReStructuredText/Menus/HeadlinesAndSection.rst Co-authored-by: Sandra Erbel <[email protected]> * Update Documentation/Reference/ReStructuredText/Menus/HeadlinesAndSection.rst * Update Documentation/Reference/ReStructuredText/Menus/HeadlinesAndSection.rst * Update Documentation/Reference/ReStructuredText/Menus/HeadlinesAndSection.rst Co-authored-by: Sandra Erbel <[email protected]> --------- Co-authored-by: Sandra Erbel <[email protected]>
TYPO3-Documentation · Jul 28, 2024 · 74a1d9f · 74a1d9f
1 parent 650d593
commit 74a1d9f
Show file tree

Hide file tree

Showing 5 changed files with 75 additions and 43 deletions.
diff --git a/Documentation/Howto/Migration/Index.rst b/Documentation/Howto/Migration/Index.rst
@@ -78,7 +78,7 @@ file :file:`genindex.rst` in your :file:`Documentation/` directory (if available
 
 While you could already jump in and render your documentation directly
 (see :ref:`local rendering <rendering-docs>`), we suggest to clean up the following other
-things first (:ref:`see <h2document:migrate-detailed-steps>`).
+things first (:ref:`see <migrate-detailed-steps>`).
 
 
 ..  _migrate-detailed-steps:
@@ -190,7 +190,7 @@ Use our Docker container to render your documentation locally. Read more about i
 The following list is not a requirement to utilize the PHP-based rendering, but
 follows "best practice" to make the most of your documentation project.
 One of the biggest benefits is, that this simplifies finding
-:ref:`errors <h2document:migrate-possible-errors>` in your reST syntax.
+:ref:`errors <migrate-possible-errors>` in your reST syntax.
 The :file:`Makefile` helps you to launch the local rendering described in :ref:`here <rendering-docs>`.
 You create the :file:`Makefile` in order to register the command shortcuts that you
 would use to :ref:`render your documentation locally <rendering-docs>` and also provide an entry point for further shortcuts (like testing).
@@ -259,15 +259,15 @@ Inventory link with key ... not found
 
 .. code-block:: text
 
-    [2024-03-13T12:26:40.940930+00:00] app.WARNING: Inventory link with key "h2document:rest-common-pitfalls"
+    [2024-03-13T12:26:40.940930+00:00] app.WARNING: Inventory link with key "rest-common-pitfalls"
     (rest-common-pitfalls) not found.  {"rst-file":"GeneratedExtension/Index","type":"ref","targetRef
 
 We see already that we have to go to file :file:`GeneratedExtension/Index` in the directory "Documentation".
 In there we have to delete the line which contains
 
 .. code-block:: text
 
-    * :ref:`h2document:rest-common-pitfalls`
+    * :ref:`rest-common-pitfalls`
 
 But whether we should delete the reference or not depends on the special case. In this case the whole section was removed.
 So here it is useful to delete the reference.

diff --git a/Documentation/Howto/WritingReST/CheatSheet.rst b/Documentation/Howto/WritingReST/CheatSheet.rst
@@ -3,7 +3,7 @@
 ..  ------------------------------------------------------------------------
     header label:  You can use this to create
     cross-references: To link to the next section, use :ref:`rest-cheat-sheet`
-    or :ref:`h2document:rest-cheat-sheet` from another manual
+    or :ref:`rest-cheat-sheet` from another manual
     -------------------------------------------------------------------------
 
 
@@ -126,7 +126,7 @@ Or, when cross-referencing to other manuals:
 
     :ref:`shortcut:label`
 
-:ref:`h2document:intersphinx`
+:ref:`intersphinx`
 
 
 When you are linking to another manual, make sure the
@@ -609,7 +609,7 @@ Source:
     text with a green box (as styled by our sphinx template).
     ---------------------------------------------------------------
 
-Visit :ref:`h2document:rest-admonitions` to see the available admonitions.
+Visit :ref:`rest-admonitions` to see the available admonitions.
 
 **How it looks:**
 

diff --git a/Documentation/Index.rst b/Documentation/Index.rst
@@ -50,7 +50,7 @@ reStructuredText (reST).
 
         Go tho the cheat sheet containing a quick overview on how to use reStructuredText.
 
-        ..  card-footer:: :ref:`Go to the reST Cheat sheet <h2document:rest-cheat-sheet>`
+        ..  card-footer:: :ref:`Go to the reST Cheat sheet <rest-cheat-sheet>`
             :button-style: btn btn-secondary stretched-link
 
     ..  card:: Edit on GitHub
@@ -59,7 +59,7 @@ reStructuredText (reST).
         you are reading by applying the "Edit on GitHub" workflow. All you
         need is a GitHub account.
 
-        ..  card-footer:: :ref:`How to make quick fixes <h2document:docs-contribute-github-method>`
+        ..  card-footer:: :ref:`How to make quick fixes <docs-contribute-github-method>`
             :button-style: btn btn-secondary stretched-link
 
     ..  card:: Local rendering
@@ -69,21 +69,21 @@ reStructuredText (reST).
         your changes in and it also gives you the ability to experiment and
         preview your changes locally before submitting them for approval.
 
-        ..  card-footer:: :ref:`How to work locally with documentation <h2document:docs-contribute-git-docker>`
+        ..  card-footer:: :ref:`How to work locally with documentation <docs-contribute-git-docker>`
             :button-style: btn btn-secondary stretched-link
 
     ..  card:: Extension documentation
 
         This chapter explains how to write documentation for a new extension.
 
-        ..  card-footer:: :ref:`How to document an extension <h2document:write-doc-extensions-intro>`
+        ..  card-footer:: :ref:`How to document an extension <write-doc-extensions-intro>`
             :button-style: btn btn-secondary stretched-link
 
     ..  card:: System Extensions
 
         The chapter contains information on how you can make changes to system extension documentation.
 
-        ..  card-footer:: :ref:`How to document system extensions <h2document:contribute-to-system-extension>`
+        ..  card-footer:: :ref:`How to document system extensions <contribute-to-system-extension>`
             :button-style: btn btn-secondary stretched-link
 
 ..  toctree::

diff --git a/Documentation/Reference/ReStructuredText/Content/Links.rst b/Documentation/Reference/ReStructuredText/Content/Links.rst
@@ -179,6 +179,7 @@ and any other file type like
     :t3src:`typo3/sysext/core/Resources/Private/Templates/ErrorPage/Error.html`.
 
 ..  index:: reST; Link targets
+..  _link-anchor:
 ..  _link-targets-explanation:
 ..  _explicit-link-targets:
 
@@ -201,11 +202,27 @@ Place the link anchor definition directly before the section header:
 
 ..  code-block:: rst
 
-    ..  _columns-inline:
+    ..  _inline-columns:
 
     Inline columns
     ==============
 
+Link anchors should contain alphanumeric signs plus hyphen: (`[a-z][0-9][-]`).
+All other signs are automatically transformed by the symfony
+:php:`Symfony\Component\String\Slugger\AsciiSlugger`.
+
+A recommended recipe could be:
+
+#.  Duplicate the headline
+#.  Transform to lowercase
+#.  Replace all blanks by a hyphens `-`
+#.  Remove all non-alphanumeric characters or replace them by a hyphen `-`
+#.  Add `.. _` at the beginning.
+#.  Add `:` at the end.
+
+We are currently trying to let `Fractor support <https://github.com/andreaswolf/fractor/issues/206>`
+this and other transformations.
+
 ..  index:: reST; Preventing links
 ..  _preventing-links:
 

diff --git a/Documentation/Reference/ReStructuredText/Menus/HeadlinesAndSection.rst b/Documentation/Reference/ReStructuredText/Menus/HeadlinesAndSection.rst
@@ -18,13 +18,19 @@ is split into "sections" instead. Those sections are identified by titles which
 
 1. Use underlining plus overlining with `===` for the first section title of a
     file. The first section title is the "document title" (**doctitle**) of that
-    file and will appear in the menu. Every .rst file should have a doctitle:
+    file and will appear in the menu. Every .rst file should have a title, each
+    title should have a link anchor. In :ref:`link-anchor` we describe 
+    our recommended best way how to build a link anchor in the official 
+    TYPO3 documentation. Here you see a title and a link anchor in
+    action:
 
 ..  code-block:: rst
 
-        ========
-        DocTitle
-        ========
+        ..  _doc-title:
+
+        ==============
+        Document Title
+        ==============
 
 2. Then use underlining only:
 
@@ -54,24 +60,39 @@ Example
 
 ..  code-block:: rst
 
-    ========
-    DocTitle
-    ========
+
+    ..  _document-title:
+
+    ==============
+    Document Title
+    ==============
 
     About this document ...
 
+    ..  _topic-1:
+
     Topic 1
     =======
+
     Here we go.
 
+    ..  _subtopic-1-1:
+
     Subtopic 1.1
     ------------
+
     Here we dive deeper
 
+
+    ..  _subsubtopic-1-1-1:
+
     Subsubtopic 1.1.1
     ~~~~~~~~~~~~~~~~~
+
     And this is even more specific.
 
+    ..  _topic-2:
+
     Topic 2
     =======
     ...
@@ -83,45 +104,39 @@ Syntax
 Length of Underlines
 --------------------
 
-The length of the underlines must at least have the length of the text. It
-may be longer, not shorter.
+The length of the underlines **should** have the same length like the text. It
+**should not** be longer or shorter.
 
 Example 1: This Works
 ~~~~~~~~~~~~~~~~~~~~~
 
 ..  code-block:: rst
 
+    ..  _example-1:
+
     =========
     Example 1
     =========
 
-Example 2: This Works Too
-~~~~~~~~~~~~~~~~~~~~~~~~~
+Example 2: These headlines work but do not abide to the coding guidelines
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Here we see how we should not do it. The underlines are too long or too short.
 
 ..  code-block:: rst
 
+    ..  _example-2:
+
     ==============
-    Example 1
+    Example 2
     ==============
+    
+    # Underline too long
 
-Example 3: This Does not Work
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-..  code-block:: rst
+    ..  _example-3:
 
     =======
-    Example 1
+    Example 3
     =======
-
-
-
-Additional Information
-======================
-
-*   **Docutils:** Read about `sections
-    <http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#sections>`__
-    in the Docutils documentation for the most fundamental description.
-
-*   **Sphinx** is explaining `sections
-    <http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#sections>`__
-    as well.
+    
+    # Underline too short