Skip to content

Improve basic usage #382

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
FireChickenProductivity wants to merge 42 commits into
base: main
Choose a base branch
from
Open

Improve basic usage #382

Changes from all commits
Commits
Show all changes
42 commits
Select commit Hold shift + click to select a range
efdee48
Explain mouse grid
FireChickenProductivity Dec 29, 2025
c64f7cb
Describe character insertion
FireChickenProductivity Dec 29, 2025
d036d14
Explained shared commands
FireChickenProductivity Dec 29, 2025
abdfc63
Explain basics of dictation mode
FireChickenProductivity Dec 29, 2025
c90d978
Start documenting keys
FireChickenProductivity Dec 29, 2025
081c574
Document the rest of the keys
FireChickenProductivity Dec 30, 2025
264f03a
Document dictation mode editing and navigation
FireChickenProductivity Dec 30, 2025
8c1a4de
Improve title
FireChickenProductivity Dec 30, 2025
fe0c9c1
Start on documenting navigation and editing
FireChickenProductivity Dec 30, 2025
186260d
Document edit
FireChickenProductivity Dec 30, 2025
e6132e5
Reorganize
FireChickenProductivity Dec 30, 2025
52541e6
[pre-commit.ci] auto fixes from pre-commit.com hooks
pre-commit-ci[bot] Dec 30, 2025
7cc4b1a
Fix some things
FireChickenProductivity Dec 30, 2025
7d606d8
Move curse commands
FireChickenProductivity Dec 30, 2025
4ad694d
[pre-commit.ci] auto fixes from pre-commit.com hooks
pre-commit-ci[bot] Dec 30, 2025
2d5acfb
Capitalize community
FireChickenProductivity Jan 10, 2026
cc58520
Merge branch 'main' into improve-basic-usage
FireChickenProductivity Jan 10, 2026
d694386
Apply suggestions from code review
nriley Jan 17, 2026
2fc1909
Update docs/Basic Usage/basic_usage.md
nriley Jan 17, 2026
026edcf
Update docs/Basic Usage/basic_usage.md
nriley Jan 17, 2026
2882098
Update docs/Basic Usage/basic_usage.md
nriley Jan 17, 2026
83d6f64
Update docs/Basic Usage/basic_usage.md
FireChickenProductivity Jan 17, 2026
d53a36b
Reserve back tics for spoken forms and tag names
FireChickenProductivity Jan 17, 2026
83c2f34
Document close grid command inside table
FireChickenProductivity Jan 17, 2026
2348c7f
[pre-commit.ci] auto fixes from pre-commit.com hooks
pre-commit-ci[bot] Jan 17, 2026
b9bef0a
Document media and tab commands
FireChickenProductivity Jan 17, 2026
9906d33
[pre-commit.ci] auto fixes from pre-commit.com hooks
pre-commit-ci[bot] Jan 17, 2026
4cafed5
Document context sensitive dictation and make some refinements
FireChickenProductivity Jan 24, 2026
dc502fb
Remove arrow
FireChickenProductivity Jan 24, 2026
54ac9de
Put the up arrow key back
FireChickenProductivity Jan 24, 2026
a99f61a
Add the other arrow key
FireChickenProductivity Jan 24, 2026
49f3794
Apply suggestions from code review
nriley Jan 31, 2026
e68c6f0
Explain unprefixed numbers
FireChickenProductivity Feb 3, 2026
c899c46
Explain prose formatters
FireChickenProductivity Feb 3, 2026
98223b9
[pre-commit.ci] auto fixes from pre-commit.com hooks
pre-commit-ci[bot] Feb 3, 2026
fcfd983
Apply suggestion from @chdoc
FireChickenProductivity Feb 7, 2026
71d4af2
Update docs/Basic Usage/basic_usage.md
nriley Feb 7, 2026
1d35b45
Update docs/Basic Usage/basic_usage.md
nriley Feb 7, 2026
8dbe576
Update docs/Basic Usage/basic_usage.md
nriley Feb 7, 2026
f2c2512
Update docs/Basic Usage/basic_usage.md
nriley Feb 7, 2026
ca15bfc
Update docs/Basic Usage/basic_usage.md
nriley Feb 7, 2026
ccfed2a
Update docs/Basic Usage/basic_usage.md
nriley Feb 7, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
263 changes: 206 additions & 57 deletions docs/Basic Usage/basic_usage.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,7 +33,9 @@ To keep track of what mode you are in with a visual icon, enable the [mode indic

Copy link

@chdoc chdoc Feb 7, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

To me, pressing keys is the most basic functionality, I would explain that first before venturing on into dictation.

## Dictating Text

Say a formatter then the text. (i.e. `say "hello world"`) to dictate while in command mode
### Formatters

Say a formatter then the text. (e.g., `say hello world`) to dictate while in command mode

| Formatter | Description |
| ----------------- | --------------------------------------- |
Expand All @@ -45,6 +47,171 @@ Say a formatter then the text. (i.e. `say "hello world"`) to dictate while in co
| `kebab` | dashes instead of spaces |
| `help formatters` | show all available formatters |

`help formatters` shows 2 types of formatters: prose formatters and code formatters. Code formatters are primarily for formatting identifiers and values in computer code. Prose formatters are primarily for ordinary text and are shown with a \* after them. When dictating text with a prose formatter, you can say the following in the middle of dictation.
Copy link

@chdoc chdoc Feb 3, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would (also) mention behavioral differences between prose and text formatters. Usage alone says nothing really.

Copy link
Contributor Author

@FireChickenProductivity FireChickenProductivity Feb 7, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What behavioral differences did I leave out?

Copy link
Contributor

@nriley nriley Feb 7, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Punctuation :) if you can provide a quick note that it supports lots of post formatting things and we can add a link to a specific description of the prose capture in a different PR.


