aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorDaniel Eklöf <daniel@ekloef.se>2022-01-14 12:33:16 +0000
committerDaniel Eklöf <daniel@ekloef.se>2022-01-14 12:41:17 +0000
commitda9d732855035f3b0b6fd8922f31679aef631927 (patch)
treeac70a8ea880e229a68e7650063b3ae0f33c29298
parentxtgettcap: switch from a table based internal structure, to a single char array (diff)
readme: document XTGETTCAP behavior
-rw-r--r--README.md49
1 files changed, 49 insertions, 0 deletions
diff --git a/README.md b/README.md
index 1be27ab6..16600d59 100644
--- a/README.md
+++ b/README.md
@@ -30,6 +30,7 @@ The fast, lightweight and minimalistic Wayland terminal emulator.
1. [DPI and font size](#dpi-and-font-size)
1. [Supported OSCs](#supported-oscs)
1. [Programmatically checking if running in foot](#programmatically-checking-if-running-in-foot)
+1. [XTGETTCAP](#xtgettcap)
1. [Credits](#Credits)
1. [Bugs](#bugs)
1. [Contact](#contact)
@@ -432,6 +433,54 @@ e.g. “1.8.2” for a regular release, or “1.8.2-36-g7db8e06f” for a git
build.
+# XTGETTCAP
+
+`XTGETTCAP` is an escape sequence initially introduced by XTerm, and
+also implemented (and extended, to some degree) by Kitty.
+
+It allows querying the terminal for terminfo
+capabilities. Applications using this feature do not need to use the
+classic, file-based, terminfo definition. For example, if all
+applications used this feature, you would no longer have to install
+foot’s terminfo on remote hosts you SSH into.
+
+XTerm’s implementation (as of XTerm-370) only supports querying key
+(as in keyboard keys) capabilities, and three custom capabilities:
+
+* `TN` - terminal name
+* `Co` - number of colors (alias for the `colors` capability)
+* `RGB` - number of bits per color channel (different semantics from
+ the `RGB` capability in file-based terminfo definitions!).
+
+Kitty has extended this, and also supports querying all integer and
+string capabilities.
+
+Foot supports this, and extends it even further, to also include
+boolean capabilities. This means foot’s entire terminfo can be queried
+via `XTGETTCAP`.
+
+Note that both Kitty and foot handles **responses** to
+multi-capability queries slightly differently, compared to XTerm.
+
+XTerm will send a single DCS reply, with `;`-separated
+capability/value pairs. There are a couple of issues with this:
+
+* The success/fail flag in the beginning of the response is always `1`
+ (success), unless the very **first** queried capability is invalid.
+* XTerm will not respond **at all** to an invalid capability, unless
+ it’s the first one in the `XTGETTCAP` query.
+* XTerm will end the response at the first invalid capability.
+
+In other words, if you send a large multi-capability query, you will
+only get responses up to, but not including, the first invalid
+capability. All subsequent capabilities will be dropped.
+
+Kitty and foot on the other hand, send one DCS response for **each**
+capability in the multi query. This allows us to send a proper
+success/fail flag for each queried capability. Responses for **all**
+queried capabilities are **always** sent. No queries are ever dropped.
+
+
# Credits
* [Ordoviz](https://codeberg.org/Ordoviz), for designing and