Update documentation for tree-sitter navigation.

docs/man/commands.md

@@ -27,3 +27,4 @@ Commands are separated into three categories:
 | -------                                                 | -----------                                                                                                                  |
 | `kak-tree-sitter-req-text-objects <text-object> <mode>` | Alter every selections by matching `<text-object>` according to `<mode>`. See [the text-objects section](./Text-objects.md). |
 | `kak-tree-sitter-req-object-text-objects <text-object>` | Alter every selections by matching `<text-object>` in _object_ mode. See [the text-objects section](./Text-objects.md).      |
+| `kak-tree-sitter-req-nav <dir>`                         | Alter every selections by navigating in the `<dir>` direction. See [the navigation section](./Text-objects.md#navigation).   |

docs/man/text-objects.md

@@ -38,3 +38,38 @@ All those options are encoded as operational modes. There are many:
 - `find_prev`: select onto the previous text-object before the cursor. Similar to `<a-f>`.
 - `extend_next`: extend onto the next text-object after the cursor. Similar to `F`.
 - `extend_prev`: extend onto the previous text-object before the cursor. Similar to `<a-F>`.
+
+## Navigation
+
+Additionally to text-objects, you also get _tree-sitter-based navigation_. The way it works is by first selecting a
+node and then moving into a semantic direction.
+
+> As with regular text-objects, navigation is applied to **all selections**, not only the primary one.
+
+The following directions are currently implemented:
+
+- `parent`: parent of the current node.
+- `first_child`: first child of the current node.
+- `last_child`: last child of the current node.
+- `first_sibling`: first sibling of the current node.
+- `last_sibling`: last sibling of the current node.
+- `prev_sibling`: previous sibling of the current node. Can include cousins.
+- `next_sibling`: next sibling of the current node. Can include cousins.
+
+The `tree-sitter` user-mode contains some mappings to start experimenting with navigation (inserted with
+`--with-text-objects`).
+
+If you would rather write your own commands, you need to use the `kak-tree-sitter-req-nav <dir>` command. `<dir>` is one
+of the items described above as a string, expect for directions that can include cousins. In such a case, you need to
+turn the direction into an object with a single attribute, `cousin`, which is of type `bool`. Setting `cousin` to `true`
+will allow prev/next sibling navigation to “jump” over parents and try to go to cousins instead of direct siblings.
+
+### Navigation examples
+
+- `kak-tree-sitter-req-nav '"parent"'`: go to the parent of the current selections.
+- `kak-tree-sitter-req-nav "'{ ""prev_sibling"": { ""cousin"": false } }'"`: go to the previous sibling.
+
+### Bonus: sticky navigation
+
+A handy `tree-sitter-nav-sticky` user-mode is available to navigate without having to re-enter the user-mode. If you run
+the server with `--with-text-objects`, the mode is available via `T`.