Notification sound added. Docs updated.

docs/fenrir.1

@@ -1,4 +1,4 @@
-.\" Automatically generated by Pandoc 3.12.1
+.\" Automatically generated by Pandoc 3.13
 .\"
 .TH "fenrir" "1" "" "" "Fenrir User Manual"
 .SH Fenrir User Manual
@@ -59,15 +59,22 @@ It releases keyboard input on graphical virtual terminals and on text
 consoles selected in \f[CR]screen.ignored_vts\f[R].
 .SS Keyboard layouts and help
 The \f[B]Fenrir key\f[R] is Insert, Super/Windows, or keypad 0 with
-NumLock off.
+NumLock off in the desktop layout.
+The laptop layout uses Caps Lock instead of Super/Windows; Insert and
+NumLock\-off keypad 0 also work.
+Press Shift+Caps Lock on its own to toggle capitalization in the laptop
+layout.
+Shifted Fenrir shortcuts do not toggle capitalization.
 Hold it while pressing the other keys in a shortcut.
 Bare keypad review keys also require NumLock off.
 .PP
 The desktop layout uses the numeric keypad.
 The laptop layout uses Fenrir chords on the main keyboard.
 Select a layout with \f[CR]\-\-keyboard\-layout desktop\f[R] or
-\f[CR]\-\-keyboard\-layout laptop\f[R], or set
-\f[CR]keyboard.layout\f[R] in the settings file.
+\f[CR]\-\-keyboard\-layout laptop\f[R], choose Desktop or Laptop in the
+Keyboard tab of the Fenrir Menu, or set \f[CR]keyboard.layout\f[R] in
+the settings file.
+Menu layout changes take effect on the next launch.
 .PP
 Press \f[B]Fenrir+H\f[R] or \f[B]Fenrir+F1\f[R] to enter the tutorial.
 Command shortcuts are announced and described instead of executed.
@@ -225,12 +232,24 @@ Character echo, word echo, and cursor echo can be configured separately.
 Punctuation levels are \f[CR]none\f[R], \f[CR]some\f[R],
 \f[CR]most\f[R], and \f[CR]all\f[R].
 At \f[CR]some\f[R] and \f[CR]most\f[R], punctuation inside words, URLs,
-email addresses, and filenames is also named.
+email addresses, and filenames is also named, without adding sentence
+pauses.
 Apostrophes within words and single numeric separators such as those in
 \f[CR]3.14\f[R], \f[CR]1,000\f[R], and \f[CR]12:30\f[R] follow the
 selected level.
 Sentence punctuation follows the selected level too.
+Multiple dots in numeric sequences are named, so \f[CR]2026.10.31\f[R]
+is read as \(lq2026 dot 10 dot 31\(rq at \f[CR]some\f[R] and
+\f[CR]most\f[R].
+A percent sign immediately after a digit is named at \f[CR]some\f[R] and
+\f[CR]most\f[R], so \f[CR]100%\f[R] is read as \(lq100 percent\(rq.
 Character review always names punctuation.
+Repeated\-symbol summaries handle multiple runs in symbol\-only tokens,
+including diffstats such as \f[CR]+++++\-\-\-\-\-\f[R] and bracketed
+bars such as \f[CR][#####\-\-\-\-\-]\f[R].
+Each run must reach the configured minimum length and be selected by the
+current punctuation level; shorter runs follow ordinary punctuation
+handling.
 Capital indicators, emoticons, repeated\-symbol summaries, indentation
 feedback, and attribute feedback are configurable in Reading.
 .PP
@@ -918,6 +937,31 @@ Earlier directories take priority.
 A filename such as \f[CR]example__\-__key_y.sh\f[R] assigns the script
 key plus Y. The script key defaults to Compose and is configured by
 \f[CR]general.script_keys\f[R].
+The Keyboard tab of the Fenrir Menu has separate \f[B]Fenrir keys\f[R]
+and \f[B]Script keys\f[R] checkbox groups for keypad Insert, Insert,
+Caps Lock, and Super; Compose is also available for scripts.
+Uncheck a key in one group before assigning it to the other.
+A physical key cannot serve both roles, including through an alias such
+as \f[CR]KEY_META\f[R] and \f[CR]KEY_RIGHTMETA\f[R].
+At least one Fenrir key must remain selected.
+After \f[B]OK\f[R] saves the changes, modifier assignments apply when
+the menu closes and all held keys are released.
+Cancel leaves them unchanged.
+If X11 cannot acquire the new keys, Fenrir reports the failure and
+retains the previous active assignments.
+The saved choices remain in the file; reopen the menu to edit or retry
+them.
+Desktop/laptop layout changes still require a new launch.
+.PP
+The Fenrir\-key checkboxes save \f[CR]keyboard.fenrir_keys\f[R], which
+overrides the layout\(cqs defaults.
+When that setting is omitted, the layout supplies defaults and
+explicitly configured script keys are excluded from them.
+Existing custom script keys remain unchanged when editing the
+checkboxes.
+Keypad Insert acts as a modifier only with NumLock off.
+Shift+Caps Lock toggles capitalization when Caps Lock serves either
+role.
 Scripts must be executable to run.
 Fenrir invokes them directly and passes the current account name as the
 first argument.
@@ -926,6 +970,16 @@ Commands appear in the tutorial\(cqs script list.
 .SS Notifications
 Send \f[CR]command notify TEXT\f[R] to speak and remember a
 notification.
+When sounds are enabled and their volume is above zero, Fenrir plays the
+theme\(cqs \f[CR]notification\f[R] cue (\f[CR]notification.wav\f[R] in
+the default theme), waits for the audio output to drain, then speaks the
+message.
+Sound playback runs outside the input loop.
+Missing or failed sound output leaves speech available.
+Speech mute or temporary silence keeps the sound and history, with no
+spoken message.
+Recalling a notification does not replay its sound.
+.PP
 \f[B]Fenrir+N\f[R] repeats the most recent notification.
 \f[B]Fenrir+Control+N\f[R] opens a list of the latest 100 notifications
 for this reader session, newest first.