@@ -51,6 +51,78 @@ It can also act on multiple selections (yay!). For example, to change every occu
5151
5252Multiple characters are currently not supported, but planned.
5353
54+## Syntax-tree Motions
55+
56+`A-p`, `A-o`, `A-i`, and `A-n` (or `Alt` and arrow keys) move the primary
57+selection according to the selection's place in the syntax tree. Let's walk
58+through an example to get familiar with them. Many languages have a syntax like
59+so for function calls:
60+
61+```
62+func(arg1, arg2, arg3)
63+```
64+
65+A function call might be parsed by tree-sitter into a tree like the following.
66+
67+```tsq
68+(call
69+ function: (identifier) ; func
70+ arguments:
71+ (arguments ; (arg1, arg2, arg3)
72+ (identifier) ; arg1
73+ (identifier) ; arg2
74+ (identifier))) ; arg3
75+```
76+
77+Use `:tree-sitter-subtree` to view the syntax tree of the primary selection. In
78+a more intuitive tree format:
79+
80+```
81+ ┌────┐
82+ │call│
83+ ┌─────┴────┴─────┐
84+ │ │
85+┌─────▼────┐ ┌────▼────┐
86+│identifier│ │arguments│
87+│ "func" │ ┌────┴───┬─────┴───┐
88+└──────────┘ │ │ │
89+ │ │ │
90+ ┌─────────▼┐ ┌────▼─────┐ ┌▼─────────┐
91+ │identifier│ │identifier│ │identifier│
92+ │ "arg1" │ │ "arg2" │ │ "arg3" │
93+ └──────────┘ └──────────┘ └──────────┘
94+```
95+
96+Say we have a selection that wraps `arg1`. The selection is on the `arg1` leaf
97+in the tree above.
98+
99+```
100+func([arg1], arg2, arg3)
101+```
102+
103+Using `A-n` would select the next sibling in the syntax tree: `arg2`.
104+
105+```
106+func(arg1, [arg2], arg3)
107+```
108+
109+While `A-o` would expand the selection to the parent node. In the tree above we
110+can see that we would select the `arguments` node.
111+
112+```
113+func[(arg1, arg2, arg3)]
114+```
115+
116+There is also some nuanced behavior that prevents you from getting stuck on a
117+node with no sibling. If we have a selection on `arg1`, `A-p` would bring us
118+to the previous child node. Since `arg1` doesn't have a sibling to its left,
119+though, we climb the syntax tree and then take the previous selection. So `A-p`
120+will move the selection over to the "func" `identifier`.
121+
122+```
123+[func](arg1, arg2, arg3)
124+```
125+
54126## Textobjects
55127
56128Currently supported: `word`, `surround`, `function`, `class`, `parameter`.