If ``:start-after:`` is used, make ``:lines:`` relative (close: #3412)

1 files changed, 16 insertions, 5 deletions

diff --git a/doc/markup/code.rst b/doc/markup/code.rst
index ff0f692fa..677deb30f 100644
--- a/doc/markup/code.rst
+++ b/doc/markup/code.rst
@@ -182,13 +182,24 @@ Includes
    ``start-after`` is given as a string option, only lines that follow the first
    line containing that string are included.  If ``end-before`` is given as a
    string option, only lines that precede the first lines containing that string
-   are included. If used in combination with ``lines``, make sure the latter
-   allows the lines (whose count start at ``1`` at top of file) containing the
-   looked-for strings.
+   are included.
+
+   With lines selected this way it is still possible to use ``lines``, the
+   numbers being now interpreted relative to the already selected lines.
+
+   .. versionchanged:: 1.5.3
+      Formerly, ``lines`` still referred to the included file, and it was
+      needed that those lines containing the requested strings were among
+      the allowed ones.
+
+   When lines have been selected in any of the ways described above, the
+   line numbers in ``emphasize-lines`` refer to the selection, with the
+   line count starting at ``1``.
 
    When specifying particular parts of a file to display, it can be useful to
-   display exactly which lines are being presented.
-   This can be done using the ``lineno-match`` option.
+   display the original line numbers. This can be done using the
+   ``lineno-match`` option, which is however allowed only when the selection
+   consists of contiguous lines.
 
    You can prepend and/or append a line to the included code, using the
    ``prepend`` and ``append`` option, respectively.  This is useful e.g. for