From 03c8d8244f616c85b51cad354616ecfd453e0072 Mon Sep 17 00:00:00 2001
From: Ulyssa <git@ulyssa.dev>
Date: Thu, 11 Apr 2024 22:49:29 -0700
Subject: [PATCH] Better describe opening identifiers under cursors

---
 src/keybindings.md   | 98 +++++++++++++++++++++++---------------------
 src/layout/README.md | 12 ++++++
 src/layout/tabs.md   |  2 +-
 3 files changed, 64 insertions(+), 48 deletions(-)

diff --git a/src/keybindings.md b/src/keybindings.md
index b04122f..d582f8f 100644
--- a/src/keybindings.md
+++ b/src/keybindings.md
@@ -2,10 +2,10 @@
 
 ## iamb keybindings
 
-| Modes           | Keybinding        | Aliases        | Help                                |
-| --------------- | ----------------- | -------------- | ----------------------------------- |
-| Normal, Visual  | `<C-W>m`          | `<C-W><C-M>`   | See [Message Scrollback]            |
-| Normal, Visual  | `<C-W>z`          | `<C-W><C-Z>`   | See [Organizing Windows]            |
+| Modes           | Keybinding        | Aliases        | Help                                          |
+| --------------- | ----------------- | -------------- | --------------------------------------------- |
+| Normal, Visual  | `<C-W>m`          | `<C-W><C-M>`   | See [Message Scrollback]                      |
+| Normal, Visual  | `<C-W>z`          | `<C-W><C-Z>`   | See [Organizing Windows]                      |
 
 ## Vim keybindings
 
@@ -13,49 +13,52 @@ Note that this is not a complete list of all Vim keybindings available within
 __iamb__, but just some of those referenced and explained throughout this
 documentation.
 
