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.

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.
-       Specifically, fish asks for the ``indn`` string capability. At the time of writing string capabilities are supported by kitty and foot.
-     - XTerm, kitty, foot
+     - Request terminfo capability (XTGETTCAP).
+       The parameter is the capability's hex-encoded terminfo code.
+       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