document the escape timeout

2 files changed, 20 insertions, 6 deletions

diff --git a/doc_src/bind.txt b/doc_src/bind.txt
index 8a099eb3..0ac2c32b 100644
--- a/doc_src/bind.txt
+++ b/doc_src/bind.txt
@@ -131,3 +131,14 @@ 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
+
+The escape key (or character) poses a special challenge for fish. Consider Vi mode. On the one hand you want to be able to press the escape key to switch from insert to normal mode. On the other hand you want fish to recognize multi-char sequences that begin with an escape character (which is what the function and arrow-keys send) without having the escape character switch to normal mode. So fish needs to wait a little bit to see if the escape introduces a multi-char sequence but not so long that you're left wondering if fish will ever switch to Vi normal mode after you press escape.
+
+Even in emacs mode (the default key bindings) you don't want fish to wait forever for more characters when it sees an escape character to determine if the sequence matches a key binding. On the other hand you want fish to wait a little bit of time so that you can use the escape key as a "meta" key.
+
+The solution is for fish to wait, by default, 500 ms (0.5 seconds) after it sees an escape character for another character that might represent a valid binding. This is the Gnu readline library default escape timeout. 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 while in emacs mode.
diff --git a/doc_src/index.hdr.in b/doc_src/index.hdr.in
index e20c8cf0..b9e3f8fc 100644
--- a/doc_src/index.hdr.in
+++ b/doc_src/index.hdr.in
@@ -753,17 +753,20 @@ 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` to override the default timeout of 500 ms after
+  seeing an escape character before giving up on matching a key binding. See
+  the documentation for the <a hread='bind.html#special-case-escape'>bind</a> builtin.
+
+- `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.