-| Modes           | Keybinding        | Aliases        | Help                                |
-| -----           | ---------------   | -------------- | ----------------------------------- |
-| Normal          | `gt`              | `<C-PageDown>` | See [Switching Tabs]                |
-| Normal          | `gT`              | `<C-PageUp>`   | See [Switching Tabs]                |
-| Normal          | `m{a-z}`          |                | See [Message Scrollback]            |
-| Normal          | `n`               |                | See [Message Scrollback]            |
-| Normal          | `N`               |                | See [Message Scrollback]            |
-| Normal          | `o`               |                | See [Sending]                       |
-| Normal          | `O`               |                | See [Sending]                       |
-| Normal          | `yy`              |                | See [Message Scrollback]            |
-| Normal          | `Y`               |                | See [Message Scrollback]            |
-| Normal          | `'{a-z}`          |                | See [Message Scrollback]            |
-| Normal          | `/`               |                | See [Message Scrollback]            |
-| Normal          | `?`               |                | See [Message Scrollback]            |
-| Normal, Visual  | `<C-B>`           | `<PageUp>`     | See [Message Scrollback]            |
-| Normal, Visual  | `<C-E>`           |                | See [Message Scrollback]            |
-| Normal, Visual  | `<C-F>`           | `<PageDown>`   | See [Message Scrollback]            |
-| Normal, Visual  | `<C-D>`           |                | See [Message Scrollback]            |
-| Normal          | `<C-I>`           | `<Tab>`        | See [Switching Windows]             |
-| Insert          | `<C-N>`           |                | See [Sending]                       |
-| Normal          | `<C-O>`           |                | See [Switching Windows]             |
-| Insert          | `<C-P>`           |                | See [Sending]                       |
-| Normal, Visual  | `<C-U>`           |                | See [Message Scrollback]            |
-| Normal, Visual  | `<C-W>f`          | `<C-W><C-F>`   | See [Opening Tabs]                  |
-| Normal, Visual  | `<C-W>h`          | `<C-W><C-H>`   | See [Switching Windows]             |
-| Normal, Visual  | `<C-W>H`          |                | See [Organizing Windows]            |
-| Normal, Visual  | `<C-W>j`          | `<C-W><C-J>`   | See [Switching Windows]             |
-| Normal, Visual  | `<C-W>J`          |                | See [Organizing Windows]            |
-| Normal, Visual  | `<C-W>k`          | `<C-W><C-K>`   | See [Switching Windows]             |
-| Normal, Visual  | `<C-W>K`          |                | See [Organizing Windows]            |
-| Normal, Visual  | `<C-W>l`          | `<C-W<C-L>`    | See [Switching Windows]             |
-| Normal, Visual  | `<C-W>L`          |                | See [Organizing Windows]            |
-| Normal, Visual  | `<C-W>o`          | `<C-W><C-O>`   | See [Closing Windows]               |
-| Normal, Visual  | `<C-W>q`          | `<C-W><C-Q>`   | See [Closing Windows]               |
-| Normal, Visual  | `<C-W>s`          | `<C-W><C-S>`   | See [Opening Windows]               |
-| Normal, Visual  | `<C-W>T`          |                | See [Organizing Windows]            |
-| Normal, Visual  | `<C-W>v`          | `<C-W><C-V>`   | See [Opening Windows]               |
-| Normal, Visual  | `<C-W>-`          |                | See [Resizing Windows]              |
-| Normal, Visual  | `<C-W>+`          |                | See [Resizing Windows]              |
-| Normal, Visual  | `<C-W><`          |                | See [Resizing Windows]              |
-| Normal, Visual  | `<C-W>>`          |                | See [Resizing Windows]              |
-| Normal, Visual  | `<C-W>=`          |                | See [Resizing Windows]              |
-| Normal, Visual  | `<C-Y>`           |                | See [Message Scrollback]            |
+| Modes           | Keybinding        | Aliases        | Help                                          |
+| -----           | ---------------   | -------------- | --------------------------------------------- |
+| Normal, Visual  | `gf`              |                | See [Following Matrix IDs]                    |
+| Normal          | `gt`              | `<C-PageDown>` | See [Switching Tabs]                          |
+| Normal          | `gT`              | `<C-PageUp>`   | See [Switching Tabs]                          |
+| Normal          | `m{a-z}`          |                | See [Message Scrollback]                      |
+| Normal          | `n`               |                | See [Message Scrollback]                      |
+| Normal          | `N`               |                | See [Message Scrollback]                      |
+| Normal          | `o`               |                | See [Sending]                                 |
+| Normal          | `O`               |                | See [Sending]                                 |
+| Normal          | `yy`              |                | See [Message Scrollback]                      |
+| Normal          | `Y`               |                | See [Message Scrollback]                      |
+| Normal          | `'{a-z}`          |                | See [Message Scrollback]                      |
+| Normal          | `/`               |                | See [Message Scrollback]                      |
+| Normal          | `?`               |                | See [Message Scrollback]                      |
+| Normal, Visual  | `<C-B>`           | `<PageUp>`     | See [Message Scrollback]                      |
+| Normal, Visual  | `<C-E>`           |                | See [Message Scrollback]                      |
+| Normal, Visual  | `<C-F>`           | `<PageDown>`   | See [Message Scrollback]                      |
+| Normal, Visual  | `<C-D>`           |                | See [Message Scrollback]                      |
+| Normal          | `<C-I>`           | `<Tab>`        | See [Switching Windows]                       |
+| Normal          | `<C-L>`           |                | Force the window to redraw                    |
+| Insert          | `<C-N>`           |                | See [Sending]                                 |
+| Normal          | `<C-O>`           |                | See [Switching Windows]                       |
+| Insert          | `<C-P>`           |                | See [Sending]                                 |
+| Normal, Visual  | `<C-U>`           |                | See [Message Scrollback]                      |
+| Normal, Visual  | `<C-W>f`          | `<C-W><C-F>`   | See [Following Matrix IDs]                    |
+| Normal, Visual  | `<C-W>gf`         |                | See [Following Matrix IDs] and [Opening Tabs] |
+| Normal, Visual  | `<C-W>h`          | `<C-W><C-H>`   | See [Switching Windows]                       |
+| Normal, Visual  | `<C-W>H`          |                | See [Organizing Windows]                      |
+| Normal, Visual  | `<C-W>j`          | `<C-W><C-J>`   | See [Switching Windows]                       |
+| Normal, Visual  | `<C-W>J`          |                | See [Organizing Windows]                      |
+| Normal, Visual  | `<C-W>k`          | `<C-W><C-K>`   | See [Switching Windows]                       |
+| Normal, Visual  | `<C-W>K`          |                | See [Organizing Windows]                      |
+| Normal, Visual  | `<C-W>l`          | `<C-W<C-L>`    | See [Switching Windows]                       |
+| Normal, Visual  | `<C-W>L`          |                | See [Organizing Windows]                      |
+| Normal, Visual  | `<C-W>o`          | `<C-W><C-O>`   | See [Closing Windows]                         |
+| Normal, Visual  | `<C-W>q`          | `<C-W><C-Q>`   | See [Closing Windows]                         |
+| Normal, Visual  | `<C-W>s`          | `<C-W><C-S>`   | See [Opening Windows]                         |
+| Normal, Visual  | `<C-W>T`          |                | See [Organizing Windows]                      |
+| Normal, Visual  | `<C-W>v`          | `<C-W><C-V>`   | See [Opening Windows]                         |
+| Normal, Visual  | `<C-W>-`          |                | See [Resizing Windows]                        |
+| Normal, Visual  | `<C-W>+`          |                | See [Resizing Windows]                        |
+| Normal, Visual  | `<C-W><`          |                | See [Resizing Windows]                        |
+| Normal, Visual  | `<C-W>>`          |                | See [Resizing Windows]                        |
+| Normal, Visual  | `<C-W>=`          |                | See [Resizing Windows]                        |
+| Normal, Visual  | `<C-Y>`           |                | See [Message Scrollback]                      |
 
 <style>
 table {
@@ -76,6 +79,7 @@ table th:nth-of-type(4) {
 </style>
 
 [Closing Windows]: ./layout/windows.md#closing-windows
+[Following Matrix IDs]: ./layout/index.md#following-matrix-ids
 [Message Scrollback]: ./messages/#message-scrollback
 [Opening Tabs]: ./layout/tabs.md#opening-tabs
 [Opening Windows]: ./layout/windows.md#opening-windows
diff --git a/src/layout/README.md b/src/layout/README.md
index 534b407..2aaf562 100644
--- a/src/layout/README.md
+++ b/src/layout/README.md
@@ -1 +1,13 @@
 # Screen Navigation
+
+## Following Matrix IDs
+
+When your cursor is placed on top of a room, space, or user identifier (or an
+item for them when when [browsing][Browsing] lists of rooms, spaces, or users),
+you can open a window for it using:
+
+- `gf` to open in the current window
+- `<C-W>f` to open a new window split for the identifier
+- `<C-W>gf` to open a new tab for the identifier
+
+[Browsing]: ../rooms/browsing.md
diff --git a/src/layout/tabs.md b/src/layout/tabs.md
index bf575ff..ea647c1 100644
--- a/src/layout/tabs.md
+++ b/src/layout/tabs.md
@@ -22,7 +22,7 @@ The above command is equivalent to running:
 :tabedit #watercooler:example.com`
 ```
 
-You can also press `<C-W>f` while navigating a list of rooms and users to open it
+You can also press `<C-W>gf` while navigating a list of rooms and users to open it
 in a new tab instead.
 
 ## Switching Tabs