fix(help): full index audit and singular/plural keyword matching #122

2026-09-01T02:07:34Z

rootiest commented

2026-09-01 02:07:34 +00:00

customization resolved but customizations didn't, and a number of recent additions were never indexed. Both fixed.

Why the plural failed

The fallback matches a keyword contained in a heading, so a plural could never reach a singular heading:

norm('customization')  in norm('# 7. CUSTOMIZATION') = '7customization'  ✓
norm('customizations') in norm('# 7. CUSTOMIZATION') = '7customization'  ✗

The index lookup was exact-match, so it couldn't cover the gap either without an alias for every word. Now both try the keyword as typed first, then its singular/plural forms — and each variant is tried against every heading before the next is considered, so a loose plural can't beat an exact hit further down the document.

Index audit

284 → 357 entries (+75 added, 2 duplicate keys removed).

Every previously unindexed heading is now reachable, including play-media, steam-dl, bd-pull, cffetch, ffetch, config-toggle, ld, lD, mv, p, fast-cli, gip4/gip6, dops, rand_string, fzf-update, the prompt functions, and the C1–C6 sub-categories.
Aliases follow what someone would actually type: play-media via video/audio/mpv/vlc, rand_string via random/password, fast-cli via speedtest, ld via lazydocker, gip4/gip6 via ipv4/ipv6.
Two normalized-key collisions resolved (key-bindings/keybindings, man-page/manpage) — they normalize identically, so one of each was dead weight.
config-toggle repointed to its own heading, which now exists.

Deliberately left unindexed: the seven identical ### Sub-categories headings. Any entry pointing at that text always resolves to the first occurrence, so it would be misleading; each parent (C1–C6, Minimal Mode) already has its own keyword. Same reasoning for the duplicate ### search and ## Integrations headings.

Verification

Checked independently against the generated document, not just self-reported:

