Merge change for lengthened and configurable escape key timeout

2 files changed, 16 insertions, 6 deletions

diff --git a/doc_src/bind.txt b/doc_src/bind.txt
index b5074ac2..f72e0cde 100644
--- a/doc_src/bind.txt
+++ b/doc_src/bind.txt
@@ -131,3 +131,12 @@ set -g fish_key_bindings fish_vi_key_bindings
 bind -M insert \cc kill-whole-line force-repaint
 \endfish
 Turns on Vi key bindings and rebinds @key{Control,C} to clear the input line.
+
+
+\subsection special-case-escape Special Case: The escape Character
+
+Since the escape key (or character) plays two distinct roles it poses a special challenge for fish. In its first role it stands by itself. In Vi mode, for example, escape is used to switch from insert to normal (aka command) mode. In its second role escape is used as a <a href="https://en.wikipedia.org/wiki/Meta_key">"meta" key</a> where it is only the beginning of some longer character sequence. Coming back to the Vi mode example, sometimes fish is expected to realize that the escape key should be regarded as a meta key, meaning that the escape character is part of a multi-char sequence. Function keys (e.g., F1, F2, etc...) and arrow keys are common cases of multi-char sequences that begin with the escape character. Custom bindings can also be defined that begin with an escape character. Obviously, fish is not supposed to exit insert mode when the escape is part of a longer character sequence.
+
+To be able distinguish between these two roles fish has to wait after it sees an escape character. In this waiting period any additional key presses make the escape key behave as a meta key. Otherwise, it remains an isolated escape key press. The waiting period is set to 300 milliseconds (0.3 seconds) in the default key bindings and 10 milliseconds in the vi key bindings. It can be configured by setting the `fish_escape_delay_ms` variable to a value between 10 and 5000 ms. It is recommended that this be a universal variable that you set once from an interactive session.
+
+Note: fish versions up thru 2.2.0 used a default of 10 ms and provided no way to configure it. That effectively made it impossible to use escape as a meta key.
diff --git a/doc_src/index.hdr.in b/doc_src/index.hdr.in
index b948d088..dd6355db 100644
--- a/doc_src/index.hdr.in
+++ b/doc_src/index.hdr.in
@@ -755,17 +755,18 @@ All arrays are one-dimensional and cannot contain other arrays, although it is p
 
 \subsection variables-special Special variables
 
-The user can change the settings of `fish` by changing the values of
-certain environment variables.
-
-- `BROWSER`, the user's preferred web browser. If this variable is set, fish will use the specified browser instead of the system default browser to display the fish documentation.
-
-- `CDPATH`, an array of directories in which to search for the new directory for the `cd` builtin. By default, the fish configuration defines `CDPATH` to be a universal variable with the values `.` and `~`.
+The user can change the settings of `fish` by changing the values of certain variables.
 
 - A large number of variable starting with the prefixes `fish_color` and `fish_pager_color.` See <a href='#variables-color'>Variables for changing highlighting colors</a> for more information.
 
 - `fish_greeting`, the greeting message printed on startup.
 
+- `fish_escape_delay_ms` overrides the default timeout of 300ms (default key bindings) or 10ms (vi key bindings) after seeing an escape character before giving up on matching a key binding. See the documentation for the <a href='bind.html#special-case-escape'>bind</a> builtin command. This delay facilitates using escape as a meta key.
+
+- `BROWSER`, the user's preferred web browser. If this variable is set, fish will use the specified browser instead of the system default browser to display the fish documentation.
+
+- `CDPATH`, an array of directories in which to search for the new directory for the `cd` builtin. By default, the fish configuration defines `CDPATH` to be a universal variable with the values `.` and `~`.
+
 - `LANG`, `LC_ALL`, `LC_COLLATE`, `LC_CTYPE`, `LC_MESSAGES`, `LC_MONETARY`, `LC_NUMERIC` and `LC_TIME` set the language option for the shell and subprograms. See the section <a href='#variables-locale'>Locale variables</a> for more information.
 
 - `fish_user_paths`, an array of directories that are prepended to `PATH`. This can be a universal variable.