docs: More on key timeout, key chord limitations

(cherry picked from commit 496fc03b98)

doc_src/cmds/bind.rst

@@ -380,3 +380,6 @@ The escape key can be used standalone, for example, to switch from insertion mod
 Holding alt and something else also typically sends escape, for example holding alt+a will send an escape character and then an "a".
 
 fish waits for a period after receiving the escape character, to determine whether it is standalone or part of an escape sequence. While waiting, additional key presses make the escape key behave as a meta key. If no other key presses come in, it is handled as a standalone escape. The waiting period is set to 30 milliseconds (0.03 seconds). It can be configured by setting the ``fish_escape_delay_ms`` variable to a value between 10 and 5000 ms. This can be a universal variable that you set once from an interactive session.
+So the escape character has its own timeout configured with :envvar:`fish_escape_delay_ms`.
+
+See also :ref:`Key sequences`.

doc_src/interactive.rst

@@ -537,6 +537,12 @@ If you change your mind on a binding and want to go back to fish's default, you
 
 Fish remembers its preset bindings and so it will take effect again. This saves you from having to remember what it was before and add it again yourself.
 
+If you use :ref:`vi bindings <vi-mode>`, note that ``bind`` will by default bind keys in :ref:`command mode <vi-mode-command>`. To bind something in :ref:`insert mode <vi-mode-insert>`::
+
+  bind --mode insert \cc 'commandline -r ""'
+
+.. _interactive-key-sequences:
+
 Key sequences
 """""""""""""
 
@@ -553,14 +559,25 @@ In these cases, :doc:`fish_key_reader <cmds/fish_key_reader>` can tell you how t
   Press a key:
   bind \e\[C 'do something'
 
-Note that some key combinations are indistinguishable or unbindable. For instance control-i *is the same* as the tab key. This is a terminal limitation that fish can't do anything about.
+Note that some key combinations are indistinguishable or unbindable. For instance control-i *is the same* as the tab key. This is a terminal limitation that fish can't do anything about. When ``fish_key_reader`` prints the same sequence for two different keys, then that is because your terminal sends the same sequence for them.
 
-Also, :kbd:`Escape` is the same thing as :kbd:`Alt` in a terminal. To distinguish between pressing :kbd:`Escape` and then another key, and pressing :kbd:`Alt` and that key (or an escape sequence the key sends), fish waits for a certain time after seeing an escape character. This is configurable via the ``fish_escape_delay_ms`` variable.
+Also, :kbd:`Escape` is the same thing as :kbd:`Alt` in a terminal. To distinguish between pressing :kbd:`Escape` and then another key, and pressing :kbd:`Alt` and that key (or an escape sequence the key sends), fish waits for a certain time after seeing an escape character. This is configurable via the :envvar:`fish_escape_delay_ms` variable.
 
 If you want to be able to press :kbd:`Escape` and then a character and have it count as :kbd:`Alt`\ +\ that character, set it to a higher value, e.g.::
 
   set -g fish_escape_delay_ms 100
 
+Similarly, to disambiguate *other* keypresses where you've bound a subsequence and a longer sequence, fish has :envvar:`fish_sequence_key_delay_ms`::
+
+  # This binds "jk" to switch to normal mode in vi-mode.
+  # If you kept it like that, every time you press "j",
+  # fish would wait for a "k" or other key to disambiguate
+  bind -M insert -m default jk cancel repaint-mode
+
+  # After setting this, fish only waits 200ms for the "k",
+  # or decides to treat the "j" as a separate sequence, inserting it.
+  set -g fish_sequence_key_delay_ms 200
+
 .. _killring:
 
 Copy and paste (Kill Ring)

doc_src/language.rst

@@ -1449,6 +1449,10 @@ You can change the settings of fish by changing the values of certain variables.
 
    sets how long fish waits for another key after seeing an escape, to distinguish pressing the escape key from the start of an escape sequence. The default is 30ms. Increasing it increases the latency but allows pressing escape instead of alt for alt+character bindings. For more information, see :ref:`the chapter in the bind documentation <cmd-bind-escape>`.
 
+.. envvar:: fish_sequence_key_delay_ms
+
+   sets how long fish waits for another key after seeing a key that is part of a longer sequence, to disambiguate. For instance if you had bound ``\cx\ce`` to open an editor, fish would wait for this long in milliseconds to see a ctrl-e after a ctrl-x. If the time elapses, it will handle it as a ctrl-x (by default this would copy the current commandline to the clipboard). See also :ref:`Key sequences <interactive-key-sequences>`.
+
 .. envvar:: fish_complete_path
 
    determines where fish looks for completion. When trying to complete for a command, fish looks for files in the directories in this variable.