Add support for the shift modifier.

Because keyboard layouts vary, the shift-modifier `<s-…>` is only supported
for special keys (like `<up>` and `<home>`) and for ASCII lowercase where
we assume the shift-modifier just produces the matching uppercase character.
Even that's not universally true, since in Turkish `i` and `I` are not an
uppercase/lowercase pair, but Kakoune's default keyboard mappings already
assume en-US mappings for mnemonic purposes.

Mappings of the form `<s-x>` are normalized to `<X>` when `x` is an ASCII
character. `<backtab>` is removed, since we can now say `<s-tab>`.

2 files changed, 25 insertions, 22 deletions

diff --git a/doc/pages/keys.asciidoc b/doc/pages/keys.asciidoc
index 8de96aa7..7b988b05 100644
--- a/doc/pages/keys.asciidoc
+++ b/doc/pages/keys.asciidoc
@@ -6,8 +6,8 @@ Usual keys are written using their ascii character, including capital
 keys. Non printable keys use an alternate name, written between *<*
 and *>*, such as *<esc>* or *<del>*. Modified keys are written between
 *<* and *>* as well, with the modifier specified as either *c* for
-Control, or *a* for Alt, followed by a *-* and the key (either its
-name or ascii character), for example *<c-x>*, *<a-space>*, *<c-a-w>*.
+Control, *a* for Alt, or *s* for Shift, followed by a *-* and the key (either
+its name or ascii character), for example *<c-x>*, *<a-space>*, *<c-a-w>*.
 
 In order to bind some keys to arbitrary ones, refer to <<mapping#,`:doc mapping`>>
 
@@ -95,18 +95,20 @@ it when pasting text.
 == Movement
 
 'word' is a sequence of alphanumeric characters or underscore, and 'WORD'
-is a sequence of non whitespace characters
+is a sequence of non whitespace characters. Generally, a movement on it own
+will move the selection to cover the text moved over, while holding down
+the Shift modifier and moving will extend the selection instead.
 
-*h*::
+*h*, *<left>*::
     select the character on the left of selection end
 
-*j*::
+*j*, *<down>*::
     select the character below the selection end
 
-*k*::
+*k*, *<up>*::
     select the character above the selection end
 
-*l*::
+*l*, *<right>*::
     select the character on the right of selection end
 
 *w*::
@@ -134,16 +136,10 @@ is a sequence of non whitespace characters
     select to matching character, see the `matching_pairs` option
     in <<options#,`:doc options`>>
 
-*M*::
-    extend selection to matching character
-
 *x*::
     select line on which selection end lies (or next line when end lies
     on an end-of-line)
 
-*X*::
-    similar to *x*, except the current selection is extended
-
 *<a-x>*::
     expand selections to contain full lines (including end-of-lines)
 
@@ -154,10 +150,10 @@ is a sequence of non whitespace characters
 *%*::
     select whole buffer
 
-*<a-h>*::
+*<a-h>*, *<home>*::
     select to line begin
 
-*<a-l>*::
+*<a-l>*, *<end>*::
     select to line end
 
 */*::
@@ -696,7 +692,7 @@ The following keys are recognized by this mode to help edition.
 *<tab>*::
     select next completion candidate
 
-*<backtab>*::
+*<s-tab>*::
     select previous completion candidate
 
 *<c-r>*::
diff --git a/doc/pages/mapping.asciidoc b/doc/pages/mapping.asciidoc
index 3ebc62c2..c21bd90b 100644
--- a/doc/pages/mapping.asciidoc
+++ b/doc/pages/mapping.asciidoc
@@ -65,15 +65,20 @@ be used:
     Keys can also be wrapped in angle-brackets for consistency
     with the non-alphabetic keys below.
 
-*X*, *<X>*::
-    Holding down Shift while pressing the *x* key.
-
 *<c-x>*::
     Holding down Control while pressing the *x* key.
 
 *<a-x>*::
     Holding down Alt while pressing the *x* key.
 
+*<s-x>*, *X*, *<X>*, *<s-X>*::
+    Holding down Shift while pressing the *x* key.
+    *<s-x>*, *<s-X>* and *<X>* are treated as the same key. The *s-* modifier
+    only works with ASCII letters and cannot be used with other printable keys
+    (non-ASCII letters, digits, punctuation) because their shift behaviour
+    depends on your keyboard layout. The *s-* modifier _can_ be used with
+    special keys like *<up>* and *<tab>*.
+
 *<c-a-x>*::
     Holding down Control and Alt while pressing the *x* key.
 
@@ -92,9 +97,6 @@ be used:
 *<tab>*::
     The Tab key.
 
-*<backtab>*::
-    The reverse-tab key. This is Shift-Tab on most keyboards.
-
 *<backspace>*::
     The Backspace (delete to the left) key.
 
@@ -110,3 +112,8 @@ be used:
 
 *<f1>*, *<f2>*, ...*<f12>*::
     Function keys.
+
+NOTE: Although Kakoune allows many key combinations to be mapped, not every
+possible combination can be triggered. For example, due to limitations in
+the way terminals handle control characters, mappings like *<c-s-a>* are
+unlikely to work in Kakoune's terminal UI.