From 796466331e7f5755bf857cc644cfce3c152a66f1 Mon Sep 17 00:00:00 2001 From: Lina Wolf <48202465+linawolf@users.noreply.github.com> Date: Wed, 31 Jul 2024 09:40:21 +0200 Subject: [PATCH] [TASK] Move rest link chapters on separate pages (#452) --- .../ReStructuredText/Content/Links.rst | 309 ------------------ .../ReStructuredText/Links/Anchors.rst | 48 +++ .../ReStructuredText/Links/Composer.rst | 32 ++ .../ReStructuredText/Links/CoreSource.rst | 24 ++ .../ReStructuredText/Links/Documentation.rst | 68 ++++ .../ReStructuredText/Links/ExampleLinks.rst | 89 +++++ .../ReStructuredText/Links/ExternalLinks.rst | 52 +++ .../ReStructuredText/Links/Index.rst | 19 ++ 8 files changed, 332 insertions(+), 309 deletions(-) delete mode 100644 Documentation/Reference/ReStructuredText/Content/Links.rst create mode 100644 Documentation/Reference/ReStructuredText/Links/Anchors.rst create mode 100644 Documentation/Reference/ReStructuredText/Links/Composer.rst create mode 100644 Documentation/Reference/ReStructuredText/Links/CoreSource.rst create mode 100644 Documentation/Reference/ReStructuredText/Links/Documentation.rst create mode 100644 Documentation/Reference/ReStructuredText/Links/ExampleLinks.rst create mode 100644 Documentation/Reference/ReStructuredText/Links/ExternalLinks.rst create mode 100644 Documentation/Reference/ReStructuredText/Links/Index.rst diff --git a/Documentation/Reference/ReStructuredText/Content/Links.rst b/Documentation/Reference/ReStructuredText/Content/Links.rst deleted file mode 100644 index 67b47ba..0000000 --- a/Documentation/Reference/ReStructuredText/Content/Links.rst +++ /dev/null @@ -1,309 +0,0 @@ -.. include:: /Includes.rst.txt -.. index:: - reST; Hyperlinks - reST; Cross referencing - reST roles; ref -.. _how-to-document-hyperlinks: - -======================== -Links & cross references -======================== - -In reStructuredText (reST) there are multiple methods to define links to -different targets. This text describes those most commonly used in TYPO3 -manuals. - -.. contents:: - -.. _rest-ref: -.. _intersphinx: - -References to TYPO3 manuals -=========================== - -You can link the following elements in any TYPO3 manual: Headlines, -:ref:`confvals ` and :ref:`phpdomain definitions `. -It is also possible to put an anchor almost anywhere and then link it. - -When an element in a manual can be linked a link symbol will appear when you -hover it: - -.. figure:: /_Images/link-headlines.png - - Hover over a headline to see if it is linkable, then click the link icon - -After you click the link icon you can copy the reST link from the modal that -appears: - -.. figure:: /_Images/link-headlines-box.png - - Copy the reST reference - -The reST code of the reference looks like this: - -.. code-block:: rst - :caption: Reference from another manual - - :ref:`Hide detail page in URL ` - -A reference has the following syntax: - -.. code-block:: plaintext - :caption: Syntax of a reST reference - - :ref:`[link_text] <[interlink]:[anchor]>` - -If you are linking within the same manual you can omit the `[interlink]:` part, -including the colon. - -.. code-block:: rst - :caption: Reference from inside the same manual - - :ref:`Hide detail page in URL ` - -If there is a warning box displayed, that the link has no anchor, you can -still link to it using a doc-reference: - -.. figure:: /_Images/link-headlines-box-warning.png - - Linking to a headline without an anchor - -The link then looks like this in reST: - -.. code-block:: rst - - :doc:`Some further explanations ` - -However such a link would not work anymore if the section was moved to another -page or if another section with the same headline was introduced. - -We suggest adding a unique link anchor to the headline to be linked to in this -case. See section :ref:`Link anchors `. - -.. index:: reST; External links -.. _external-links: - -External links -============== - -.. important:: - - Do not use this mechanism (external links) for links to sections of - the TYPO3. Use references as described in the section above: - :ref:`References to TYPO3 manuals `. - - -An URL that is mentioned within a text is automatically linked: - -.. code-block:: rst - - Lorem Ipsum Dolor https://example.org dolor sit - -The result looks like this: - -Lorem Ipsum Dolor https://example.org dolor sit - -If you want to also give the URL a distinctive link text you can use the -following syntax: - -.. code-block:: rst - - Lorem Ipsum Dolor `Example Page `__ dolor sit - -The result looks like this: - -Lorem Ipsum Dolor `Example Page `__ dolor sit - -Sometimes links can get quite long and unruly to use within the text. You can -use so called named links to separate the link definitions from the text: - -.. code-block:: rst - - Lorem Ipsum Dolor `Example Page`_ dolor sit - - .. _Example Page: https://example.org - -The result looks like this: - -Lorem Ipsum Dolor `Example Page`_ dolor sit - -.. _Example Page: https://example.org - -.. _linking-extensions: - -Linking extensions and Composer packages -======================================== - -You can use the text role :rst:`:composer:` to create an infobox with information -and links to Packagist. This way you can link to any TYPO3 extension -that is also listed on Packagist like :composer:`georgringer/news` and -:composer:`b13/container`, any TYPO3 system extension like -:composer:`typo3/cms-adminpanel` and any other Composer package like -:composer:`typo3/testing-framework`: - -.. code-block:: rst - - This way you can link to any TYPO3 extension - that is also listed on packagist like :composer:`georgringer/news` and - :composer:`b13/container`, any TYPO3 system extension like - :composer:`typo3/cms-adminpanel` and any other Composer package like - :composer:`typo3/testing-framework` - -If you want to link to the TYPO3 Extension Repository (TER) you can use the -text role :rst:`t3ext` instead and link extensions like :t3ext:`news` or -system extensions like :t3ext:`adminpanel`: - -.. code-block:: rst - - You can use the text role `t3ext` instead and link extensions like - :t3ext:`news` or system extensions like :t3ext:`adminpanel` - -.. _linking-core-source: - -Linking source files of the TYPO3 Core -====================================== - -Any file within the TYPO3 Core can be linked to their source file on GitHub using -the text role :rst:`t3src`. - -You can link classes like the -:t3src:`typo3/sysext/core/Classes/Pagination/SlidingWindowPagination.php` -and any other file type like -:t3src:`typo3/sysext/core/Resources/Private/Templates/ErrorPage/Error.html`. - -.. code-block:: rst - - You can link classes like the - :t3src:`typo3/sysext/core/Classes/Pagination/SlidingWindowPagination.php` - 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: - -Link anchors -============ - -Link anchors assign a unique name to a headline and its section. These anchors -can be used in internal references and references between TYPO3 manuals. - -As long as the anchor of a section stays the same the section can be moved to -another page or the headline can be renamed and references will still go to the -correct target. - -You can define a link anchor with a label for a section. - -In the following example, the link target :rst:`columns-inline` is assigned -to the section with the title "Inline columns". - -Place the link anchor definition directly before the section header: - -.. code-block:: rst - - .. _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 ` -this and other transformations. - -.. index:: reST; Preventing links -.. _preventing-links: - -Preventing links -================ - -Sphinx automatically converts simple URLs into links. This can be unintentional -in certain contexts, for example when using a -:ref:`hypothetical domain ` like "example.org" or -:ref:`placeholders ` instead of real query parameters -in a tutorial. -To prevent linking, the TYPO3 documentation uses the :code:`:samp:` directive -to wrap the URL. - -For example: - -.. code-block:: rst - - The TYPO3 backend can be accessed via :samp:`https://example.org/typo3` .. - -is rendered like: - -The TYPO3 backend can be accessed via :samp:`https://example.org/typo3` .. - -To emphasize parts of the URL, use curly braces: - -.. code-block:: rst - - The *route* is the "speaking URL" as a whole without the domain part, - for example :samp:`https://example.org//{}`. - -is rendered like: - -The *route* is the "speaking URL" as a whole without the domain part, -for example :samp:`https://example.org//{}`. - - -.. index:: reST; Hypothetical domains -.. _hypothetical-domains: - -Hypothetical domains -==================== - -The TYPO3 documentation uses a defined set of dummy domains when describing URLs -where the domain name does not matter, but serves as a placeholder. The defined -set is - -1. :samp:`https://example.org` -2. :samp:`https://example.com` -3. :samp:`https://example.net` - -– in this order: :samp:`https://example.org` as the preferred domain, and -:samp:`https://example.com` and :samp:`https://example.net` as alternatives if -multiple domains are required in the same context. - -Why is :samp:`https://example.com` not preferred, as common sense would have it? -Because the preference for :samp:`.org` over :samp:`.com` fits with the fact -that the TYPO3 documentation is hosted on :samp:`https://typo3.org` and the -TYPO3 Association is owning the TYPO3 GmbH. - -For explicit mention of the local development context it uses - -4. :samp:`https://example.localhost`. - -If you need additional dummy domains, use subdomains of the domains listed -above such as :samp:`https://staging.example.org` and -:samp:`https://production.example.org`. - -For example: - -.. code-block:: rst - - The class :php:`MailMessage` can be used to generate and send a mail without - using Fluid: - - .. code-block:: rst - - $mail = GeneralUtility::makeInstance(\TYPO3\CMS\Core\Mail\MailMessage::class); - $mail - ->from(new Address('john.doe@example.org', 'John Doe')) - ->to( - new Address('receiver@example.com', 'Max Mustermann'), - new Address('other@example.net') - ) diff --git a/Documentation/Reference/ReStructuredText/Links/Anchors.rst b/Documentation/Reference/ReStructuredText/Links/Anchors.rst new file mode 100644 index 0000000..5320c8d --- /dev/null +++ b/Documentation/Reference/ReStructuredText/Links/Anchors.rst @@ -0,0 +1,48 @@ +:navigation-title: Anchors +.. include:: /Includes.rst.txt + +.. index:: reST; Link targets +.. _link-anchor: +.. _link-targets-explanation: +.. _explicit-link-targets: + +============ +Link anchors +============ + +Link anchors assign a unique name to a headline and its section. These anchors +can be used in internal references and references between TYPO3 manuals. + +As long as the anchor of a section stays the same the section can be moved to +another page or the headline can be renamed and references will still go to the +correct target. + +You can define a link anchor with a label for a section. + +In the following example, the link target :rst:`columns-inline` is assigned +to the section with the title "Inline columns". + +Place the link anchor definition directly before the section header: + +.. code-block:: rst + + .. _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 ` +this and other transformations. diff --git a/Documentation/Reference/ReStructuredText/Links/Composer.rst b/Documentation/Reference/ReStructuredText/Links/Composer.rst new file mode 100644 index 0000000..8f36efe --- /dev/null +++ b/Documentation/Reference/ReStructuredText/Links/Composer.rst @@ -0,0 +1,32 @@ +:navigation-title: Composer / Extensions +.. include:: /Includes.rst.txt + +.. _linking-extensions: + +============================================== +Linking Composer packages and TYPO3 extensions +============================================== + +You can use the text role :rst:`:composer:` to create an infobox with information +and links to Packagist. This way you can link to any TYPO3 extension +that is also listed on Packagist like :composer:`georgringer/news` and +:composer:`b13/container`, any TYPO3 system extension like +:composer:`typo3/cms-adminpanel` and any other Composer package like +:composer:`typo3/testing-framework`: + +.. code-block:: rst + + This way you can link to any TYPO3 extension + that is also listed on packagist like :composer:`georgringer/news` and + :composer:`b13/container`, any TYPO3 system extension like + :composer:`typo3/cms-adminpanel` and any other Composer package like + :composer:`typo3/testing-framework` + +If you want to link to the TYPO3 Extension Repository (TER) you can use the +text role :rst:`t3ext` instead and link extensions like :t3ext:`news` or +system extensions like :t3ext:`adminpanel`: + +.. code-block:: rst + + You can use the text role `t3ext` instead and link extensions like + :t3ext:`news` or system extensions like :t3ext:`adminpanel` diff --git a/Documentation/Reference/ReStructuredText/Links/CoreSource.rst b/Documentation/Reference/ReStructuredText/Links/CoreSource.rst new file mode 100644 index 0000000..8c5c1e9 --- /dev/null +++ b/Documentation/Reference/ReStructuredText/Links/CoreSource.rst @@ -0,0 +1,24 @@ +:navigation-title: Core source +.. include:: /Includes.rst.txt + +.. _linking-core-source: + +====================================== +Linking source files of the TYPO3 Core +====================================== + +Any file within the TYPO3 Core can be linked to their source file on GitHub using +the text role :rst:`t3src`. + +You can link classes like the +:t3src:`typo3/sysext/core/Classes/Pagination/SlidingWindowPagination.php` +and any other file type like +:t3src:`typo3/sysext/core/Resources/Private/Templates/ErrorPage/Error.html`. + +.. code-block:: rst + + You can link classes like the + :t3src:`typo3/sysext/core/Classes/Pagination/SlidingWindowPagination.php` + and any other file type like + :t3src:`typo3/sysext/core/Resources/Private/Templates/ErrorPage/Error.html`. + diff --git a/Documentation/Reference/ReStructuredText/Links/Documentation.rst b/Documentation/Reference/ReStructuredText/Links/Documentation.rst new file mode 100644 index 0000000..e97408b --- /dev/null +++ b/Documentation/Reference/ReStructuredText/Links/Documentation.rst @@ -0,0 +1,68 @@ +:navigation-title: Documentation references +.. include:: /Includes.rst.txt + +.. _rest-ref: +.. _intersphinx: + +================================= +References to TYPO3 documentation +================================= + +You can link the following elements in any TYPO3 manual: Headlines, +:ref:`confvals ` and :ref:`phpdomain definitions `. +It is also possible to put an anchor almost anywhere and then link it. + +When an element in a manual can be linked a link symbol will appear when you +hover it: + +.. figure:: /_Images/link-headlines.png + + Hover over a headline to see if it is linkable, then click the link icon + +After you click the link icon you can copy the reST link from the modal that +appears: + +.. figure:: /_Images/link-headlines-box.png + + Copy the reST reference + +The reST code of the reference looks like this: + +.. code-block:: rst + :caption: Reference from another manual + + :ref:`Hide detail page in URL ` + +A reference has the following syntax: + +.. code-block:: plaintext + :caption: Syntax of a reST reference + + :ref:`[link_text] <[interlink]:[anchor]>` + +If you are linking within the same manual you can omit the `[interlink]:` part, +including the colon. + +.. code-block:: rst + :caption: Reference from inside the same manual + + :ref:`Hide detail page in URL ` + +If there is a warning box displayed, that the link has no anchor, you can +still link to it using a doc-reference: + +.. figure:: /_Images/link-headlines-box-warning.png + + Linking to a headline without an anchor + +The link then looks like this in reST: + +.. code-block:: rst + + :doc:`Some further explanations ` + +However such a link would not work anymore if the section was moved to another +page or if another section with the same headline was introduced. + +We suggest adding a unique link anchor to the headline to be linked to in this +case. See section :ref:`Link anchors `. diff --git a/Documentation/Reference/ReStructuredText/Links/ExampleLinks.rst b/Documentation/Reference/ReStructuredText/Links/ExampleLinks.rst new file mode 100644 index 0000000..280580c --- /dev/null +++ b/Documentation/Reference/ReStructuredText/Links/ExampleLinks.rst @@ -0,0 +1,89 @@ +:navigation-title: example.org +.. include:: /Includes.rst.txt + +.. index:: reST; Preventing links +.. _preventing-links: + +=========================== +Example domain: example.org +=========================== + +The renderer automatically converts simple URLs into links. This can be unintentional +in certain contexts, for example when using a +:ref:`hypothetical domain ` like "example.org" or +:ref:`placeholders ` instead of real query parameters +in a tutorial. +To prevent linking, the TYPO3 documentation uses the :code:`:samp:` directive +to wrap the URL. + +For example: + +.. code-block:: rst + + The TYPO3 backend can be accessed via :samp:`https://example.org/typo3` .. + +is rendered like: + +The TYPO3 backend can be accessed via :samp:`https://example.org/typo3` .. + +To emphasize parts of the URL, use curly braces: + +.. code-block:: rst + + The *route* is the "speaking URL" as a whole without the domain part, + for example :samp:`https://example.org//{}`. + +is rendered like: + +The *route* is the "speaking URL" as a whole without the domain part, +for example :samp:`https://example.org//{}`. + + + +.. index:: reST; Hypothetical domains +.. _hypothetical-domains: + +Hypothetical domains +==================== + +The TYPO3 documentation uses a defined set of dummy domains when describing URLs +where the domain name does not matter, but serves as a placeholder. The defined +set is + +1. :samp:`https://example.org` +2. :samp:`https://example.com` +3. :samp:`https://example.net` + +– in this order: :samp:`https://example.org` as the preferred domain, and +:samp:`https://example.com` and :samp:`https://example.net` as alternatives if +multiple domains are required in the same context. + +Why is :samp:`https://example.com` not preferred, as common sense would have it? +Because the preference for :samp:`.org` over :samp:`.com` fits with the fact +that the TYPO3 documentation is hosted on :samp:`https://typo3.org` and the +TYPO3 Association is owning the TYPO3 GmbH. + +For explicit mention of the local development context it uses + +4. :samp:`https://example.localhost`. + +If you need additional dummy domains, use subdomains of the domains listed +above such as :samp:`https://staging.example.org` and +:samp:`https://production.example.org`. + +For example: + +.. code-block:: rst + + The class :php:`MailMessage` can be used to generate and send a mail without + using Fluid: + + .. code-block:: rst + + $mail = GeneralUtility::makeInstance(\TYPO3\CMS\Core\Mail\MailMessage::class); + $mail + ->from(new Address('john.doe@example.org', 'John Doe')) + ->to( + new Address('receiver@example.com', 'Max Mustermann'), + new Address('other@example.net') + ) diff --git a/Documentation/Reference/ReStructuredText/Links/ExternalLinks.rst b/Documentation/Reference/ReStructuredText/Links/ExternalLinks.rst new file mode 100644 index 0000000..ba8359b --- /dev/null +++ b/Documentation/Reference/ReStructuredText/Links/ExternalLinks.rst @@ -0,0 +1,52 @@ +:navigation-title: External URLs +.. include:: /Includes.rst.txt + +.. index:: reST; External links +.. _external-links: + +============== +External links +============== + +.. important:: + + Do not use this mechanism (external links) for links to sections of + the TYPO3. Use references as described in the section above: + :ref:`References to TYPO3 manuals `. + + +An URL that is mentioned within a text is automatically linked: + +.. code-block:: rst + + Lorem Ipsum Dolor https://example.org dolor sit + +The result looks like this: + +Lorem Ipsum Dolor https://example.org dolor sit + +If you want to also give the URL a distinctive link text you can use the +following syntax: + +.. code-block:: rst + + Lorem Ipsum Dolor `Example Page `__ dolor sit + +The result looks like this: + +Lorem Ipsum Dolor `Example Page `__ dolor sit + +Sometimes links can get quite long and unruly to use within the text. You can +use so called named links to separate the link definitions from the text: + +.. code-block:: rst + + Lorem Ipsum Dolor `Example Page`_ dolor sit + + .. _Example Page: https://example.org + +The result looks like this: + +Lorem Ipsum Dolor `Example Page`_ dolor sit + +.. _Example Page: https://example.org diff --git a/Documentation/Reference/ReStructuredText/Links/Index.rst b/Documentation/Reference/ReStructuredText/Links/Index.rst new file mode 100644 index 0000000..af60527 --- /dev/null +++ b/Documentation/Reference/ReStructuredText/Links/Index.rst @@ -0,0 +1,19 @@ +:navigation-title: Links +.. include:: /Includes.rst.txt +.. _links: +.. _how-to-document-hyperlinks: + +========================== +Links in ReStructured Text +========================== + + +In reStructuredText (reST) there are multiple methods to define links to +different targets. The following chapter describe those most commonly used in +TYPO3 documentation. + +.. toctree:: + :glob: + :titlesonly: + + *