docs: More on key timeout, key chord limitations

doc_src/cmds/bind.rst

@@ -388,4 +388,6 @@ The escape key is a special case, because it can be used standalone as a real ke
 
 Holding alt and something else also typically sends escape, for example holding alt+a will send an escape character and then an "a".
 
-So the escape character has its own timeout configured with ``fish_escape_delay_ms``.
+So the escape character has its own timeout configured with :envvar:`fish_escape_delay_ms`.
+
+See also :ref:`Key sequences`.

doc_src/interactive.rst

@@ -548,6 +548,8 @@ If you use :ref:`vi bindings <vi-mode>`, note that ``bind`` will by default bind
 
   bind --mode insert \cc 'commandline -r ""'
 
+.. _interactive-key-sequences:
+
 Key sequences
 """""""""""""
 
@@ -564,14 +566,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

@@ -1538,6 +1538,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.