| Prose formatting options | Description |
| ------------------------ | ----------------------------------------- |
| `cap` | capitalize the next word |
| `no cap` or `no caps` | the next word is in lowercase |
| `no space` | no space is inserted before the next word |
| `numb <number>` | insert the specified number |

These formatting options are also available in dictation mode with the same effects.

### Dictating Individual Characters

#### Dictating Characters in Command Mode

`help symbols` shows the commands for dictating symbols. Numbers can be dictated in command or dictation mode by saying `numb <number>`, i.e. `numb 2000` to dictate "2000". Individual letters can be dictated with the alphabet commands, which can be seen by saying `help alphabet`. A single capital letter can be dictated by saying `shift <user.letter>`, such as saying `shift air` to dictate "A". Multiple capital letters can be dictated in command or dictation mode by saying `ship` before the letters, such as saying `ship air bat cap` to dictate "ABC".

If you want to insert numbers in command mode without needing to say `numb` before every number, you can enable the user.unprefixed_numbers tag. To do this, first open settings.talon by saying `customize settings`. Look for the line with the text "# tag(): user.unprefixed_numbers" and remove the "#" and space at the start of the line. Now save the file by saying `file save`. You can read more about tags in the [the tags customization page](../Customization/Talon%20Framework/tags.md).

#### Dictating Characters in Dictation Mode

In dictation mode, lowercase letters can be dictated by saying `spell` and then the letters, such as `spell air bat cap` to dictate "abc". Keys can be pressed in dictation mode by saying `press` and then the key stroke. This can allow dictating symbols, such as `press tilde` to dictate "~". `help punctuation` shows how to dictate punctuation symbols in dictation mode without the press prefix.

The commands for dictating uppercase letters and numbers are the same as in command mode and are documented in the previous section.

### Dictating Words in Dictation Mode

In dictation mode, words that are not commands are inserted as text. To dictate words that would otherwise get interpreted as dictation mode commands, you can say `escape` followed by the words you want transcribed, such as saying `escape press air` to dictate the text "press air".

The following commands are available for overriding the default formatting:

| Command | Description |
| ----------------------------------------- | --------------------------------------------------------- |
| `cap` | capitalize the next word |
| `no cap` or `no caps` | make the next word lowercase |
| `no space` | do not put a space before the next word |
| `cap that` | make the first word of the last dictated text capitalized |
| `no cap that` or `no caps that` | make the first word of the last dictated text lowercase |
| `formatted <user.formatters> <user.text>` | apply formatter to the dictated text |

The formatted command works with the formatters documented above. To give an example, saying `formatted title this is dictation` inserts the text "This Is Dictation".

To improve automatic spacing and capitalization in dictation mode, you can enable the user.context_sensitive_dictation setting. You can enable this globally in the settings.talon file, which you can open by saying `customize settings`. Context sensitive dictation may be slow and may not work in some applications because it relies on selecting and copying the text near the cursor, so you may want to enable this on a per-application basis. See [this page on .talon files](Customization/talon-files.md) if you want to understand how to modify settings on a per context basis and create custom commands.

## Pressing Keys

In command mode, saying `help alphabet` shows spoken forms for letter keys. Saying `help symbols` shows spoken forms for symbol keys.

Keys can be combined with modifier keys, i.e., saying `shift up` presses <kbd>Shift</kbd> and the up arrow key <kbd>↑</kbd>. Saying `help modifiers` shows the word to refer to each modifier key. The `super` key refers to the operating system-specific modifier. This is used for the Windows logo key on Windows and offers one way to refer to the <kbd>Command</kbd> key on macOS.

In a keystroke, number keys can be dictated without prefix. For instance, saying `control one` presses the <kbd>Control</kbd> and <kbd>1</kbd> keys at the same time.

