From 45c01c2109b1c6c1f7728c64f6800c6670425ea5 Mon Sep 17 00:00:00 2001 From: Tim Allen Date: Sun, 21 May 2023 20:14:56 +1000 Subject: [PATCH] Document the new key, and too while we're at it. Sometimes we get people asking why can't be mapped. It should be mentioned in the `:help mapping` documentation, along with any other unmappable keys. --- doc/pages/keys.asciidoc | 20 ++++++++++++++++++++ doc/pages/mapping.asciidoc | 3 +++ 2 files changed, 23 insertions(+) diff --git a/doc/pages/keys.asciidoc b/doc/pages/keys.asciidoc index 408e729d..84ed4260 100644 --- a/doc/pages/keys.asciidoc +++ b/doc/pages/keys.asciidoc @@ -825,3 +825,23 @@ The following keys are recognized by this mode to help with editing **:: enter default `user mode` to access custom commands (See <>) + +== Cancelling operations + +These keys are used to cancel long-running operations, either inside +Kakoune or outside it. Because they are intended as a safety mechanism +when something goes wrong, these keys are handled very early on in +Kakoune's input processing, and therefore cannot be remapped in any mode. + +**:: + Stop any external processes. If you ever see Kakoune display a message + like "waiting for shell command to finish", this key will stop + that command so you can regain control of Kakoune. + Technically, this key causes Kakoune to send the SIGINT signal + to its entire process group. + +**:: + Cancel a long-running Kakoune operation, such as a regex search on a + very large file. This also clears Kakoune's input buffer, so any + commands that were waiting for the long-running operation to complete + will also be cancelled. diff --git a/doc/pages/mapping.asciidoc b/doc/pages/mapping.asciidoc index 0ba142c4..5bfb9585 100644 --- a/doc/pages/mapping.asciidoc +++ b/doc/pages/mapping.asciidoc @@ -144,6 +144,9 @@ possible combination can be triggered. For example, due to limitations in the way terminals handle control characters, mappings like ** are unlikely to work in Kakoune's terminal UI. +Some keys, like `` and ``, cannot be remapped because they are +used to cancel operations. See <>. + == Default mappings Some mappings exist by default in the global scope: