Document inter-dependencies between optional terminal features

- document that we currently require "cursor position report" if
  either of both click_events or XTGETTCAP+indn is implemented.
  One of the following patches will remove this requirement.
- document properly that scrollback-push currently only works
  when XTGETTCAP+indn is implemented. There are still a few terminals
  that don't support SCROLL UP, for example the Linux Console,
  and there is no better way to find out if it's supported.

CHANGELOG.rst

@@ -71,9 +71,11 @@ New or improved bindings
 - :kbd:`ctrl-z` (undo) after executing a command will restore the previous cursor position instead of placing the cursor at the end of the command line.
 - The OSC 133 prompt marking feature has learned about kitty's ``click_events=1`` flag, which allows moving fish's cursor by clicking in the command line,
   and selecting pager items (:issue:`10932`).
-- :kbd:`ctrl-l` now pushes all text located above the prompt to the terminal's scrollback, before clearing and redrawing the screen (via a new special input function ``scrollback-push``).
+- :kbd:`ctrl-l` now pushes all text located above the prompt to the terminal's scrollback,
-  For compatibility with terminals that do not provide the scroll-forward command,
+  via a new special input function :ref:`scrollback-push <special-input-functions-scrollback-push>`,
-  this is only enabled by default if the terminal advertises support for the ``indn`` capability via the XTGETTCAP protocol.
+  before redrawing the screen as usual.
+  For compatibility with terminals that do not provide ECMA-48's ``SCROLL UP`` command,
+  this function is only enabled if the terminal advertises support for that via :ref:`XTGETTCAP <term-compat-xtgettcap>`.
 - Vi mode has learned :kbd:`ctrl-a` (increment) and :kbd:`ctrl-x` (decrement) (:issue:`11570`).
 
 Completions

doc_src/cmds/bind.rst

@@ -183,9 +183,14 @@ The following special input functions are available:
 ``clear-screen``
     clears the screen and redraws the prompt.
 
+.. _special-input-functions-scrollback-push:
+
 ``scrollback-push``
     pushes earlier output to the terminal scrollback, positioning the prompt at the top.
 
+    For compatibility with terminals that do not provide the ECMA-48 ``SCROLL UP`` command,
+    this command does nothing unless the terminal advertises support for that command via :ref:`XTGETTCAP <term-compat-xtgettcap>`.
+
 ``complete``
     guess the remainder of the current token
 

doc_src/terminal-compatibility.rst

@@ -189,17 +189,31 @@ Optional Commands
      - Su
      - Reset underline color to the default (follow the foreground color).
      - kitty
-   * - ``\e[ Ps S``
+   * - .. _term-compat-indn:
+
+       ``\e[ Ps S``
      - indn
-     - Scroll forward Ps lines.
+     - Scroll up Ps lines (aka ``SU`` but terminfo calls it "scroll forward")
-     -
+       This enables the :ref:`scrollback-push <special-input-functions-scrollback-push>` special input function which is used by :kbd:`ctrl-l`.
+     - ECMA-48
    * - ``\e[= Ps u``, ``\e[? Ps u``
      - n/a
      - Enable the kitty keyboard protocol.
      - kitty
-   * - ``\e[6n``
+   * - .. _term-compat-cursor-position-report:
+
+       ``\e[6n``
      - n/a
      - Request cursor position report.
+       The response must be of the form ``\e[ Ps ; Ps R``
+       where the first parameter is the row number
+       and the second parameter is the column number.
+       Both start at 1.
+
+       This is required for terminals that either
+
+       - implement the OSC 133 :ref:`click_events <term-compat-osc-133>` feature.
+       - advertise the :ref:`indn <term-compat-indn>` capability via :ref:`XTGETTCAP <term-compat-xtgettcap>`
      - VT100
    * - ``\e[ \x20 q``
      - Se
@@ -265,11 +279,13 @@ Optional Commands
      -
      - Copy to clipboard (OSC 52).
      - XTerm
-   * - .. _click-events:
+   * - .. _term-compat-osc-133:
 
        ``\e]133;A; click_events=1\x07``
      -
      - Mark prompt start (OSC 133), with kitty's ``click_events`` extension.
+       If ``click_events`` is implemented,
+       the :ref:`cursor position reporting <term-compat-cursor-position-report>` feature is required.
      - FinalTerm, kitty
    * - ``\e]133;C; cmdline_url= Pt \x07``
      -
@@ -279,8 +295,17 @@ Optional Commands
      -
      - Mark command end (OSC 133);  Ps is the exit status.
      - FinalTerm
-   * - ``\eP+q Pt \e\\``
+   * - .. _term-compat-xtgettcap:
+
+        ``\eP+q Pt \e\\``
      -
-     - Request terminfo capability (XTGETTCAP). The parameter is the capability's hex-encoded terminfo code.
+     - Request terminfo capability (XTGETTCAP).
-       Specifically, fish asks for the ``indn`` string capability. At the time of writing string capabilities are supported by kitty and foot.
+       The parameter is the capability's hex-encoded terminfo code.
-     - XTerm, kitty, foot
+       To advertise a capability, the response must of the form
+       ``\eP1+q Pt \e\\`` or ``\eP1+q Pt = Pt \e\\``.
+       In either variant the first parameter must be the hex-encoded terminfo code.
+       The second variant's second parameter is ignored.
+
+       Currently, fish only queries the :ref:`indn <term-compat-indn>` string capability.
+     - XTerm (but without string capabilities), kitty;
+       also adopted by foot, wezterm, contour, ghostty