feat: Slim dictionary (#2583)

Co-authored-by: Ryan Hitchman <hitchmanr@gmail.com> Co-authored-by: Kurtis Grant <kurtis.b.grant@gmail.com> Co-authored-by: kemonine <kemonine@kemonine.info> Co-authored-by: DustinHu <hu.dustin@gmail.com> Co-authored-by: Justin Mitchell <justin@jmitch.com>
2026-07-19 17:57:16 +03:00
parent 5ba1d5747f
commit b1d1d757ba
27 changed files with 1919 additions and 10 deletions
@@ -0,0 +1,51 @@
+# Dictionary
+
+Look up words while reading an EPUB using an offline StarDict dictionary stored on the SD card.
+
+## Supported Format
+
+The reader supports **StarDict** dictionaries. When searching for dictionaries online, look for "StarDict format" or files with `.dict`, `.idx`, and `.ifo` extensions.
+
+A dictionary folder must contain:
+
+- `.idx` — word index (required, **must be uncompressed** — a `.idx.gz` will not work; decompress it on your computer with `gzip -d` first)
+- `.dict` or `.dict.dz` — definition data (`.dict.dz` is supported as-is; entries are decompressed on the fly during lookup)
+- `.ifo` — metadata (optional)
+
+Not supported: `.syn` synonym files (ignored), dictionaries with 64-bit index offsets (`idxoffsetbits=64` in the `.ifo` — rare, and rejected with an error), and HTML-formatted definitions render as raw markup rather than styled text.
+
+## Setting Up a Dictionary
+
+1. Copy your dictionary folder(s) to `/dictionaries/` on the SD card — one dictionary per folder, e.g. `/dictionaries/webster/webster.idx` + `webster.dict.dz`. A hidden `/.dictionaries/` folder (dot-prefixed) works the same way, for keeping it out of the file browser.
+2. Open **Settings → Reader → Dictionary** on the device.
+3. Select a dictionary from the list, or **None** to disable lookups.
+
+The Dictionary setting only appears when at least one usable dictionary folder exists. Folders containing more than one dictionary (multiple `.idx` stems) are skipped as ambiguous.
+
+## Looking Up a Word
+
+Two ways to start a lookup while reading:
+
+- Open the reader menu (**Confirm**) and choose **Look Up**.
+- Or set **Settings → Controls → Long-press Menu** to "Dictionary", then hold **Confirm** (~0.4s) on the reading page.
+
+One word on the page becomes highlighted:
+
+1. Use **Left/Right** to move between words in reading order, and the side **Up/Down** buttons to jump between lines.
+2. Press **Confirm** to look up the highlighted word.
+3. Press **Back** to return to the reader.
+
+On the very first lookup with a dictionary (and again if the dictionary file changes), the reader shows *"Indexing dictionary…"* while it builds a small `.qidx` sidecar file next to the `.idx`. This takes a few seconds for large dictionaries and makes all subsequent lookups fast. The sidecar can be deleted safely at any time — it will simply be rebuilt.
+
+### How Lookup Works
+
+1. **Direct match** — the word is found as-is (case-insensitive) in the dictionary index. Surrounding punctuation is ignored.
+2. **Stemming** — on a miss, common English word forms are retried automatically: possessives and plurals (`dogs` → `dog`, `stories` → `story`) and verb endings (`walked` → `walk`, `running` → `run`, `making` → `make`).
+3. **Not found** — a short popup appears and you return to word selection.
+
+## The Definition Screen
+
+When a word is found, the definition screen shows the matched headword at the top and the definition text below, with a page counter for long definitions.
+
+- **Left/Right** or side **Up/Down** — previous / next page
+- **Back** — return to word selection