From 7dc6a6a6600fdfdcf2bb0b7bd1751671fb56601e Mon Sep 17 00:00:00 2001 From: Kovid Goyal Date: Tue, 19 Nov 2024 11:47:30 +0530 Subject: [PATCH] Document the miscellaneous protocol extensions kitty uses --- docs/misc-protocol.rst | 38 ++++++++++++++++++++++++++++++++++++ docs/protocol-extensions.rst | 1 + 2 files changed, 39 insertions(+) create mode 100644 docs/misc-protocol.rst diff --git a/docs/misc-protocol.rst b/docs/misc-protocol.rst new file mode 100644 index 000000000..3323909f3 --- /dev/null +++ b/docs/misc-protocol.rst @@ -0,0 +1,38 @@ +Miscellaneous protocol extensions +============================================== + +These are a few small protocol extensions kitty implements, primarily for use +by its own kitten, they are documented here for completeness. + + +Simple save/restore of all terminal modes +-------------------------------------------- + +XTerm has the XTSAVE/XTRESTORE escape codes to save and restore terminal +private modes. However, they require specifying an explicit list of modes to +save/restore. kitty extends this protocol to specify that when no modes are +specified, all side-effect free modes should be saved/restored. By side-effects +we mean things that can affect other terminal state such as cursor position or +screen contents. Examples of modes that have side effects are: `DECOM +`__ and `DECCOLM +`__. + +This allows TUI applications to easily save and restore emulator state without +needing to maintain lists of modes. + + +Independent control of bold and faint SGR properties +------------------------------------------------------- + +In common terminal usage, bold is set via SGR 1 and faint by SGR 2. However, +there is only one number to reset these attributes, SGR 22, which resets both. +There is no way to reset one and not the other. kitty uses 221 and 222 to reset +bold and faint independently. + + +kitty specific private escape codes +--------------------------------------- + +These are a family of escape codes used by kitty for various things including +remote control. They are all DCS (Device Control String) escape codes starting +with ``\x1b P @ kitty-`` (ignoring spaces present for clarity). diff --git a/docs/protocol-extensions.rst b/docs/protocol-extensions.rst index 610b691f6..52ca6cf8e 100644 --- a/docs/protocol-extensions.rst +++ b/docs/protocol-extensions.rst @@ -34,3 +34,4 @@ please do so by opening issues in the `GitHub bug tracker color-stack deccara clipboard + misc-protocol