diff --git a/doc/DOCUMENTATION.md b/doc/DOCUMENTATION.md
index 7ea9300a0..795e5dca3 100644
--- a/doc/DOCUMENTATION.md
+++ b/doc/DOCUMENTATION.md
@@ -851,7 +851,7 @@ is **guaranteed** to never conflict with `Spacemacs` defaults key bindings.
## Escaping
`Spacemacs` uses [evil-escape][] to easily switch between `insert state` and
-`normal state` with the key chord `fd`.
+`normal state` by quickly pressing the `fd` keys.
The choice of `fd` was made to be able to use the same sequence to escape from
"everything" in Emacs:
@@ -877,6 +877,10 @@ to `jj` (it is important set the variable in `dotspacemacs/init`):
(setq-default evil-escape-key-sequence "jj"))
```
+**Note:** Although `jj` or `jk` are popular choices of vim users, these key
+sequences are not optimal for `Spacemacs`. Indeed it is very easy in
+`visual state` to press quickly `jj` and inadvertently escape to `normal state`.
+
## Executing Vim, Emacs and shell commands
Command | Key Binding
diff --git a/spacemacs/extensions/evil-escape/README.md b/spacemacs/extensions/evil-escape/README.md
index 070ab09ad..43402d0c7 100644
--- a/spacemacs/extensions/evil-escape/README.md
+++ b/spacemacs/extensions/evil-escape/README.md
@@ -11,6 +11,7 @@
- [Customization](#customization)
- [Key sequence](#key-sequence)
- [Delay between keys](#delay-between-keys)
+ - [Limitations](#limitations)
@@ -84,4 +85,52 @@ composed with the two same characters it is recommended to set the delay to
**Note:** The variable `evil-escape-delay` must be set before requiring
`evil-escape`.
+## Limitations
+
+Due to the current implementation only the following characters can be used
+as the first character of the key sequence:
+
+| Keys |
+|:----------:|
+|b|
+|B|
+|e|
+|E|
+|f|
+|F|
+|G|
+|h|
+|H|
+|j|
+|k|
+|l|
+| |
+|K|
+|L|
+|M|
+|n|
+|N|
+|t|
+|T|
+|w|
+|W|
+|{|
+|}|
+|#|
+|%|
+|`|
+|'|
+|(|
+|)|
+|*|
+|,|
+|/|
+|;|
+|?|
+|||
+|^|
+|+|
+|_|
+|-|
+
[MELPA]: http://melpa.org/
diff --git a/spacemacs/extensions/evil-escape/evil-escape.el b/spacemacs/extensions/evil-escape/evil-escape.el
index 59cf16c88..929689542 100644
--- a/spacemacs/extensions/evil-escape/evil-escape.el
+++ b/spacemacs/extensions/evil-escape/evil-escape.el
@@ -5,7 +5,7 @@
;; Author: Sylvain Benner
;; Keywords: convenience editing evil
;; Created: 22 Oct 2014
-;; Version: 2.05
+;; Version: 2.06
;; Package-Requires: ((emacs "24") (evil "1.0.9"))
;; URL: https://github.com/syl20bnr/evil-escape
@@ -128,13 +128,16 @@ with a key sequence."
`:delete-func FUNCTION'
Specify the delete function to call when deleting the first key."
- (let ((shadowed-func (plist-get properties :shadowed-func))
- (insert-func (plist-get properties :insert-func))
- (delete-func (plist-get properties :delete-func)))
+ (let* ((shadowed-func (plist-get properties :shadowed-func))
+ (evil-func-props (when shadowed-func
+ (evil-get-command-properties shadowed-func)))
+ (insert-func (plist-get properties :insert-func))
+ (delete-func (plist-get properties :delete-func)))
`(progn
(define-key ,map ,(evil-escape--first-key)
(evil-define-motion ,(evil-escape--escape-function-symbol from)
(count)
+ ,@evil-func-props
;; called by the user
(if (called-interactively-p 'interactive)
(evil-escape--escape ,evil-escape-key-sequence