Add documentation for surround

3 files changed, 40 insertions, 3 deletions

diff --git a/book/src/keymap.md b/book/src/keymap.md
index 1e159f81..58dcc5fb 100644
--- a/book/src/keymap.md
+++ b/book/src/keymap.md
@@ -21,7 +21,6 @@
 | `F`          | Find previous char                                                         |
 | `Home`       | Move to the start of the line                                              |
 | `End`        | Move to the end of the line                                                |
-| `m`          | Jump to matching bracket                                                   |
 | `PageUp`     | Move page up                                                               |
 | `PageDown`   | Move page down                                                             |
 | `Ctrl-u`     | Move half page up                                                          |
@@ -30,6 +29,7 @@
 | `Ctrl-o`     | Jump backward on the jumplist                                              |
 | `v`          | Enter [select (extend) mode](#select--extend-mode)                         |
 | `g`          | Enter [goto mode](#goto-mode)                                              |
+| `m`          | Enter [match mode](#match-mode)
 | `:`          | Enter command mode                                                         |
 | `z`          | Enter [view mode](#view-mode)                                              |
 | `Ctrl-w`     | Enter [window mode](#window-mode) (maybe will be remove for spc w w later) |
@@ -70,7 +70,7 @@
 | `Alt-;`  | Flip selection cursor and anchor                                  |
 | `%`      | Select entire file                                                |
 | `x`      | Select current line, if already selected, extend to next line     |
-| ``       | Expand selection to parent syntax node TODO: pick a key           |
+|          | Expand selection to parent syntax node TODO: pick a key           |
 | `J`      | join lines inside selection                                       |
 | `K`      | keep selections matching the regex TODO: overlapped by hover help |
 | `Space`  | keep only the primary selection TODO: overlapped by space mode    |
@@ -144,6 +144,18 @@ Jumps to various locations.
 | `i`   | Go to implementation                             |
 | `a`   | Go to the last accessed/alternate file           |
 
+## Match mode
+
+Enter this mode using `m` from normal mode. See the relavant section
+in [Usage](./usage.md#surround) for an explanation about surround usage.
+
+| Key              | Description                                     |
+| -----            | -----------                                     |
+| `m`              | Goto matching bracket                           |
+| `s` `<char>`     | Surround current selection with `<char>`        |
+| `r` `<from><to>` | Replace surround character `<from>` with `<to>` |
+| `d` `<char>`     | Delete surround character `<char>`              |
+
 ## Object mode
 
 TODO: Mappings for selecting syntax nodes (a superset of `[`).
diff --git a/book/src/usage.md b/book/src/usage.md
index 8f04b05a..e6bd60e2 100644
--- a/book/src/usage.md
+++ b/book/src/usage.md
@@ -1 +1,26 @@
 # Usage
+
+(Currently not fully documented, see the [keymappings](./keymap.md) list for more.)
+
+## Surround
+
+Functionality similar to [vim-surround](https://github.com/tpope/vim-surround) is built into
+helix. The keymappings have been inspired from [vim-sandwich](https://github.com/machakann/vim-sandwich):
+
+![surround demo](https://user-images.githubusercontent.com/23398472/122865801-97073180-d344-11eb-8142-8f43809982c6.gif)
+
+- `ms` - Add surround characters
+- `mr` - Replace surround characters
+- `md` - Delete surround characters
+
+`ms` acts on a selection, so select the text first and use `ms<char>`. `mr` and `md` work
+on the closest pairs found and selections are not required; use counts to act in outer pairs.
+
+It can also act on multiple seletions (yay!). For example, to change every occurance of `(use)` to `[use]`:
+
+- `%` to select the whole file
+- `s` to split the selections on a search term
+- Input `use` and hit Enter
+- `mr([` to replace the parens with square brackets
+
+Multiple characters are currently not supported, but planned.
diff --git a/helix-term/src/commands.rs b/helix-term/src/commands.rs
index 6cf99927..59aa25ee 100644
--- a/helix-term/src/commands.rs
+++ b/helix-term/src/commands.rs
@@ -3324,7 +3324,7 @@ fn surround(cx: &mut Context) {
             cx.count = count;
             match ch {
                 'm' => match_brackets(cx),
-                'a' => surround_add(cx),
+                's' => surround_add(cx),
                 'r' => surround_replace(cx),
                 'd' => {
                     surround_delete(cx);