Move FAQ to main documentation

1 files changed, 122 insertions, 5 deletions

diff --git a/doc/build/texinfo/evil.texi b/doc/build/texinfo/evil.texi
index 05a7a35..a7a1bc3 100644
--- a/doc/build/texinfo/evil.texi
+++ b/doc/build/texinfo/evil.texi
@@ -59,6 +59,7 @@ Copyright @copyright{} 2011-2019, Eivind Fonn, Frank Fischer, Vegard Øye
 * Keymaps:: 
 * Hooks:: 
 * Extension:: 
+* Frequently Asked Questions:: 
 * Internals:: 
 * The GNU Free Documentation License:: 
 * Emacs lisp functions and variables:: 
@@ -97,6 +98,11 @@ Extension
 * Range types:: 
 * States:: 
 
+Frequently Asked Questions
+
+* Problems with the escape key in the terminal:: 
+* Underscore is not a word character:: 
+
 Internals
 
 * Command properties:: 
@@ -1069,7 +1075,7 @@ During the hook execution, the variables @code{evil-next-state} and
 @code{evil-previous-state} contain information about the states being
 switched to and from, respectively.
 
-@node Extension,Internals,Hooks,Top
+@node Extension,Frequently Asked Questions,Hooks,Top
 @anchor{extension doc}@anchor{59}@anchor{extension extension}@anchor{5a}
 @chapter Extension
 
@@ -1429,8 +1435,119 @@ For example:
              "Disabling test state.")))
 @end example
 
-@node Internals,The GNU Free Documentation License,Extension,Top
-@anchor{internals doc}@anchor{60}@anchor{internals internals}@anchor{61}
+@node Frequently Asked Questions,Internals,Extension,Top
+@anchor{faq doc}@anchor{60}@anchor{faq frequently-asked-questions}@anchor{61}
+@chapter Frequently Asked Questions
+
+
+@menu
+* Problems with the escape key in the terminal:: 
+* Underscore is not a word character:: 
+
+@end menu
+
+@node Problems with the escape key in the terminal,Underscore is not a word character,,Frequently Asked Questions
+@anchor{faq problems-with-the-escape-key-in-the-terminal}@anchor{62}
+@section Problems with the escape key in the terminal
+
+
+A common problem when using Evil in terminal mode is a certain delay
+after pressing the escape key. Even more, when pressing the escape key
+followed quickly by another key the command is recognized as
+@code{M-<key>} instead of two separate keys: @code{ESC} followed by
+@code{<key>}. In fact, it is perfectly valid to simulate
+@code{M-<key>} by pressing @code{ESC <key>} quickly (but see below).
+
+The reason for this is that in terminal mode a key sequence involving
+the meta key (or alt key) always generates a so called “escape
+sequence”, i.e. a sequence of two events sent to Emacs, the first
+being @code{ESC} and the second the key pressed simultaneously. The
+problem is that pressing the escape key itself also generates the
+@code{ESC} event. Thus, if Emacs (and therefore Evil) receives an
+@code{ESC} event there is no way to tell whether the escape key has
+been pressed (and no further event will arrive) or a @code{M-<key>}
+combination has been pressed (and the @code{<key>} event will arrive
+soon). In order to distinguish both situations Evil does the
+following. After receiving an @code{ESC} event Evil waits for a short
+time period (specified by the variable @ref{17,,evil-esc-delay}
+which defaults to 0.01 seconds) for another event. If no other event
+arrives Evil assumes that the plain escape key has been pressed,
+otherwise it assumes a @code{M-<key>} combination has been pressed and
+combines the @code{ESC} event with the second one. Because a
+@code{M-<key>} sequence usually generates both events in very quick
+succession, 0.01 seconds are usually enough and the delay is hardly
+noticeable by the user.
+
+If you use a terminal multiplexer like @emph{tmux} or @emph{screen} the
+situation may be worse. These multiplexers have exactly the same
+problem recognizing @code{M-<key>} sequences and often introduce their
+own delay for the @code{ESC} key. There is no way for Evil to
+influence this delay. In order to reduce it you must reconfigure your
+terminal multiplexer.
+
+Note that this problem should not arise when using Evil in graphical
+mode. The reason is that in this case the escape key itself generates
+a different command, namely @code{escape} (a symbol) and hence Evil can
+distinguish whether the escape key or a @code{M-<key>} combination has
+been pressed. But this also implies that pressing @code{ESC} followed
+by <key> cannot be used to simulate @code{M-<key>} in graphical mode!
+
+@node Underscore is not a word character,,Problems with the escape key in the terminal,Frequently Asked Questions
+@anchor{faq underscore-is-not-a-word-character}@anchor{63}
+@section Underscore is not a word character
+
+
+An underscore @code{_} is a word character in Vim. This means that word
+motions like @code{w} skip over underlines in a sequence of letters as
+if it was a letter itself.  In contrast, in Evil the underscore is
+often a non-word character like operators, e.g. @code{+}.
+
+The reason is that Evil uses Emacs’ definition of a word and this
+definition does often not include the underscore. In Emacs word
+characters are determined by the syntax-class of the buffer. The
+syntax-class usually depends on the major-mode of this buffer. This
+has the advantage that the definition of a “word” may be adapted to
+the particular type of document being edited. Evil uses Emacs’
+definition and does not simply use Vim’s definition in order to be
+consistent with other Emacs functions. For example, word characters
+are exactly those characters that are matched by the regular
+expression character class @code{[:word:]}.
+
+If you want the underscore to be recognised as word character, you can
+modify its entry in the syntax-table:
+
+@example
+(modify-syntax-entry ?_ "w")
+@end example
+
+This gives the underscore the ‘word’ syntax class. You can use a
+mode-hook to modify the syntax-table in all buffers of some mode,
+e.g.:
+
+@example
+(add-hook 'c-mode-common-hook
+          (lambda () (modify-syntax-entry ?_ "w")))
+@end example
+
+This gives the underscore the word syntax-class in all C-like buffers.
+
+Alternatively, many find that motion by @emph{symbols} is more convenient
+than motion by @emph{words}.  One way to make word motions operate as
+symbol motions is to alias the @code{evil-word} @emph{thing} @footnote{@w{(1)} 
+Many of Evil’s text objects and motions are defined in
+terms of the @emph{thingatpt} library, which in this case are defined
+entirely in terms of @code{forward-THING} functions.  Thus aliasing
+one to another should make all motions and text objects implemented
+in terms of that @emph{thing} behave the same.
+} to
+the @code{evil-symbol} thing:
+
+@example
+(defalias 'forward-evil-word 'forward-evil-symbol)
+@end example
+
+@node Internals,The GNU Free Documentation License,Frequently Asked Questions,Top
+@anchor{internals doc}@anchor{64}@anchor{internals internals}@anchor{65}
 @chapter Internals
 
 
@@ -1440,7 +1557,7 @@ For example:
 @end menu
 
 @node Command properties,,,Internals
-@anchor{internals command-properties}@anchor{62}
+@anchor{internals command-properties}@anchor{66}
 @section Command properties
 
 
@@ -1513,7 +1630,7 @@ keystrokes.
 @end deffn
 
 @node The GNU Free Documentation License,Emacs lisp functions and variables,Internals,Top
-@anchor{license doc}@anchor{63}@anchor{license the-gnu-free-documentation-license}@anchor{64}
+@anchor{license doc}@anchor{67}@anchor{license the-gnu-free-documentation-license}@anchor{68}
 @chapter The GNU Free Documentation License