Increase KEYTIMEOUT; warn of issues if it's too brief

Fixes #13

README.md

@@ -19,24 +19,28 @@ etc. `<Esc>` or `<C-[>` quickly switches into NORMAL mode (`vicmd`).
 
 ### Surround Bindings for ZSH text objects
 
-ZSH has support for text objects since 5.0.8. This plugin adds the suggested
-bindings to use surround-type objects. For example, when in NORMAL mode with
-the cursor inside a double-quoted string, type `ci"` to change the contents
-of the string. Or type `cs"(` to change the quotes to parentheses. Type
-`ds(` to remove the parentheses. Type `ys2W]` to surround the following two
-Words with brackets.
+ZSH has support for text objects since 5.0.8. This plugin adds the
+[suggested bindings][] to use surround-type objects. For example, when in
+NORMAL mode with the cursor inside a double-quoted string, type `ci"` to
+change the contents of the string. Or type `cs"(` to change the quotes to
+parentheses. Type `ds(` to remove the parentheses. Type `ys2W]` to surround
+the following two Words with brackets.
 
 In visual mode, type `a[` to select the surrounding bracketed text
 (including the brackets), or type `i'` to select the text within single
 quotes. Type `S<` to put angle brackets around the selected text.
 
+[suggested bindings]: https://sourceforge.net/p/zsh/code/ci/master/tree/Functions/Zle/surround
+
 ### Mode-sensitive cursor styling
 
 Change the color and shape of the terminal cursor with:
 
-    MODE_CURSOR_VICMD="green block"
-    MODE_CURSOR_VIINS="#20d08a blinking bar"
-    MODE_CURSOR_SEARCH="#ff00ff steady underline"
+```zsh
+MODE_CURSOR_VICMD="green block"
+MODE_CURSOR_VIINS="#20d08a blinking bar"
+MODE_CURSOR_SEARCH="#ff00ff steady underline"
+```
 
 Use X11 color names or `#RRGGBB` notation for colors. The recognized
 style words are `steady`, `blinking`, `block`, `underline` and `bar`.
@@ -100,11 +104,26 @@ for `MODE_INDICATOR_VICMD` if nothing else is set.
 The `$VIM_MODE_KEYMAP` variable is set to `viins`, `vicmd`, `replace`,
 `isearch`, `visual` or `vline` for easy inspection from other plugins.
 
+## Compatibility
+
+This plugin uses features added in ZSH 5.3 (`add-zle-hook-widget`, etc.).
+
+This plugin sets `KEYTIMEOUT` to a reasonably short duration. If you set it
+to `1`, as in many examples on the net, it has been known to cause some
+subtle problems. If you have issues, try bumping this up to see if they go
+away. Please file a report if the current setting is too brief for you.
+
 ## Bugs
 
 If you find this doesn't work with your terminal, your plugins, your
 settings or your version of ZSH, please [open an issue][issues]. If
-it clobbers some setting that it shouldn't, please file a report.
+it clobbers some setting that it shouldn't, please open an issue.
+
+It is usually helpful to create a clean `.zshrc` that only contains
+`source ~/path-to/zsh-vim-mode/zsh-vim-mode.plugin.zsh`. If your
+issue disappears, then please start adding back items from your
+configuration until you find one that causes the problem. Put that test
+`.zshrc` in the bug report. Thanks!
 
 [issues]: https://github.com/softmoth/zsh-vim-mode/issues
 

zsh-vim-mode.plugin.zsh

@@ -7,7 +7,9 @@ bindkey -v
 #${(%):-%x}_debug () { print -r "$(date) $@" >> /tmp/zsh-debug-vim-mode.log 2>&1 }
 
 # Don't wait too long after <Esc> to see if it's an arrow / function key
-export KEYTIMEOUT=5
+# Warning: Setting this too low can break some zsh functionality, eg:
+#     https://github.com/zsh-users/zsh-autosuggestions/issues/254#issuecomment-345175735
+export KEYTIMEOUT=30
 
 
 # Special keys {{{1