From dd4ffd0256d05240be1a6324829cdf2827fced80 Mon Sep 17 00:00:00 2001
From: Lina Wolf <48202465+linawolf@users.noreply.github.com>
Date: Thu, 1 Oct 2026 07:48:52 +0200
Subject: [PATCH] [TASK] Improve the documentation of code blocks with line
 numbers and folding

It was unclear how to count the lines of a code block that a text
refers to, especially when some of its lines are folded.

Assisted-by: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: Lina Wolf
---
 .../ReStructuredText/Code/Codeblocks.rst      | 36 ++++++++++++++++++-
 .../Code/_snippets/_line-numbers.rst.txt      | 25 +++++++++++++
 2 files changed, 60 insertions(+), 1 deletion(-)
 create mode 100644 Documentation/Reference/ReStructuredText/Code/_snippets/_line-numbers.rst.txt

diff --git a/Documentation/Reference/ReStructuredText/Code/Codeblocks.rst b/Documentation/Reference/ReStructuredText/Code/Codeblocks.rst
index cc6792de..1d4d066a 100644
--- a/Documentation/Reference/ReStructuredText/Code/Codeblocks.rst
+++ b/Documentation/Reference/ReStructuredText/Code/Codeblocks.rst
@@ -113,7 +113,9 @@ will fail.
             :name: <reference-label>
 
     :rst:`linenos`
-        Show line numbers.
+        Show line numbers. Use it whenever the text refers to a line by its
+        number, so the reader can see that number instead of counting, see
+        `Referring to a line by its number <https://docs.typo3.org/permalink/h2document:codeblocks-line-numbers>`_.
 
     :rst:`lineno-start`
         Start line numbers with <start-number>.
@@ -295,6 +297,38 @@ is the point. Where the block works on its own, show that part alone and mark
 the caption as an excerpt, see
 `Captioning a part of a file <https://docs.typo3.org/permalink/h2document:codeblocks-caption-excerpt>`_.
 
+..  _codeblocks-line-numbers:
+
+Referring to a line by its number
+---------------------------------
+
+When the text refers to a line by its number, show the line numbers with
+:rst:`:linenos:` and use the number the reader sees beside the line. Do not
+count the lines yourself.
+
+The numbers count the lines of the source, one per line break. A folded line
+keeps its number, so the first visible line below is line 10, not line 1. A
+line too long for the screen wraps but is still one line.
+
+Emphasize the lines the text is about, so the reader finds them without
+counting:
+
+..  tabs::
+
+    ..  group-tab:: Source (rst)
+
+        ..  literalinclude:: _snippets/_line-numbers.rst.txt
+            :caption: Documentation/MyDocs.rst
+
+    ..  group-tab:: Output
+
+        ..  include:: _snippets/_line-numbers.rst.txt
+
+A line number goes out of date as soon as a line is added above it. Name what
+is in the line as well, like "the attribute in line 12", so the sentence still
+leads the reader to the right line, and check the numbers whenever you change
+the code.
+
 ..  _writing-rest-codeblocks-with-syntax-highlighting-examples-code-blocks:
 
 Use code blocks containing diffs
diff --git a/Documentation/Reference/ReStructuredText/Code/_snippets/_line-numbers.rst.txt b/Documentation/Reference/ReStructuredText/Code/_snippets/_line-numbers.rst.txt
new file mode 100644
index 00000000..fc06f6a6
--- /dev/null
+++ b/Documentation/Reference/ReStructuredText/Code/_snippets/_line-numbers.rst.txt
@@ -0,0 +1,25 @@
+..  code-block:: php
+    :caption: EXT:my_extension/Classes/EventListener/MyListener.php
+    :linenos:
+    :emphasize-lines: 12-13
+
+    <?php
+
+    declare(strict_types=1);
+
+    namespace MyVendor\MyExtension\EventListener;
+
+    use TYPO3\CMS\Core\Attribute\AsEventListener;
+    use TYPO3\CMS\Core\Resource\Event\AfterFileAddedEvent;
+
+    final class MyListener
+    {
+      #[AsEventListener]
+      public function __invoke(AfterFileAddedEvent $event): void
+      {
+        // Your code here
+      }
+    }
+
+The attribute in line 12 registers the method as an event listener. The type
+of its argument in line 13 tells TYPO3 which event the method listens to.