Update docs to clarify that all actions require a target (#628)

cursorless-talon/src/cheatsheet/cheat_sheet.py

@@ -122,10 +122,10 @@ class CheatSheet:
             ),
         )
 
-        self.draw_section(canvas, "Special marks", get_list("special_mark"))
-
         self.next_column(canvas)
 
+        self.draw_section(canvas, "Special marks", get_list("special_mark"))
+
         self.draw_section(canvas, "Positions", get_list("position"))
 
         self.draw_section(

cursorless-talon/src/cheatsheet/sections/actions.py

@@ -16,7 +16,7 @@ def get_actions():
         "rewrap",
     ]
     simple_actions = {
-        key: value
+        f"{key} <T>": value
         for key, value in all_actions.items()
         if value not in multiple_target_action_names
     }

docs/user/README.md

@@ -56,7 +56,7 @@ Note: If you'd like to customize any of the spoken forms, please see the [docume
 
 ## Overview
 
-Every cursorless command consists of an action performed on a target. For example, the command `"chuck blue air"` deletes the token with a blue hat over the `"a"`. In this command, the action is `"chuck"` (delete), and the target is `"blue air"`.
+Every cursorless command consists of an action performed on a target. For example, the command `"chuck blue air"` deletes the token with a blue hat over the `"a"`. In this command, the action is `"chuck"` (delete), and the target is `"blue air"`. There are no actions without at least one target.
 
 ## Targets
 
@@ -138,7 +138,7 @@ minimize syllables.
 
 ##### `"this"`
 
-The word `"this"` can be used as a mark to refer to the current cursor(s) or selection(s). Note that when combined with a modifier, the `"this"` mark can be omitted, and it will be implied.
+The word `"this"` can be used as a mark to refer to the current cursor(s) or selection(s) as a target. Note that when combined with a modifier, the `"this"` mark can be omitted, and it will be implied.
 
 - `chuck this`
 - `take this funk`
@@ -319,7 +319,7 @@ Selects both the token containing letter 'a' with a blue hat AND the token conta
 
 ## Actions
 
-In any cursorless command the action defines what happens to the given target, for example deleting the target (`"chuck"`) or moving the cursor to select the target (`"take"`).
+In any cursorless command, the action defines what happens to the specified target. Every command must have a target. For example, deleting the target (`"chuck"`, as in `"chuck air"`) or moving the cursor to select the target (`"take"`, as in `"take air"`).
 
 ### Cursor movement
 
@@ -327,9 +327,9 @@ Despite the name cursorless, some of the most basic commands in cursorless are f
 
 Note that when combined with list targets, these commands will result in multiple cursors
 
-- `"take"`: Selects the given target
-- `"pre"`: Places the cursor before the given target
-- `"post"`: Places the cursor after the given target
+- `"take <TARGET>"`: Selects the given target
+- `"pre <TARGET>"`: Places the cursor before the given target
+- `"post <TARGET>"`: Places the cursor after the given target
 
 eg:
 `pre blue air`
@@ -339,7 +339,7 @@ Moves the cursor to before the token containing letter 'a' with a blue hat.
 
 This command can be used to delete a target without moving the cursor
 
-- `"chuck"`
+- `"chuck <TARGET>"`
 
 eg:
 `chuck blue air`
@@ -349,12 +349,15 @@ Deletes the token containing letter 'a' with a blue hat.
 
 This command will delete a target and leave the cursor where the target used to be, making it easy to change a target
 
-- `"change"`
+- `"change <TARGET>"`
+eg:
+`change blue air`
+Deletes the token containing letter 'a' with a blue hat then places your cursor where the token had been.
 
 ### Cut / copy
 
-- `"carve"`: cut
-- `"copy"`: copy
+- `"carve <TARGET>"`: cut
+- `"copy <TARGET>"`: copy
 
 eg:
 `copy blue air`
@@ -362,7 +365,7 @@ Copies the token containing letter 'a' with a blue hat.
 
 ### Swap
 
-Swaps two targets. If the first target is omitted, it will refer to the current selection. If the targets are list targets they will be zipped together.
+Swaps two targets. If the first target is omitted, it will target the current selection. If the targets are list targets they will be zipped together.
 
 - `"swap <TARGET 1> with <TARGET 2>"`
 - `"swap with <TARGET>"`
@@ -374,8 +377,8 @@ Swaps the given tokens.
 
 ### Insert empty lines
 
-- `"drink"`: Inserts a new line above the current line, and moves the cursor to the newly created line
-- `"pour"`: Inserts a new line below the current line, and moves the cursor to the newly created line
+- `"drink <TARGET>"`: Inserts a new line above the target line, and moves the cursor to the newly created line
+- `"pour <TARGET>"`: Inserts a new line below the target line, and moves the cursor to the newly created line
 
 eg:
 `pour blue air`
@@ -383,9 +386,9 @@ Insert empty line below the token containing letter 'a' with a blue hat.
 
 ### Rename
 
-Executes vscode rename action on the given target
+Executes vscode rename action on the specified target
 
-- `"rename"`
+- `"rename <TARGET>"`
 
 eg:
 `rename blue air`
@@ -395,9 +398,9 @@ Rename the token containing letter 'a' with a blue hat.
 
 Scrolls a given target to the top, center or bottom of the screen.
 
-- `"crown"`: top
-- `"center"`: center
-- `"bottom"`: bottom
+- `"crown <TARGET>"`: top
+- `"center <TARGET>"`: center
+- `"bottom <TARGET>"`: bottom
 
 eg `crown blue air` scrolls the line containing the letter 'a' with a blue hat to the top of the screen.
 
@@ -445,10 +448,10 @@ See [experimental documentation](experimental/wrapper-snippets.md).
 
 ### Show definition/reference/quick fix
 
-- `"define"`
-- `"reference"`
-- `"hover"`
-- `"quick fix"`
+- `"define <TARGET>"`
+- `"reference <TARGET>"`
+- `"hover <TARGET>"`
+- `"quick fix <TARGET>"`
 
 eg:
 `define blue air`
@@ -456,8 +459,8 @@ Shows definition for the token containing letter 'a' with a blue hat.
 
 ### Fold/unfold
 
-- `"fold"`
-- `"unfold"`
+- `"fold <TARGET>"`
+- `"unfold <TARGET>"`
 
 eg:
 `fold funk blue air`
@@ -467,8 +470,7 @@ Fold the function with the token containing letter 'a' with a blue hat.
 
 Extracts a target as a variable using the VSCode refactor action
 
-- `"extract"`
-- `"extract {TARGET} as hello world"`
+- `"extract <TARGET>"`
 
 eg:
 `extract call air`