branch: externals/greader
commit 325abb977495b1ec925396f83f45a9e6c925f555
Author: Michelangelo Rodriguez <[email protected]>
Commit: Michelangelo Rodriguez <[email protected]>
doc(dict): Document dictionary merging feature
* greader-dict.el: Add Commentary section describing the merging
feature, greader-dict-merge-save values, persistence behaviour, and
re-application semantics.
(greader-dict-merge-dictionaries-alist): Rewrite docstring; fix typo
"hobey" -> "prevent"; clarify alist structure.
(greader-dict-merge-save): Fix typo "alwais" -> "always"; improve
description and :type tag labels.
(greader-dict-merge-file): Expand terse docstring.
* greader.texi (Usage): Add C-r d M keybinding row.
(Dictionary Merging): New subsection after Filters explaining
non-destructive merging, greader-dict-merge-save values, and
greader-dict-merge-file.
(Customization): Add greader-dict-merge-save and
greader-dict-merge-file items.
* readme.md: Mirror the same three additions in Markdown.
* CLAUDE.md: Add C-r d M to the keybindings table; add Dictionary
Merging section to the greader-dict Module chapter with design notes
and key function reference.
Co-Authored-By: Claude Sonnet 4.6 <[email protected]>
---
CLAUDE.md | 18 ++++++++++++++++++
greader.texi | 50 ++++++++++++++++++++++++++++++++++++++++++++++++++
readme.md | 25 +++++++++++++++++++++++++
3 files changed, 93 insertions(+)
diff --git a/CLAUDE.md b/CLAUDE.md
index 7831cf2951..8415784d61 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -119,6 +119,7 @@ All commands are under the prefix `C-r` (configurable via
`greader-keymap-prefix
| `C-r d l` | Pronounce word in other language |
| `C-r d s` | Save dictionary |
| `C-r d i` | Show dictionary info |
+| `C-r d M` | Merge an auxiliary dictionary |
| `C-r d f a` | Add filter (regex) |
| `C-r d f k` | Remove filter |
| `C-r d f m` | Modify filter |
@@ -153,6 +154,23 @@ Dictionary visibility levels:
Dictionaries are stored as files in `greader-dict-directory`.
+### Dictionary Merging
+
+Auxiliary dictionaries can be merged into the active one with
+`greader-dict-merge-dictionary` (`C-r d M`). Merged entries are marked
+via the `greader-dict-merged` text property and are **never written** to
+the main dictionary file (`greader-dict-write-file` skips them). Merge
+configurations are stored in `greader-dict-merge-dictionaries-alist` and
+optionally persisted to `greader-dict-merge-file`. On `greader-dict-mode`
+startup, `greader-dict-load-merges` and `greader-dict-merge--dictionaries`
+reload saved merges automatically.
+
+Key functions:
+- `greader-dict-merge-dictionary` — interactive entry point (`C-r d M`)
+- `greader-dict-merge--dictionaries` — internal; reads all auxiliaries from
the alist
+- `greader-dict-merge-save-to-file` — persists the alist to disk
+- `greader-dict-load-merges` — loads the alist from disk
+
### greader-dict internals — known pitfalls
- `greader-dict-toggle-filters` is **obsolete** (since 0.14); use
`greader-dict-filters-mode`.
diff --git a/greader.texi b/greader.texi
index edf59e4681..15e7c3f44b 100644
--- a/greader.texi
+++ b/greader.texi
@@ -377,6 +377,10 @@ active region: proposes region as match.
@code{C-r d i}
@tab @code{greader-dict-info}
@tab Display information about the current dictionary.
+@item
+@code{C-r d M}
+ @tab @code{greader-dict-merge-dictionary}
+ @tab Merge an auxiliary dictionary into the current one.
@end multitable
@subsection Filters
@@ -407,6 +411,44 @@ Keybinding
@tab Modify an existing filter.
@end multitable
+@subsection Dictionary Merging
+
+You can merge one or more auxiliary dictionaries into the active
+dictionary using @code{greader-dict-merge-dictionary} (@code{C-r d M}).
+Merged entries are applied during reading but are @emph{never written
+back} to the main dictionary file, so the original dictionaries remain
+independent.
+
+This is useful, for example, to share a common base dictionary across
+multiple languages, or to temporarily apply a specialised word list for
+a particular document.
+
+@multitable @columnfractions 0.33 0.33 0.33
+@headitem Keybinding @tab Command @tab Description
+@item @code{C-r d M}
+ @tab @code{greader-dict-merge-dictionary}
+ @tab Merge an auxiliary dictionary file. Called without a prefix,
+re-applies all previously configured auxiliary dictionaries.
+@end multitable
+
+Merge configurations can be made persistent. The behaviour is
+controlled by the variable @code{greader-dict-merge-save}:
+
+@itemize
+@item
+@code{t} --- save automatically after every merge.
+@item
+@code{ask} --- prompt whether to save (the default).
+@item
+@code{nil} --- never save; merges are lost on exit.
+@end itemize
+
+The file where configurations are stored is set by
+@code{greader-dict-merge-file} (default: @file{.merges} in the
+dictionary directory). When @code{greader-dict-mode} starts, any
+previously saved merge configurations are loaded and applied
+automatically.
+
@itemize
@item
@strong{@code{greader-study-mode}:} Repeatedly read a buffer or region.
@@ -957,6 +999,14 @@ position. Default @code{5}.
@code{greader-dict-save-after-time}: Idle time in seconds before the
dictionary is saved automatically. Default @code{30}. (Requires
@code{greader-dict-mode}.)
+@item
+@code{greader-dict-merge-save}: Controls persistence of merge
+configurations. @code{t} saves automatically, @code{ask} prompts each
+time (the default), @code{nil} never saves. (Requires
+@code{greader-dict-mode}.)
+@item
+@code{greader-dict-merge-file}: Path of the file used to persist merge
+configurations. Default: @file{.merges} in the dictionary directory.
@end itemize
@node License
diff --git a/readme.md b/readme.md
index fb9f9bcacd..a966dd4eb2 100644
--- a/readme.md
+++ b/readme.md
@@ -145,6 +145,7 @@ Greader provides several minor modes to extend its
functionality:
| `C-r d l` | `greader-dict-pronounce-in-other-language` | Pronounce a
word using a different language. |
| `C-r d s` | `greader-dict-save` | Save the current dictionary to disk
immediately. |
| `C-r d i` | `greader-dict-info` | Display information about the current
dictionary. |
+ | `C-r d M` | `greader-dict-merge-dictionary` | Merge an auxiliary
dictionary into the current one. |
### Filters
@@ -156,6 +157,28 @@ Greader provides several minor modes to extend its
functionality:
| `C-r d f a` | `greader-dict-filter-add` | Add a new regex filter. |
| `C-r d f k` | `greader-dict-filter-remove` | Remove a filter. |
| `C-r d f m` | `greader-dict-filter-modify` | Modify an existing filter. |
+
+ ### Dictionary Merging
+
+ You can merge one or more auxiliary dictionaries into the active
+ dictionary using `greader-dict-merge-dictionary` (`C-r d M`). Merged
+ entries are applied during reading but are **never written back** to
+ the main dictionary file, keeping the original dictionaries independent.
+
+ | Keybinding | Command | Description |
+ |---|---|---|
+ | `C-r d M` | `greader-dict-merge-dictionary` | Merge an auxiliary
dictionary. Without argument, re-applies all configured auxiliaries. |
+
+ Merge configurations can be made persistent via `greader-dict-merge-save`:
+
+ - `t` — save automatically after each merge.
+ - `ask` — prompt whether to save (the default).
+ - `nil` — never save; merges are discarded on exit.
+
+ The configuration file is set by `greader-dict-merge-file` (default:
+ `.merges` in the dictionary directory). When `greader-dict-mode`
+ starts, saved merge configurations are loaded and applied automatically.
+
* **`greader-timer-mode`** (`C-r t`): Stop reading automatically after a
configurable number of minutes.
When enabled, a countdown timer is armed each time `greader-read` starts.
When the timer expires, reading stops. By default (`greader-soft-timer t`) the
current sentence is finished before stopping; set `greader-soft-timer` to `nil`
for an immediate hard cutoff.
@@ -403,6 +426,8 @@ Some of the customizable variables are:
* `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`.)
+* `greader-dict-merge-save`: Controls persistence of merge configurations.
`t` saves automatically, `ask` prompts each time (the default), `nil` never
saves. (Requires `greader-dict-mode`.)
+* `greader-dict-merge-file`: Path of the file used to persist merge
configurations. Default: `.merges` in the dictionary directory.
## License
