De-jargon-ify the change-detection work - #23
Merged
imnasnainaec merged 3 commits intoAug 11, 2026
Merged
Conversation
Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
# Conflicts: # docs/en/guides/bulk-edit-glosses.md
The change queries describe themselves in terms the rest of the prose has stopped using. `RangesChanges`, `Changes`, and `Lexicon.changed_entries` blamed "the passthrough layer" for declining a source, but the module that declines it is the byte scanner, and the writer calls what it does with those bytes reuse rather than a layer. `Lexicon.changes` said it costs what "deciding passthrough" costs, which now reads as deciding which source bytes can be reused. `_nodes_aligned` was the last place describing byte reuse as a "matrix" pairing "slot" *i* with node *i*; it now pairs the *i*th source region with the *i*th node, and no longer claims the guard "stays honest" when what it does is stay in step with the writer. Three borrowed vocabularies go too. From set theory: "membership held" becomes the same entries still being present, "a permutation alongside one" becomes a reordering, and a set difference that would "swallow" a repeated node becomes comparing the two lists as sets, which would miss it. From the byte scanner: an entry's digest covers its subtree rather than spanning it, and ranges live in several files rather than spanning them — `span` is LIFT's inline-markup element and nothing else. From the shell: `mtime` is spelled out as the file-modification time it stands for. Bare "residue" gains its "LIFT" qualifier where it names what `Extras` carries, keeping it clear of FieldWorks' unrelated `import-residue` field. A `Changes` called "the composite" is named for what it is, a whole-document report, and the duplicate-range test covers the same gap rather than the same hole. The bulk-edit guide's two bullets on the same subject follow the docstrings they describe. No behavior change: prose only. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
imnasnainaec
marked this pull request as ready for review
August 11, 2026 19:09
imnasnainaec
merged commit Aug 11, 2026
2e51b77
into
docs/terminology-alignment
10 of 13 checks passed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Onto
docs/terminology-alignment(#22), which branched before502910d landed on
main. Two commits:mainmerged in (not rebased). One conflict, indocs/en/guides/bulk-edit-glosses.md, where De-jargon-ify #22 reworded thevalidation bullet that 502910d inserted new bullets above; resolved by
keeping both, verbatim.
git diff main HEADon that commit is exactlyDe-jargon-ify #22's own diff, nothing more.
the
Changes/RangesChangesdocstrings, theLexiconquery docstrings,node_diff/_nodes_aligned, the two new guide bullets, and the new testdocstrings and comments. Prose only.
Terms #22 had already ruled on
save()does to decide passthrough"span→ region and the loss of "matrix"/"slot" follow c55c8c9; the LIFT-residuequalifier follows db67388. "passthrough" is left standing where #22 keeps it
(
CHANGELOG.md,_canonical.py,_scan.py, the reader/writer test names) —only the "layer" and "decide passthrough" uses are reworded, matching how #22
treated the same phrases.
New jargon in 502910d
Not covered by #22, since the words weren't in the repo when it was audited:
mtime— an unexpanded abbreviation, in both thechanges()docstringand the guide. Spelled out as "file-modification time".
would swallow it" — set-theory borrowings, in the
Changes/RangesChangesdocstrings,node_diff, and a test docstring. Now "the sameentries are still present", "a reordering alongside one", and "comparing the
two lists as sets would miss it".
Changes— a coined sense, in a test comment. Now"the whole-document report".
_nodes_aligned; now "staysin step with the writer", which is the actual claim.
Deliberately left alone:
falsy/truthy(Python's own vocabulary),digest,baseline, andaliased— the last glossed on first use innode_diff("appending a node the document already has aliases the objectrather than copying it") and in the
_duplicate_entrytest helper.Verified
python scripts/check.pygreen (ruff, format,mypy --strict, 529 tests at97.6% coverage);
mkdocs build --strictgreen.This change is