A new protocol extension to unscroll the screen

See https://gitlab.freedesktop.org/terminal-wg/specifications/-/issues/30

docs/changelog.rst

@@ -7,6 +7,10 @@ To update |kitty|, :doc:`follow the instructions <binary>`.
 0.20.2 [future]
 ----------------------
 
+- A new protocol extension to :ref:`unscroll <unscroll>` text from the
+  scrollback buffer onto the screen. Useful, for example, to restore
+  the screen after showing completions below the shell prompt.
+
 - Linux: Fix binary kitty builds not able to load fonts in WOFF2 format
   (:iss:`3506`)
 

docs/protocol-extensions.rst

@@ -157,6 +157,37 @@ protocol extension, it can be disabled by specifying ``no-append`` to the
 :opt:`clipboard_control` setting.
 
 
+.. _unscroll:
+
+Unscrolling the screen
+-----------------------
+
+This is a small extension to the `SD (Pan up) escape code
+<https://vt100.net/docs/vt510-rm/SD.html>`_ from the VT-420 terminal. The
+``SD`` escape code normally causes the text on screen to scroll down by the
+specified number of lines, with empty lines appearing at the top of the screen.
+This extension allows the new lines to be filled in from the scrollback buffer
+instead of being blank.
+
+The motivation for this is that many modern shells will show completions in a
+block of lines under the cursor, this causes some of the on-screen text to be
+lost even after the completion is completed, because it has scrolled off
+screen. This escape code allows that text to be restored.
+
+The syntax of the escape code is identical to that of ``SD`` except that it has
+a trailing ``+`` modifier. This is legal under the `ECMA 48 standard
+<https://www.ecma-international.org/publications-and-standards/standards/ecma-48/>`_
+and unused for any other purpose as far as I can tell. So for example, to
+unscroll three lines, the escape code would be::
+
+    CSI 3 + T
+
+See `discussion here
+<https://gitlab.freedesktop.org/terminal-wg/specifications/-/issues/30>`_.
+
+.. versionadded:: 0.20.2
+
+
 .. _desktop_notifications: