From 86a1f0177ca734e0ce66f4e55c41eda306f1adbb Mon Sep 17 00:00:00 2001
From: Michael Davis <mcarsondavis@gmail.com>
Date: Sat, 6 May 2023 13:31:58 -0500
Subject: [PATCH] book: Document default and special registers

---
 book/src/usage.md | 26 +++++++++++++++++++++-----
 1 file changed, 21 insertions(+), 5 deletions(-)

diff --git a/book/src/usage.md b/book/src/usage.md
index 3c48e306..e392e5e6 100644
--- a/book/src/usage.md
+++ b/book/src/usage.md
@@ -37,19 +37,35 @@ If a register is selected before invoking a change or delete command, the select
 - `"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
+### Default registers
+
+Commands that use registers, like yank (`y`), use a default register if none is specified.
+These registers are used as defaults:
 
 | Register character | Contains              |
 | ---                | ---                   |
 | `/`                | Last search           |
 | `:`                | Last executed command |
 | `"`                | Last yanked text      |
-| `_`                | Black hole            |
+| `@`                | Last recorded macro   |
 
-The system clipboard is not directly supported by a special register. Instead, special commands and keybindings are provided. Refer to the
-[key map](keymap.md#space-mode) for more details.
+### Special registers
 
-The black hole register is a no-op register, meaning that no data will be read or written to it.
+Some registers have special behavior when read from and written to.
+
+| Register character | When read              | When written             |
+| ---                | ---                    | ---                      |
+| `_`                | No values are returned | All values are discarded |
+| `#`                | Selection indices (first selection is `1`, second is `2`, etc.) | This register is not writable |
+| `.`                | Contents of the current selections | This register is not writable |
+| `%`                | Name of the current file | This register is not writable |
+| `*`                | Reads from the system clipboard | Joins and yanks to the system clipboard |
+| `+`                | Reads from the primary clipboard | Joins and yanks to the primary clipboard |
+
+When yanking multiple selections to the clipboard registers, the selections
+are joined with newlines. Pasting from these registers will paste multiple
+selections if the clipboard was last yanked to by the Helix session. Otherwise
+the clipboard contents are pasted as one selection.
 
 ## Surround