Skip to content

docs(rtl): make the extractor table say what NORM and TRIM do - #8

Merged
shigarov merged 1 commit into
mainfrom
docs/extractor-table-wording
Aug 26, 2026
Merged

docs(rtl): make the extractor table say what NORM and TRIM do#8
shigarov merged 1 commit into
mainfrom
docs/extractor-table-wording

Conversation

@shigarov

Copy link
Copy Markdown
Contributor

Documentation only — no behaviour change, no version bump.

The extractor table

before after
NORM Collapse whitespace Trim + collapse internal whitespace
TRIM Trim Strip leading/trailing whitespace only

TRIM's cell defined the extractor as itself. NORM's was incomplete: norm_whitespace is java_strip plus run collapsing, so NORM is strictly stronger than TRIM rather than orthogonal to it — the old table gave the opposite impression. Both rows now match what docs/model/atp.md already said for the same extractors, and the "only" in TRIM's row carries the contrast.

This table is also the source of the rtl-lsp hover dictionary — vscode-rtl/tools/gen_hover_data.py harvests it — so the VS Code extension was showing TRIM → Trim as its tooltip. Verified: regenerating against this branch changes exactly those two hover entries and nothing else. That regeneration belongs to the vscode-rtl side and is not part of this PR.

Deliberately not adding a cross-reference to the delimited specification here. TRIM applies to any atom — atomic cells, compound segments and delimited tokens alike — and singling out delimited use would invert the relationship: it is the "Semantics of S_delim" section that points at the extractor. It would also be misleading, since =NORM trims just as well, and would break the register of a table whose every other row is a bare effect phrase.

Broken anchor from 0.5.0

mkdocs build --strict reported:

Doc file 'rtl-reference.md' contains a link '#atomic--contspec', but there is no such anchor on this page.

The link was added in the 0.5.0 S_delim work, carried over from the jRegTab wording where GitHub's slugifier produces a double hyphen. The docs here are published with mkdocs, which renders ### Atomic — contSpec as id="atomic-contspec". Fixed; the build no longer reports it.

mkdocs build --strict   clean
pytest tests -q         1918 passed

🤖 Generated with Claude Code

The RTL reference described `TRIM` as "Trim" -- a tautology -- and `NORM` as
"Collapse whitespace", which is incomplete: norm_whitespace strips the edges
too, so NORM is strictly stronger than TRIM rather than orthogonal to it. Both
rows now match the wording docs/model/atp.md already used for the same
extractors, and the "only" in TRIM's row carries the contrast.

This table is also the source of the rtl-lsp hover dictionary
(vscode-rtl/tools/gen_hover_data.py harvests it), so the extension showed
"TRIM -> Trim" as its tooltip. Regenerating there now yields something useful;
that regeneration belongs to the vscode-rtl side.

Deliberately not cross-referencing the delimited specification here: TRIM
applies to any atom, and it is the "Semantics of S_delim" section that points
at the extractor, not the other way round.

Also fixes an in-page link added in 0.5.0: the anchor for "Atomic -- contSpec"
is `#atomic-contspec` under mkdocs, not the GitHub-style `#atomic--contspec`
carried over from the jRegTab wording. `mkdocs build --strict` reported it as
an unresolved anchor.

No behaviour change; documentation only.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
@shigarov
shigarov merged commit 5332313 into main Aug 26, 2026
8 checks passed
@shigarov
shigarov deleted the docs/extractor-table-wording branch August 26, 2026 07:42
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant