Attempt to improve the multicharacter detection code.
This commit is contained in:
Storm Dragon committed
1 parent
6fc3416a1b
commit
3cf41e662c
12 files changed
+1135
-843
No files matched your search
+190
-164
@@ -8,6 +8,168 @@ consoles and can run in an X11 terminal as a regular user.
|
||||
|
||||
For build requirements and setup, see the [README](../README.md).
|
||||
|
||||
## Starting and stopping
|
||||
|
||||
Run these commands from the checkout root after building `fenrir`:
|
||||
|
||||
```bash
|
||||
# Linux text console, with console and keyboard device access
|
||||
sudo ./fenrir
|
||||
|
||||
# Linux console in the foreground (also use -f with service managers)
|
||||
sudo ./fenrir -f
|
||||
|
||||
# X11 terminal, as your regular user
|
||||
./fenrir -x
|
||||
|
||||
# Either mode can select the laptop layout
|
||||
./fenrir -x --keyboard-layout laptop
|
||||
```
|
||||
|
||||
Console mode starts in the background by default. Add `-f` to keep it in the
|
||||
foreground, including under a service manager. The launcher returns after the
|
||||
reader initializes and reports startup failures in the launching terminal.
|
||||
Use `--debug-file PATH` to retain diagnostics after detaching. Help, version,
|
||||
and configuration-only commands always run in the foreground.
|
||||
|
||||
X11 mode (`-x`) always stays in the foreground because it owns the terminal
|
||||
and its child shell. Press **Fenrir+Q** to quit either mode. Run only one
|
||||
reader on a given Linux console. Separate X11 terminal instances can run at
|
||||
once.
|
||||
|
||||
X11 mode starts a shell in a new PTY. The launching terminal must supply valid
|
||||
`DISPLAY` and `WINDOWID` environment variables. Keyboard interception is scoped
|
||||
to that terminal window; a desktop screen reader can handle other windows.
|
||||
|
||||
Console mode needs access to console devices, keyboard event devices, and
|
||||
`/dev/uinput`. It releases keyboard input on graphical virtual terminals and
|
||||
on text consoles selected in `screen.ignored_vts`.
|
||||
|
||||
## Keyboard layouts and help
|
||||
|
||||
The **Fenrir key** is Insert, Super/Windows, or keypad 0 with NumLock off.
|
||||
Hold it while pressing the other keys in a shortcut. Bare keypad review keys
|
||||
also require NumLock off.
|
||||
|
||||
The desktop layout uses the numeric keypad. The laptop layout uses Fenrir
|
||||
chords on the main keyboard. Select a layout with `--keyboard-layout desktop`
|
||||
or `--keyboard-layout laptop`, or set `keyboard.layout` in the settings file.
|
||||
|
||||
Press **Fenrir+H** or **Fenrir+F1** to enter the tutorial. Command shortcuts are
|
||||
announced and described instead of executed. Up and Down browse commands;
|
||||
Left and Right switch between active actions, unbound actions, and scripts.
|
||||
Space repeats the current item. Escape or Fenrir+F1 exits.
|
||||
|
||||
The complete layouts are [desktop.toml](../config/keyboard/desktop.toml) and
|
||||
[laptop.toml](../config/keyboard/laptop.toml).
|
||||
|
||||
## Screen review
|
||||
|
||||
Review moves Fenrir's reading position without moving the application's cursor.
|
||||
Return to the application cursor with the Follow cursor shortcut. By default,
|
||||
application cursor movement or a screen change also leaves review.
|
||||
|
||||
| Action | Desktop | Laptop |
|
||||
| --- | --- | --- |
|
||||
| Previous / current / next line | Keypad 7 / 8 / 9 | Fenrir+U / I / O |
|
||||
| Previous / current / next word | Keypad 4 / 5 / 6 | Fenrir+J / K / L |
|
||||
| Previous / current / next character | Keypad 1 / 2 / 3 | Fenrir+M / Comma / Period |
|
||||
| Top / bottom of screen | Fenrir+Keypad 7 / 9 | Fenrir+Shift+U / O |
|
||||
| Line start / end | Fenrir+Keypad 4 / 6 | Fenrir+Shift+J / L |
|
||||
| First / last text on line | Fenrir+Keypad 1 / 3 | Fenrir+Control+J / L |
|
||||
| Read screen | Fenrir+Keypad 5 | Fenrir+Shift+K |
|
||||
| Screen before / after cursor | Fenrir+Keypad 8 / 2 | Fenrir+Shift+I / Comma |
|
||||
| Character above / below | Fenrir+Control+Keypad 8 / 2 | Fenrir+Control+I / Comma |
|
||||
| Follow cursor | Fenrir+Keypad Period | Fenrir+Slash |
|
||||
| Review position | Keypad Period | Fenrir+Shift+Period |
|
||||
|
||||
Press the current-line or current-word shortcut twice quickly to spell the
|
||||
text, or three times for phonetic reading. Press the current-character shortcut
|
||||
twice for its phonetic name. The default interval between presses is 200 ms;
|
||||
`keyboard.multi_press_timeout_ms` changes it at launch.
|
||||
|
||||
## Tracking modes
|
||||
|
||||
Cycle through **cursor**, **table**, and **highlight** with
|
||||
**Fenrir+Keypad Asterisk** on desktop or **Fenrir+Y** on laptop.
|
||||
The startup selection is `reading.mode`.
|
||||
|
||||
- **Cursor**: follows application cursor movement.
|
||||
- **Table**: treats delimited or space-aligned text as cells.
|
||||
- **Highlight**: follows changes to highlighted text, such as menu selections.
|
||||
|
||||
In table mode, word navigation moves between cells, line start/end moves to the
|
||||
first/last cell, and first/last text moves to the first/last character in the
|
||||
current cell. Place review on a header row and press **Fenrir+X** to use its
|
||||
cells as column headers. Outside table mode, Fenrir+X places a text-selection
|
||||
mark.
|
||||
|
||||
## Speech and automatic reading
|
||||
|
||||
- **Control** interrupts speech.
|
||||
- **Fenrir+F4** toggles mute.
|
||||
- **Keypad Enter** on desktop temporarily silences speech. Speech can return on
|
||||
the next keypress or a newly recognized prompt or completion.
|
||||
- **Fenrir+Keypad Enter** on desktop, or **Fenrir+Enter** on laptop, toggles
|
||||
automatic reading of new text.
|
||||
- **Fenrir+Backspace** passes the next key through to the application.
|
||||
|
||||
Character echo, word echo, and cursor echo can be configured separately.
|
||||
Punctuation levels are `none`, `some`, `most`, and `all`. At `some` and `most`,
|
||||
punctuation inside words, URLs, email addresses, and filenames is also named.
|
||||
Apostrophes within words and single numeric separators such as those in `3.14`,
|
||||
`1,000`, and `12:30` follow the selected level. Sentence punctuation follows the
|
||||
selected level too. Character review always names punctuation.
|
||||
Capital indicators, emoticons, repeated-symbol summaries,
|
||||
indentation feedback, and attribute feedback are configurable in Reading.
|
||||
|
||||
**Fenrir+T** announces the time; press twice quickly for the date.
|
||||
**Fenrir+Shift+V** announces the Fenrir version.
|
||||
|
||||
## Fenrir Menu and quick settings
|
||||
|
||||
Press **Fenrir+F** to open the Fenrir Menu. It contains settings tabs for
|
||||
presentation, speech, sound, reading, keyboard, internal UI, clipboard, and other options.
|
||||
The form captures its navigation keys until it closes.
|
||||
|
||||
- At the tab selector, use arrows to choose a tab.
|
||||
- Tab and Shift+Tab move between controls and the tab selector.
|
||||
- Space or Enter toggles a checkbox.
|
||||
- Arrows change list selections and numeric values.
|
||||
- Activate **OK** to save, or **Cancel** or Escape to discard the form's changes.
|
||||
|
||||
Speech rate, pitch, and volume use a scale from -100 to 100. For speech rate,
|
||||
Up and Down change the value by 10; Left and Right change it by 1. Sound volume is
|
||||
between 0.0 and 1.0. Backend, device, keyboard layout, sound theme, and other
|
||||
launch-only settings take effect on the next start.
|
||||
|
||||
The **Internal UI** tab controls speech in Fenrir's own menus and dialogs.
|
||||
**Announce grid row and column** and **Announce item position** are independent
|
||||
checkboxes, both enabled by default. Disable coordinates to omit “row 1, column 2”;
|
||||
disable item position to omit “2 of 20”. Item names and grid navigation remain
|
||||
available with both disabled. Saved changes apply immediately to Emoji and
|
||||
Spellcheck grids and persist across launches. These are global settings, so this
|
||||
tab is omitted from application settings. The TOML keys are
|
||||
`internal_ui.announce_grid_coordinates` and `internal_ui.announce_item_position`.
|
||||
|
||||
Settings saves use mode `644` for the standard system settings file at
|
||||
`/etc/fenrirscreenreader/settings/settings.toml`, so other users can read it as a
|
||||
startup fallback. Personal settings and application profiles use mode `600`.
|
||||
|
||||
Quick settings work without opening the form:
|
||||
|
||||
| Shortcut | Action |
|
||||
| --- | --- |
|
||||
| Fenrir+Space | Announce current setting |
|
||||
| Fenrir+Left / Right | Previous / next setting |
|
||||
| Fenrir+Control+Left / Right | Previous / next category |
|
||||
| Fenrir+Up / Down | Change value |
|
||||
| Fenrir+Control+S | Save settings |
|
||||
|
||||
Quick changes apply to the current session. Save to retain them for future
|
||||
launches. Session controls such as mute and temporary silence are separate
|
||||
from saved startup preferences.
|
||||
|
||||
## Application overrides
|
||||
|
||||
Press **Fenrir+A** to open **Applications**. Up and Down select an item; Enter
|
||||
@@ -241,168 +403,6 @@ Real acceptance still needs a Codex reply spoken once after completion, working
|
||||
status on demand, history review, composer typing, approval/question handling,
|
||||
and returning to ordinary reading after choosing Default or exiting Codex.
|
||||
|
||||
## Starting and stopping
|
||||
|
||||
Run these commands from the checkout root after building `fenrir`:
|
||||
|
||||
```bash
|
||||
# Linux text console, with console and keyboard device access
|
||||
sudo ./fenrir
|
||||
|
||||
# Linux console in the foreground (also use -f with service managers)
|
||||
sudo ./fenrir -f
|
||||
|
||||
# X11 terminal, as your regular user
|
||||
./fenrir -x
|
||||
|
||||
# Either mode can select the laptop layout
|
||||
./fenrir -x --keyboard-layout laptop
|
||||
```
|
||||
|
||||
Console mode starts in the background by default. Add `-f` to keep it in the
|
||||
foreground, including under a service manager. The launcher returns after the
|
||||
reader initializes and reports startup failures in the launching terminal.
|
||||
Use `--debug-file PATH` to retain diagnostics after detaching. Help, version,
|
||||
and configuration-only commands always run in the foreground.
|
||||
|
||||
X11 mode (`-x`) always stays in the foreground because it owns the terminal
|
||||
and its child shell. Press **Fenrir+Q** to quit either mode. Run only one
|
||||
reader on a given Linux console. Separate X11 terminal instances can run at
|
||||
once.
|
||||
|
||||
X11 mode starts a shell in a new PTY. The launching terminal must supply valid
|
||||
`DISPLAY` and `WINDOWID` environment variables. Keyboard interception is scoped
|
||||
to that terminal window; a desktop screen reader can handle other windows.
|
||||
|
||||
Console mode needs access to console devices, keyboard event devices, and
|
||||
`/dev/uinput`. It releases keyboard input on graphical virtual terminals and
|
||||
on text consoles selected in `screen.ignored_vts`.
|
||||
|
||||
## Keyboard layouts and help
|
||||
|
||||
The **Fenrir key** is Insert, Super/Windows, or keypad 0 with NumLock off.
|
||||
Hold it while pressing the other keys in a shortcut. Bare keypad review keys
|
||||
also require NumLock off.
|
||||
|
||||
The desktop layout uses the numeric keypad. The laptop layout uses Fenrir
|
||||
chords on the main keyboard. Select a layout with `--keyboard-layout desktop`
|
||||
or `--keyboard-layout laptop`, or set `keyboard.layout` in the settings file.
|
||||
|
||||
Press **Fenrir+H** or **Fenrir+F1** to enter the tutorial. Command shortcuts are
|
||||
announced and described instead of executed. Up and Down browse commands;
|
||||
Left and Right switch between active actions, unbound actions, and scripts.
|
||||
Space repeats the current item. Escape or Fenrir+F1 exits.
|
||||
|
||||
The complete layouts are [desktop.toml](../config/keyboard/desktop.toml) and
|
||||
[laptop.toml](../config/keyboard/laptop.toml).
|
||||
|
||||
## Screen review
|
||||
|
||||
Review moves Fenrir's reading position without moving the application's cursor.
|
||||
Return to the application cursor with the Follow cursor shortcut. By default,
|
||||
application cursor movement or a screen change also leaves review.
|
||||
|
||||
| Action | Desktop | Laptop |
|
||||
| --- | --- | --- |
|
||||
| Previous / current / next line | Keypad 7 / 8 / 9 | Fenrir+U / I / O |
|
||||
| Previous / current / next word | Keypad 4 / 5 / 6 | Fenrir+J / K / L |
|
||||
| Previous / current / next character | Keypad 1 / 2 / 3 | Fenrir+M / Comma / Period |
|
||||
| Top / bottom of screen | Fenrir+Keypad 7 / 9 | Fenrir+Shift+U / O |
|
||||
| Line start / end | Fenrir+Keypad 4 / 6 | Fenrir+Shift+J / L |
|
||||
| First / last text on line | Fenrir+Keypad 1 / 3 | Fenrir+Control+J / L |
|
||||
| Read screen | Fenrir+Keypad 5 | Fenrir+Shift+K |
|
||||
| Screen before / after cursor | Fenrir+Keypad 8 / 2 | Fenrir+Shift+I / Comma |
|
||||
| Character above / below | Fenrir+Control+Keypad 8 / 2 | Fenrir+Control+I / Comma |
|
||||
| Follow cursor | Fenrir+Keypad Period | Fenrir+Slash |
|
||||
| Review position | Keypad Period | Fenrir+Shift+Period |
|
||||
|
||||
Press the current-line or current-word shortcut twice quickly to spell the
|
||||
text, or three times for phonetic reading. Press the current-character shortcut
|
||||
twice for its phonetic name. The default interval between presses is 200 ms;
|
||||
`keyboard.multi_press_timeout_ms` changes it at launch.
|
||||
|
||||
## Tracking modes
|
||||
|
||||
Cycle through **cursor**, **table**, and **highlight** with
|
||||
**Fenrir+Keypad Asterisk** on desktop or **Fenrir+Y** on laptop.
|
||||
The startup selection is `reading.mode`.
|
||||
|
||||
- **Cursor**: follows application cursor movement.
|
||||
- **Table**: treats delimited or space-aligned text as cells.
|
||||
- **Highlight**: follows changes to highlighted text, such as menu selections.
|
||||
|
||||
In table mode, word navigation moves between cells, line start/end moves to the
|
||||
first/last cell, and first/last text moves to the first/last character in the
|
||||
current cell. Place review on a header row and press **Fenrir+X** to use its
|
||||
cells as column headers. Outside table mode, Fenrir+X places a text-selection
|
||||
mark.
|
||||
|
||||
## Speech and automatic reading
|
||||
|
||||
- **Control** interrupts speech.
|
||||
- **Fenrir+F4** toggles mute.
|
||||
- **Keypad Enter** on desktop temporarily silences speech. Speech can return on
|
||||
the next keypress or a newly recognized prompt or completion.
|
||||
- **Fenrir+Keypad Enter** on desktop, or **Fenrir+Enter** on laptop, toggles
|
||||
automatic reading of new text.
|
||||
- **Fenrir+Backspace** passes the next key through to the application.
|
||||
|
||||
Character echo, word echo, and cursor echo can be configured separately.
|
||||
Punctuation levels are `none`, `some`, `most`, and `all`. At `some` and `most`,
|
||||
punctuation inside words, URLs, email addresses, and filenames is also named.
|
||||
Apostrophes within words and single numeric separators such as those in `3.14`,
|
||||
`1,000`, and `12:30` follow the selected level. Sentence punctuation follows the
|
||||
selected level too. Character review always names punctuation.
|
||||
Capital indicators, emoticons, repeated-symbol summaries,
|
||||
indentation feedback, and attribute feedback are configurable in Reading.
|
||||
|
||||
**Fenrir+T** announces the time; press twice quickly for the date.
|
||||
**Fenrir+Shift+V** announces the Fenrir version.
|
||||
|
||||
## Fenrir Menu and quick settings
|
||||
|
||||
Press **Fenrir+F** to open the Fenrir Menu. It contains settings tabs for
|
||||
presentation, speech, sound, reading, keyboard, internal UI, clipboard, and other options.
|
||||
The form captures its navigation keys until it closes.
|
||||
|
||||
- At the tab selector, use arrows to choose a tab.
|
||||
- Tab and Shift+Tab move between controls and the tab selector.
|
||||
- Space or Enter toggles a checkbox.
|
||||
- Arrows change list selections and numeric values.
|
||||
- Activate **OK** to save, or **Cancel** or Escape to discard the form's changes.
|
||||
|
||||
Speech rate, pitch, and volume use a scale from -100 to 100. For speech rate,
|
||||
Up and Down change the value by 10; Left and Right change it by 1. Sound volume is
|
||||
between 0.0 and 1.0. Backend, device, keyboard layout, sound theme, and other
|
||||
launch-only settings take effect on the next start.
|
||||
|
||||
The **Internal UI** tab controls speech in Fenrir's own menus and dialogs.
|
||||
**Announce grid row and column** and **Announce item position** are independent
|
||||
checkboxes, both enabled by default. Disable coordinates to omit “row 1, column 2”;
|
||||
disable item position to omit “2 of 20”. Item names and grid navigation remain
|
||||
available with both disabled. Saved changes apply immediately to Emoji and
|
||||
Spellcheck grids and persist across launches. These are global settings, so this
|
||||
tab is omitted from application settings. The TOML keys are
|
||||
`internal_ui.announce_grid_coordinates` and `internal_ui.announce_item_position`.
|
||||
|
||||
Settings saves use mode `644` for the standard system settings file at
|
||||
`/etc/fenrirscreenreader/settings/settings.toml`, so other users can read it as a
|
||||
startup fallback. Personal settings and application profiles use mode `600`.
|
||||
|
||||
Quick settings work without opening the form:
|
||||
|
||||
| Shortcut | Action |
|
||||
| --- | --- |
|
||||
| Fenrir+Space | Announce current setting |
|
||||
| Fenrir+Left / Right | Previous / next setting |
|
||||
| Fenrir+Control+Left / Right | Previous / next category |
|
||||
| Fenrir+Up / Down | Change value |
|
||||
| Fenrir+Control+S | Save settings |
|
||||
|
||||
Quick changes apply to the current session. Save to retain them for future
|
||||
launches. Session controls such as mute and temporary silence are separate
|
||||
from saved startup preferences.
|
||||
|
||||
## Clipboard
|
||||
|
||||
Use review navigation to place two marks around text with **Fenrir+X**, then
|
||||
@@ -477,6 +477,30 @@ Sound output uses `pulse` for PulseAudio or PipeWire's PulseAudio service, or
|
||||
`alsa` for an ALSA PCM device. Select the driver and theme in Sound settings.
|
||||
The ALSA device name is set with `presentation.sound.device` in the file.
|
||||
|
||||
Speech Dispatcher has its own synthesis and audio configuration, separate
|
||||
from Fenrir's sound cues. For an X11 terminal session, run `./fenrir -x` as
|
||||
your regular user. With sudo, Fenrir uses `SUDO_UID` to locate the invoking
|
||||
user's PulseAudio socket. The default sound driver tries the user session,
|
||||
then `/tmp/pulse.sock`, then `/run/pulse/native`. Set `PULSE_SERVER` to select
|
||||
an explicit server; the sound driver does not read PulseAudio's `client.conf`.
|
||||
The sound service must already be running and accessible to the reader.
|
||||
See [Speech synthesizers](#speech-synthesizers) for Speech Dispatcher addresses
|
||||
and autostart behavior.
|
||||
|
||||
If root sound needs additional configuration, the checkout includes
|
||||
[configure_pulse.sh](../tools/configure_pulse.sh) for PulseAudio and
|
||||
[configure_pipewire.sh](../tools/configure_pipewire.sh) for PipeWire.
|
||||
Read the appropriate script before running it. Each has a regular-user part
|
||||
and a root part, and writes audio configuration files. The PulseAudio script
|
||||
replaces the user's `default.pa` and configures an anonymously accessible socket
|
||||
at `/tmp/pulse.sock`. The PipeWire script also changes WirePlumber settings.
|
||||
These scripts change system audio configuration and are only needed when the
|
||||
existing audio setup does not provide the required access.
|
||||
|
||||
For ALSA, select `driver = "alsa"` under `[presentation.sound]` in
|
||||
`settings.toml` and set `device` to the desired PCM name, such as `"default"`.
|
||||
Driver and device changes apply at the next launch.
|
||||
|
||||
Personal themes are searched under `~/.local/stormux/fenrir/sounds/` before
|
||||
bundled and system themes. A theme contains WAV files and `soundicons.toml`.
|
||||
|
||||
@@ -660,8 +684,10 @@ values. `./fenrir --version` identifies the build when reporting a problem.
|
||||
## Documentation maintenance and support
|
||||
|
||||
`docs/user.md` is the shared manual source. With Pandoc installed, run
|
||||
`./docs/create_manpage.sh` to regenerate `docs/user.txt`, `docs/fenrir.adoc`, and
|
||||
`docs/fenrir.1`. The script can run from any working directory.
|
||||
`./docs/create_manpage.sh` to regenerate `docs/user.txt` and `docs/fenrir.1`.
|
||||
The script can run from any working directory. Edit the Markdown source rather
|
||||
than the generated files. The bundled `docs/man_tables.lua` filter renders
|
||||
man-page tables as labeled lists for narrow terminals.
|
||||
|
||||
Please review documentation and test instructions for the affected workflow
|
||||
before submitting a change, as described in the README's contribution policy.
|
||||
|
||||
Reference in new issue
Block a user