Add docs for registers, multi key remaps (#557)

5 files changed, 38 insertions, 2 deletions

diff --git a/book/src/SUMMARY.md b/book/src/SUMMARY.md
index 5dea3112..3fa8e067 100644
--- a/book/src/SUMMARY.md
+++ b/book/src/SUMMARY.md
@@ -2,6 +2,7 @@
 
 - [Installation](./install.md)
 - [Usage](./usage.md)
+- [Migrating from Vim](./from-vim.md)
 - [Configuration](./configuration.md)
   - [Themes](./themes.md)
   - [Keymap](./keymap.md)
diff --git a/book/src/from-vim.md b/book/src/from-vim.md
new file mode 100644
index 00000000..8e9bbac3
--- /dev/null
+++ b/book/src/from-vim.md
@@ -0,0 +1,10 @@
+# Migrating from Vim
+
+Helix's editing model is strongly inspired from vim and kakoune, and a notable
+difference from vim (and the most striking similarity to kakoune) is that Helix
+follows the `selection → action` model. This means that the whatever you are
+going to act on (a word, a paragraph, a line, etc) is selected first and the
+action itself (delete, change, yank, etc) comes second. A cursor is simply a
+single width selection.
+
+> TODO: Mention texobjects, surround, registers
diff --git a/book/src/keymap.md b/book/src/keymap.md
index 156e694d..4eb85636 100644
--- a/book/src/keymap.md
+++ b/book/src/keymap.md
@@ -59,6 +59,7 @@
 | `y`         | Yank selection                                  |
 | `p`         | Paste after selection                           |
 | `P`         | Paste before selection                          |
+| `"` `<reg>` | Select a register to yank to or paste from      |
 | `>`         | Indent selection                                |
 | `<`         | Unindent selection                              |
 | `=`         | Format selection                                |
diff --git a/book/src/remapping.md b/book/src/remapping.md
index b4f4005b..3f25e364 100644
--- a/book/src/remapping.md
+++ b/book/src/remapping.md
@@ -13,10 +13,12 @@ this:
 [keys.normal]
 a = "move_char_left" # Maps the 'a' key to the move_char_left command
 w = "move_line_up" # Maps the 'w' key move_line_up
-C-S-esc = "extend_line" # Maps Control-Shift-Escape to extend_line
+"C-S-esc" = "extend_line" # Maps Control-Shift-Escape to extend_line
+g = { a = "code_action" } # Maps `ga` to show possible code actions
 
 [keys.insert]
-A-x = "normal_mode" # Maps Alt-X to enter normal mode
+"A-x" = "normal_mode" # Maps Alt-X to enter normal mode
+j = { k = "normal_mode" } # Maps `jk` to exit insert mode
 ```
 
 Control, Shift and Alt modifiers are encoded respectively with the prefixes
diff --git a/book/src/usage.md b/book/src/usage.md
index 0458071a..9ee8634c 100644
--- a/book/src/usage.md
+++ b/book/src/usage.md
@@ -2,6 +2,28 @@
 
 (Currently not fully documented, see the [keymappings](./keymap.md) list for more.)
 
+## Registers
+
+Vim-like registers can be used to yank and store text to be pasted later. Usage is similar, with `"` being used to select a register:
+
+- `"ay` - Yank the current selection to register `a`.
+- `"op` - Paste the text in register `o` after the selection.
+
+If there is a selected register before invoking a change or delete command, the selection will be stored in the register and the action will be carried out:
+
+- `"hc` - Store the selection in register `h` and then change it (delete and enter insert mode).
+- `"md` - Store the selection in register `m` and delete it.
+
+### Special Registers
+
+| Register character | Contains              |
+| ---                | ---                   |
+| `/`                | Last search           |
+| `:`                | Last executed command |
+| `"`                | Last yanked text      |
+
+> There is no special register for copying to system clipboard, instead special commands and keybindings are provided. See the [keymap](keymap.md#space-mode) for the specifics.
+
 ## Surround
 
 Functionality similar to [vim-surround](https://github.com/tpope/vim-surround) is built into