branch: externals/greader
commit 15bd6f190c192a38d12ddb942ac596494f0d2650
Author: Michelangelo Rodriguez <[email protected]>
Commit: Michelangelo Rodriguez <[email protected]>
docs: document time-based seek commands in all three doc files
* readme.md (Navigation): Add C-<left>/C-<right>/M-<left>/M-<right>
bindings with description of default values and numeric prefix behavior.
(Customization): Add greader-move-default-seconds and
greader-move-default-minutes variables.
* CLAUDE.md (Key Keybindings): Add the four new seek bindings.
(Development Notes): Add note on greader-move-by-time internals
(WPM formula, conditional sentence snap, greader--seek helper) and
on the defvar+define-key keymap pattern.
* greader.texi (Navigation): Rewrite subsection as a proper @multitable
(was broken Markdown syntax); add rows for the four seek commands.
(Customization): Add greader-move-default-seconds and
greader-move-default-minutes.
---
CLAUDE.md | 13 +++++++++++++
greader.texi | 60 ++++++++++++++++++++++++++++++++++++++++++++++++++----------
readme.md | 6 ++++++
3 files changed, 69 insertions(+), 10 deletions(-)
diff --git a/CLAUDE.md b/CLAUDE.md
index 870ab6bd1b..af3e295151 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -116,6 +116,8 @@ All commands are under the prefix `C-r` (configurable via
`greader-keymap-prefix
| `C-r s` | `greader-tired-mode` — toggle tired/relax mode |
| `C-r f` | Get text attributes |
| `←` / `→` | Navigate backward/forward sentence |
+| `C-←` / `C-→` | Seek backward/forward by `greader-move-default-seconds`
seconds (default 30); numeric prefix overrides |
+| `M-←` / `M-→` | Seek backward/forward by `greader-move-default-minutes`
minutes (default 1); numeric prefix overrides |
| `p` | Toggle punctuation |
| `.` | Stop with timer |
| `+` / `-` | Increase/decrease speech rate by 10 WPM |
@@ -235,6 +237,17 @@ Tests are in `greader-dict-tests.el` (covers dict
functionality).
following the GNU Emacs convention. Only `greader.texi` (the Texinfo source)
is tracked.
Generate with: `makeinfo greader.texi -o greader.info`
- `greader-tired-mode` internals: the wakeup intercept uses
`greader--tired-intercept-mode`, a transient buffer-local minor mode with a
`[t]` catch-all keymap. Any key press calls `greader--tired-wakeup` (swallowing
the command) and resumes reading. With `greader-soft-timer` on, the idle timer
is armed in `greader--default-action` (after the last sentence finishes) via
`greader--tired-pending`, not in `greader-stop-timer-callback`. `greader-stop`
clears `greader--tired-pending` to preven [...]
+- Time-based seek API: `greader-move-by-time` computes a word offset as
+ `round(rate × abs(time) / 60.0)`, moves with `forward-word`, then snaps to a
sentence
+ boundary via `greader-forward-sentence` / `greader-backward-sentence` —
UNLESS the
+ sentence at the destination is longer (in words) than the offset, in which
case point
+ stays at the raw word-level position to avoid over-shooting. The internal
helper
+ `greader--seek` wraps the full stop→move→register→read sequence. Public
commands:
+ `greader-move-by-seconds-backward/forward` (`C-←`/`C-→`) and
+ `greader-move-by-minutes-backward/forward` (`M-←`/`M-→`); all accept a
numeric prefix.
+ Keymap definitions use `defvar (make-sparse-keymap)` + top-level
`define-key` calls so
+ that re-evaluating any keymap defvar during development does not orphan the
object
+ stored in `minor-mode-map-alist`.
- `greader-audiobook-convert-block` uses `greader-call-backend 'audio-write` —
do not
hardcode espeak-ng there. Error handling: non-zero exit code + WAV size check
(`greader-audiobook-min-wav-size`). Hard-error policy:
`greader-audiobook-on-error`
diff --git a/greader.texi b/greader.texi
index 299e0caa45..12285f83eb 100644
--- a/greader.texi
+++ b/greader.texi
@@ -186,16 +186,46 @@ enabling @code{greader-timer-mode} directly.
@node Navigation
@subsection Navigation
-The following commands work when you are in
-@code{greader-reading-mode', which happens when you call}greader-read'.
-| Keybinding | Command | Description | |---|---|---| | @code{<left>} |
-@code{greader-backward} | Move to the previous sentence. | |
-@code{<right>} | @code{greader-forward} | Move to the next sentence. | |
-@code{p} | @code{greader-toggle-punctuation} | Toggle reading of
-punctuation characters. | | @code{.} | @code{greader-stop-with-timer} |
-Stop reading and reset the timer. | | @code{+} | @code{greader-inc-rate}
-| Increase speech rate by 10 WPM. | | @code{-} | @code{greader-dec-rate}
-| Decrease speech rate by 10 WPM. |
+The following commands work when you are in @code{greader-reading-mode},
+which is active while @code{greader-read} is running.
+
+@multitable @columnfractions 0.30 0.35 0.35
+@headitem Keybinding @tab Command @tab Description
+@item @code{<left>}
+ @tab @code{greader-backward}
+ @tab Move to the previous sentence.
+@item @code{<right>}
+ @tab @code{greader-forward}
+ @tab Move to the next sentence.
+@item @code{C-<left>}
+ @tab @code{greader-move-by-seconds-backward}
+ @tab Seek backward by @code{greader-move-default-seconds} seconds
+(default 30). A numeric prefix overrides the default.
+@item @code{C-<right>}
+ @tab @code{greader-move-by-seconds-forward}
+ @tab Seek forward by @code{greader-move-default-seconds} seconds
+(default 30). A numeric prefix overrides the default.
+@item @code{M-<left>}
+ @tab @code{greader-move-by-minutes-backward}
+ @tab Seek backward by @code{greader-move-default-minutes} minutes
+(default 1). A numeric prefix overrides the default.
+@item @code{M-<right>}
+ @tab @code{greader-move-by-minutes-forward}
+ @tab Seek forward by @code{greader-move-default-minutes} minutes
+(default 1). A numeric prefix overrides the default.
+@item @code{p}
+ @tab @code{greader-toggle-punctuation}
+ @tab Toggle reading of punctuation characters.
+@item @code{.}
+ @tab @code{greader-stop-with-timer}
+ @tab Stop reading and reset the timer.
+@item @code{+}
+ @tab @code{greader-inc-rate}
+ @tab Increase speech rate by 10 WPM.
+@item @code{-}
+ @tab @code{greader-dec-rate}
+ @tab Decrease speech rate by 10 WPM.
+@end multitable
@node Commands
@section Commands
@@ -1039,6 +1069,16 @@ mode.
@code{"07"}) at which @code{greader-auto-tired-mode} deactivates tired
mode. Intervals crossing midnight are supported.
@item
+@code{greader-move-default-seconds}: Default number of seconds used by
+@code{greader-move-by-seconds-backward} and
+@code{greader-move-by-seconds-forward} (@kbd{C-<left>}/@kbd{C-<right>}).
+Default @code{30}.
+@item
+@code{greader-move-default-minutes}: Default number of minutes used by
+@code{greader-move-by-minutes-backward} and
+@code{greader-move-by-minutes-forward} (@kbd{M-<left>}/@kbd{M-<right>}).
+Default @code{1}.
+@item
@code{greader-backward-acoustic-feedback}: If @code{t}, plays a brief
beep when the cursor returns to the previous reading position after
backward navigation. Default @code{nil}.
diff --git a/readme.md b/readme.md
index ca95f7de07..de2b09636e 100644
--- a/readme.md
+++ b/readme.md
@@ -71,6 +71,10 @@ The following commands work when you are in
`greader-reading-mode', which happen
|---|---|---|
| `<left>` | `greader-backward` | Move to the previous sentence. |
| `<right>` | `greader-forward` | Move to the next sentence. |
+| `C-<left>` | `greader-move-by-seconds-backward` | Seek backward by
`greader-move-default-seconds` seconds (default 30). With a numeric prefix,
seek by that many seconds instead. |
+| `C-<right>` | `greader-move-by-seconds-forward` | Seek forward by
`greader-move-default-seconds` seconds (default 30). With a numeric prefix,
seek by that many seconds instead. |
+| `M-<left>` | `greader-move-by-minutes-backward` | Seek backward by
`greader-move-default-minutes` minutes (default 1). With a numeric prefix, seek
by that many minutes instead. |
+| `M-<right>` | `greader-move-by-minutes-forward` | Seek forward by
`greader-move-default-minutes` minutes (default 1). With a numeric prefix, seek
by that many minutes instead. |
| `p` | `greader-toggle-punctuation` | Toggle reading of punctuation
characters. |
| `.` | `greader-stop-with-timer` | Stop reading and reset the timer. |
| `+` | `greader-inc-rate` | Increase speech rate by 10 WPM. |
@@ -456,6 +460,8 @@ Some of the customizable variables are:
* `greader-tired-time`: Idle seconds to wait after the reading timer expires
before moving point back (default 60). Used by `greader-tired-mode`.
* `greader-auto-tired-mode-time`: Hour (as a string, e.g. `"22"`) at which
`greader-auto-tired-mode` activates tired mode.
* `greader-auto-tired-time-end`: Hour (as a string, e.g. `"07"`) at which
`greader-auto-tired-mode` deactivates tired mode. Intervals crossing midnight
are supported.
+* `greader-move-default-seconds`: Default number of seconds used by
`greader-move-by-seconds-backward` and `greader-move-by-seconds-forward`.
Default `30`.
+* `greader-move-default-minutes`: Default number of minutes used by
`greader-move-by-minutes-backward` and `greader-move-by-minutes-forward`.
Default `1`.
* `greader-backward-acoustic-feedback`: If `t`, plays a brief beep when the
cursor returns to the previous reading position after backward navigation.
Default `nil`.
* `greader-backward-seconds`: Number of seconds to wait at the previous
sentence before automatically returning to the reading position. Default `5`.
* `greader-dict-save-after-time`: Idle time in seconds before the dictionary
is saved automatically. Default `30`. (Requires `greader-dict-mode`.)