Keys can be pressed in dictation mode by saying `press` followed by the keystroke, such as saying `press shift up` to press <kbd>Shift</kbd> and the up arrow key <kbd>↑</kbd>. The `press` command can also be used in command or dictation mode to press modifier keys by themselves, such as `press control` to press the <kbd>Control</kbd> key.

Saying `help arrows` shows spoken forms for the arrow keys, which are just the direction names up, down, left, right. These can be used with a modifier or the `press` command but not by themselves.

Saying `help special keys` shows spoken forms for other keys you can `press`, such as <kbd>Page Up</kbd> and <kbd>Escape</kbd>.

Function keys, like <kbd>f1</kbd>, can be dictated by saying `f` and then the key number.

### Dictation Mode Editing and Navigation
Copy link

@chdoc chdoc Feb 4, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why is this a subsection of "pressing keys"? Shouldnt it be in its own "editing commands" section?

Copy link
Contributor Author

@FireChickenProductivity FireChickenProductivity Feb 7, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Because these commands press keys. I wanted few high level sections to make it easier to find information.


Dictation mode provides some convenience commands for editing and navigating text.

| Command | Description |
| ------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| `scratch that` | delete the last dictated phrase assuming the cursor has not moved after dictating it |
| `select that` | select the last dictated phrase assuming the cursor has not moved after dictating it |
| `go line start` | move the cursor to the start of the line |
| `go line end` | move the cursor to the end of the line |
| `go up <number_small> (line or lines)` | move the cursor up the specified number of lines |
| `go down <number_small> (line or lines)` | move the cursor down the specified number of lines |
| `go left <number_small> (word or words)` | move the cursor left the specified number of words |
| `go right <number_small> (word or words)` | move the cursor right the specified number of words |
| `select left <number_small> (word or words)` | select the specified number of words to the left |
| `select right <number_small> (word or words)` | select the specified number of words to the right |
| `select left <number_small> (character or characters)` | select the specified number of characters to the left |
| `select right <number_small> (character or characters)` | select the specified number of characters to the right |
| `clear left <number_small> (word or words)` | delete the specified number of words to the left |
| `clear right <number_small> (word or words)` | delete the specified number of words to the right |
| `clear left <number_small> (character or characters)` | delete the specified number of characters to the left |
| `clear right <number_small> (character or characters)` | delete the specified number of characters to the right |

For example, saying `go up 10 lines` moves the cursor up 10 lines.

### Command Mode Editing and Navigation

#### Edit/Navigation Actions and Modifiers
Copy link

@chdoc chdoc Feb 7, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
#### Edit/Navigation Actions and Modifiers

I'm not a fan of two successive headlines, nor am I a fan of fourth-level headlines.


Command mode provides flexible editing and navigation commands.

Saying an action name followed by a modifier applies the action to the modifier's target. For instance, saying `select line` selects the current line. A number between 1 and 99 can be dictated between the name of an action and a repeatable modifier to apply that modifier the specified number of times. For instance, saying `copy 3 right` copies the three characters to the right of the cursor.

| Action | Description |
| --------- | ------------------------------------------------- |
| select | select the target |
| go before | go before the target |
| go after | go after the target |
| copy | copy the text at the target |
| paste | paste the contents of the clipboard to the target |
| clear | delete the target |

| Modifier | What the action gets applied to |
| ---------- | ------------------------------- |
| all | the document |
| paragraph | the paragraph |
| line | the line |
| line start | the start of line |
| way left | the start of line |
| line end | the end of line |
| way right | the end of line |
| file start | the start of file |
| way up | the start of file |
| file end | the end of file |
| way down | the end of file |

| Repeatable Modifier | The action gets applied to the specified number of |
| ------------------- | -------------------------------------------------- |
| word left | words to the left of the cursor |
| word right | words to the right of the cursor |
| word | words to the right of the cursor |
| up | lines up starting at the cursor |
| down | lines down starting at the cursor |
| left | characters to the left of the cursor |
| right | characters to the right of the cursor |

#### Scrolling

| Command | Description |
| -------------- | -------------------------------------- |
| `page down` | press the Page Down key |
| `page up` | press the Page Up key |
| `scroll down` | scroll down |
| `scroll up` | scroll up |
| `wheel down` | scroll down with the mouse |
| `wheel up` | scroll up with the mouse |
| `wheel left` | scroll left with the mouse |
| `wheel right` | scroll right with the mouse |
| `wheel gaze` | scroll according to the mouse position |
| `wheel upper` | continually scroll up with the mouse |
| `wheel downer` | continually scroll down with the mouse |
| `wheel stop` | stop scrolling |

#### Working with text

| Command | Description |
| ------------ | -------------- |
| `copy that` | copy selection |
| `paste that` | paste |
| `cut that` | cut selection |
| `undo that` | undo |
| `redo that` | redo |

