Skip to content

De-jargon-ify the change-detection work - #23

Merged
imnasnainaec merged 3 commits into
docs/terminology-alignmentfrom
docs/terminology-alignment-change-detection
Aug 11, 2026
Merged

De-jargon-ify the change-detection work#23
imnasnainaec merged 3 commits into
docs/terminology-alignmentfrom
docs/terminology-alignment-change-detection

Conversation

@imnasnainaec

@imnasnainaec imnasnainaec commented Aug 11, 2026

Copy link
Copy Markdown
Collaborator

Onto docs/terminology-alignment (#22), which branched before
502910d landed on main. Two commits:

  1. main merged in (not rebased). One conflict, in
    docs/en/guides/bulk-edit-glosses.md, where De-jargon-ify #22 reworded the
    validation bullet that 502910d inserted new bullets above; resolved by
    keeping both, verbatim. git diff main HEAD on that commit is exactly
    De-jargon-ify #22's own diff, nothing more.
  2. The same terminology decisions applied to the change-detection work
    the Changes / RangesChanges docstrings, the Lexicon query docstrings,
    node_diff / _nodes_aligned, the two new guide bullets, and the new test
    docstrings and comments. Prose only.

Terms #22 had already ruled on

In 502910d Here
"the passthrough layer declined to scan" "the byte scanner declined to read"
"the same work save() does to decide passthrough" "…to decide which source bytes it can reuse"
"the passthrough matrix pairs slot i with node i" "byte reuse pairs the ith source region with the ith node"
"fill the source's slots one-for-one" "match the source's regions one-for-one"
"an entry's digest spans its subtree" "…covers its whole subtree"
"ranges span several files" "ranges live in several files"
"root-level residue" (bare) "root-level LIFT residue"

span → region and the loss of "matrix"/"slot" follow c55c8c9; the LIFT-residue
qualifier 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 the changes() docstring
    and the guide. Spelled out as "file-modification time".
  • "membership held", "a permutation alongside one", "a set difference
    would swallow it"
    — set-theory borrowings, in the Changes /
    RangesChanges docstrings, node_diff, and a test docstring. Now "the same
    entries are still present", "a reordering alongside one", and "comparing the
    two lists as sets would miss it".
  • "the composite" for a Changes — a coined sense, in a test comment. Now
    "the whole-document report".
  • "the same hole … of the guard" — a test docstring; now "the same gap".
  • "the change guard stays honest about them"_nodes_aligned; now "stays
    in step with the writer", which is the actual claim.

Deliberately left alone: falsy / truthy (Python's own vocabulary),
digest, baseline, and aliased — the last glossed on first use in
node_diff ("appending a node the document already has aliases the object
rather than copying it") and in the _duplicate_entry test helper.

Verified

python scripts/check.py green (ruff, format, mypy --strict, 529 tests at
97.6% coverage); mkdocs build --strict green.


This change is Reviewable

imnasnainaec and others added 3 commits August 11, 2026 14:30
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
imnasnainaec marked this pull request as ready for review August 11, 2026 19:09
@imnasnainaec
imnasnainaec merged commit 2e51b77 into docs/terminology-alignment Aug 11, 2026
10 of 13 checks passed
@imnasnainaec
imnasnainaec deleted the docs/terminology-alignment-change-detection branch August 11, 2026 19:09
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