entries: 357   distinct targets: 231
stale targets (value is not a real heading): 0
normalized-key collisions: 0
headings with no entry: 1   (### Sub-categories, intentional)

Resolution spot-checked end to end — singular and plural both directions (customization/customizations, abbreviation/abbreviations, binding/bindings, plugin/plugins, variable/variables), every new alias above, and a regression pass confirming exact keys still win (functions, path, fzf, prompt, network, sync).

tests/run-tests.fish 220/220 lint + 10/10, verify-manual.py 71/71.

Independent of #121 — verified the two merge cleanly.

`customization` resolved but `customizations` didn't, and a number of recent additions were never indexed. Both fixed. ## Why the plural failed The fallback matches a keyword **contained in** a heading, so a plural could never reach a singular heading: ``` norm('customization') in norm('# 7. CUSTOMIZATION') = '7customization' ✓ norm('customizations') in norm('# 7. CUSTOMIZATION') = '7customization' ✗ ``` The index lookup was exact-match, so it couldn't cover the gap either without an alias for every word. Now both try the keyword **as typed first**, then its singular/plural forms — and each variant is tried against every heading before the next is considered, so a loose plural can't beat an exact hit further down the document. ## Index audit **284 → 357 entries** (+75 added, 2 duplicate keys removed). - Every previously unindexed heading is now reachable, including `play-media`, `steam-dl`, `bd-pull`, `cffetch`, `ffetch`, `config-toggle`, `ld`, `lD`, `mv`, `p`, `fast-cli`, `gip4`/`gip6`, `dops`, `rand_string`, `fzf-update`, the prompt functions, and the C1–C6 sub-categories. - Aliases follow what someone would actually type: `play-media` via `video`/`audio`/`mpv`/`vlc`, `rand_string` via `random`/`password`, `fast-cli` via `speedtest`, `ld` via `lazydocker`, `gip4`/`gip6` via `ipv4`/`ipv6`. - Two normalized-key collisions resolved (`key-bindings`/`keybindings`, `man-page`/`manpage`) — they normalize identically, so one of each was dead weight. - `config-toggle` repointed to its own heading, which now exists. **Deliberately left unindexed:** the seven identical `### Sub-categories` headings. Any entry pointing at that text always resolves to the first occurrence, so it would be misleading; each parent (C1–C6, Minimal Mode) already has its own keyword. Same reasoning for the duplicate `### search` and `## Integrations` headings. ## Verification Checked independently against the generated document, not just self-reported: ``` entries: 357 distinct targets: 231 stale targets (value is not a real heading): 0 normalized-key collisions: 0 headings with no entry: 1 (### Sub-categories, intentional) ``` Resolution spot-checked end to end — singular and plural both directions (`customization`/`customizations`, `abbreviation`/`abbreviations`, `binding`/`bindings`, `plugin`/`plugins`, `variable`/`variables`), every new alias above, and a regression pass confirming exact keys still win (`functions`, `path`, `fzf`, `prompt`, `network`, `sync`). `tests/run-tests.fish` 220/220 lint + 10/10, `verify-manual.py` 71/71. Independent of #121 — verified the two merge cleanly.

rootiest added 2 commits 2026-09-01 02:07:35 +00:00

docs(index): full audit of the config-help keyword index 618ce00f9e

Cover the ~50 previously-unindexed headings (function reference entries
like play-media, steam-dl, bd-pull, cffetch/ffetch, config-toggle, dops,
rand_string, fish_prompt/fish_mode_prompt/fish_right_prompt, lD, mv, p,
fast/fast-cli, gip4/gip6, fzf-update, sponge_filter_secrets,
fzf_configure_bindings, ld; the C1-C6 component sub-category headings
filesystem/network/monitor/shell-tools/dev-tools,
plugin-management/pkg-wrappers/venv/telemetry/sync,
key-bindings/environment/prompt, terminal-abbrs/window-mgmt/
notifications/history-logs/pkg-upgrade, terminal-capture/
multiplexer-capture/pkg-logs, first-run/greeting-message; plus
Config Variables' "Other", the Integrations "Scrollback History", the
dependency catalog's Optional/Terminal Emulators tiers, the C0/always
override note, and "Reading the source directly").

Expanded aliases for existing headings: play-media also reachable as
video/audio/mpv/vlc, steam-dl as steam, cffetch/ffetch share fetch/
fastfetch/neofetch/sysinfo, rand_string as random/password/randomword,
gip4/gip6 as ipv4/ipv6, dops as docker-ps, ld as lazydocker, bd-pull as
beads, fast-cli as speedtest, sponge_filter_secrets as secret-filter.

Fixed two pre-existing duplicate normalized keys (key-bindings/
keybindings and man-page/manpage both collapsed to a single entry) and
repointed config-toggle from the generic config-settings heading to its
own dedicated "### config-toggle" heading now that one exists.

Judgment calls on ambiguous/repeated heading text (left unindexed, or
indexed via a distinguishing keyword instead of the literal name):
- "### Sub-categories" repeats 7 times (once per opinionated-components
  overview and once per C1-C6 page); an index entry pointing at that
  text always resolves to the first occurrence, so none of the 7 are
  indexed under that name. Each parent (C1-C6, and the Minimal Mode
  section) already has its own keyword.
- "### search" appears twice: the pkg search subcommand (kept, existing
  `search` key) and the C1 command-shadow sub-category. The C1 one
  isn't separately reachable for the same reason.
- "## Integrations" appears twice (Section 1 integrations writeup and
  the Dependency Catalog's Integrations tier table); only the first
  (already indexed) is reachable.
- Where a C1-C6 sub-category heading text collides after normalization
  with an existing higher-value keyword (key-bindings, network,
  notifications, venv), the new entry uses a distinguishing keyword
  (bindings-toggle, network-shadow, notifications-toggle, venv-toggle)
  instead of contesting the existing one.
- `prompt` now points at the fuller "## Prompt and Theme" section
  rather than the one-line C3 sub-category blurb; the latter is
  reachable via `prompt-toggle`.

fix(help): resolve singular and plural section keywords 6cf690e637

The heading scan matches a keyword contained in a heading, so a plural
could never reach a singular heading: `customization` found "7.
CUSTOMIZATION" and `customizations` found nothing at all. The index
lookup was exact-match, so it could not cover the gap either without an
alias per word.

Both now try the keyword as typed first, then its singular/plural
forms. Each variant is tried against every heading before the next one
is considered, so a loose plural cannot beat an exact hit further down
the document.

rootiest merged commit 5328529e18 into main

2026-09-01 02:11:54 +00:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: rootiest/fish-config#122