#### Working With Tabs
Copy link

@chdoc chdoc Feb 7, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This section definitely does not belong below "Command Mode Editing and Navigation"

Copy link
Contributor Author

@FireChickenProductivity FireChickenProductivity Feb 7, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Working with tabs is a form of navigation.


| Command | Description |
| ----------------- | ---------------------------------------------- |
| `tab new` | open a new tab |
| `tab last` | go to the previous tab |
| `tab next` | go to the next tab |
| `tab close` | close the current tab |
| `tab restore` | reopen the most recently closed tab |
| `go tab <number>` | go to the tab specified by the dictated number |
| `go tab final` | go to the final tab |

## Customize Talon

These commands will open up a CSV or [Talon list](Customization/talon_lists.md) file in your default text editor that you can edit to customize voice commands without needing to write Talon scripts.
Expand All @@ -65,28 +232,9 @@ These commands will open up a CSV or [Talon list](Customization/talon_lists.md)
| `launch "app name"` | say "launch chrome" for example, to open chrome |
| `window close` | closes the currently active window |

## Working with tabs

| Command |
| ----------------- |
| `tab new` |
| `tab last` |
| `tab next` |
| `tab close` |
| `tab restore` |
| `go tab <number>` |
| `go tab final` |

## Working with media

| Command |
| --------------- |
| `media mute` |
| `play next` |
| `play previous` |
| `media play` |
## Mouse Commands

## Controlling the Tobii eye tracker
### Controlling the Tobii eye tracker

| Commands | Description |
| ----------------- | ------------------------------------ |
Expand All @@ -95,43 +243,44 @@ These commands will open up a CSV or [Talon list](Customization/talon_lists.md)
| `zoom mouse` | Toggle Control Mouse (Zoom). |
| `control off` | Turn the eye tracker off |

## Working with text
### Clicking

| Command | Description |
| -------------- | ------------------------------------------------------------------------- |
| `copy that` | |
| `control cap` | copy via the keyboard shortcut using the Talon alphabet (`cap` for `c`) |
| `paste that` | |
| `control vest` | paste via the keyboard shortcut using the Talon alphabet (`vest` for `v`) |
| `cut that` | |
| `undo that` | |
| `redo that` | |
| `scratch that` | undo Talon dictation |
| Command | Description |
| ------------ | -------------------------------------- |
| `touch` | single click |
| `duke` | double click |
| `trip click` | triple click |
| `drag` | hold down the mouse. Repeat to release |
| `righty` | right click |

## Mouse Commands
### Mouse Grid

| Command | Description |
| ------------ | --------------------------------------- |
| `touch` | single click |
| `duke` | double click |
| `trip click` | triple click |
| `drag` | hold down the mouse. Repeat to release |
| `curse yes` | hides the mouse cursor for eye tracking |
| `curse no` | shows the mouse cursor |
| `righty` | right click |
The mouse grid lets you move the mouse by dictating numbers. You use one of the below commands to open the grid. This divides the area you made the grid around into 9 rectangles. Picking one of the numbers recreates the grid within that rectangle and moves the mouse to the center of that rectangle. The clicking commands and `grid close` close the mouse grid.

## Scrolling
| Command | Description |
| ------------------------- | --------------------------------------------------------------------------------- |
| `mouse grid` | open the mouse grid |
| `grid win` | open the mouse grid on the window |
| `grid screen <number>` | open the mouse grid on the specified screen |
| `grid <user.number_key>+` | open the mouse grid and narrow it using the numbers from the dictated number keys |
| `grid close` | close the mouse grid |

| Command | Description |
| -------------- | -------------------------------------- |
| `page down` | press the page down key |
| `page up` | press the page up key |
| `scroll down` | scroll down |
| `scroll up` | scroll up |
| `wheel down` | scroll down |
| `wheel up` | scroll up |
| `wheel left` | scroll left |
| `wheel gaze` | scroll according to the mouse position |
| `wheel upper` | continually scroll up |
| `wheel downer` | continually scroll down |
| `wheel stop` | stop scrolling |
### Cursor Hide/Show Commands

| Command | Description |
| ----------- | --------------------------------------- |
| `curse yes` | hides the mouse cursor for eye tracking |
| `curse no` | shows the mouse cursor |

These commands require activating the `user.mouse_cursor_commands_enable` tag (see Community settings.talon).

## Media and Volume Control

| Command | Description |
| --------------- | ----------------------------- |
| `volume mute` | toggle muting sound |
| `volume up` | increase volume |
| `volume down` | decrease volume |
| `play next` | press the <kbd>next</kbd> key |
| `play previous` | press the <kbd>prev</kbd> key |
| `media play` | play or pause media |