De-jargon-ify - #22
Merged
Merged
Conversation
Inventories every technical, sophisticated, or jargony word and phrase in the Python comments and docstrings and in the Markdown outside `.claude/`, with per-file occurrence counts, an external reference for each term, and a keep-or-change verdict. Each term is also counted in FieldWorks, libpalaso, and this project's design repo, because precedent in the C# LIFT tooling is the deciding factor: `residue`, `POS`, `sanity`, `spurious`, `surface`, `bail out`, `pump`, `plumbing`, `safety net`, and `MDF` all turn out to be the ecosystem's own vocabulary, while `slot`, `anchor`, `matrix`, and `twin` already mean something else there. The file is for review only and is removed again in the next commit. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
It is a working document, not a deliverable: the repo ships no prose about its own prose. The findings it records are applied to the comments, docstrings, and documentation in the commits that follow, which is where they belong. Keeping the file in its own pair of commits leaves it readable in review while ensuring a squashed merge adds nothing to the tree. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
FieldWorks stores content that does not map onto its model in a `<lift-residue>` blob held in a `LiftResidue` field, and libpalaso's LIFT builder describes the same mechanism as putting content "in the xml residue for round-tripping". This package already used the word; it now uses the ecosystem's qualified form on first mention in each file, and `_extras` cites `LiftResidue` so a FieldWorks developer can connect the two. The qualifier is load-bearing rather than decorative. Bare "residue" in FieldWorks means the `import-residue` field — a user-visible LIFT field recording what a standard format import could not place — and FieldWorks has code that moves content from one to the other precisely because they differ. That field appears in this repo's own AllFLExFields fixture, asserted in `test_reader`, where a comment now marks the distinction. Also drops two metaphors from the same sentences: the `Extras` container is no longer a "bucket", and streaming "has no byte-passthrough layer" becomes "reuses no source bytes". Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
`_scan` located each root child's "byte span", which collided with LIFT's own `<span>` element for inline markup. Both meanings were live in one file: `_writer` had `_span_el(span: Span)` a few hundred lines above `for span in source.children`, and `_reader` built `range_spans` in one function and `span = Span()` in another. `ChildSpan` is now `ChildRegion` and every local follows, so `span` means the LIFT element and nothing else. The bytes between those regions were called the "matrix", a coined sense with no external meaning — in FieldWorks the word is only ever a comparison table. They are now described as what they are: the bytes between and around the top-level regions, copied verbatim. `_slot_bytes` becomes `_fit_between_regions`, which says what it does rather than naming a slot in a matrix that no longer exists. Two neighboring metaphors go with them: chunks are no longer "topped up" but have a missing newline appended, and without it they "run into" rather than "glue" their neighbor. The "passthrough layer" and "passthrough assembly" become plain byte reuse; "passthrough" on its own is kept where it reads well, since bytes really do pass through untouched. No behavior change: identical bytes in, identical bytes out. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
A pass over wording that named a thing after a metaphor rather than after itself. None of these terms appear in FieldWorks or libpalaso in the sense used here, so a reader coming from the C# LIFT tooling had nothing to look up: - `O(one entry) memory` is not well-formed big-O — the notation takes an input-size variable, not a quantity. It becomes "one entry in memory at a time", which the streaming guide already said. - `the extensible bundle` / `the extensibility outlier` become extensible fields and the extensibility exception. "Extensible" itself stays: it is the LIFT grammar's own pattern name, used 269 times in libpalaso. - `scope pillar` becomes "every major capability", and `LiftTools-style` becomes "in the spirit of LiftTools" — a suffix compound assumed the reader knew the product. - `LiftSorter-informed` becomes "based on LiftSorter's rules", and the two "strengthenings" and one "narrowing" become stricter and looser. - `dangling-by-design` becomes "ones FLEx writes knowing they will not resolve". Bare "dangling" stays; it is standard. - `vouch for` and `judged` become confirm and checked: ranges and hrefs do not hold opinions. - `hoisted` becomes "moved" — in programming, hoisting is what a compiler does to declarations. - `sort . sort = sort` becomes "sorting twice changes nothing"; the word for that, idempotent, is used elsewhere in the same suite. - `fixpoint` becomes stability, `fork` becomes "split in two", `colocated` becomes "in the same folder", and a re-emit `anchor` becomes the recorded position it always was. `_read_prologue` becomes `_read_header`. It read up to the header, while `_scan` uses "prolog" for the XML spec's meaning — everything before the root element. Two near-identical words for two different things, one codebase. The C# `oracle` keeps its name, which is a real testing term, but now says once what it means. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Several abbreviations were never spelled out anywhere in the file that used them, and two of them are ambiguous outside this project: - `RNG` reads as "random number generator" to most programmers, and does not appear in FieldWorks at all. Prose now says RELAX NG on first use in each file; the abbreviation stays for the compound adjectives and for the `.rng` filenames themselves. - `PI` and `BOM` become processing instruction and byte-order mark where they first appear, then keep the short form. - `MDF` becomes Multi-Dictionary Formatter. It is normal SIL vocabulary — 19 uses in FieldWorks — but appears exactly once here, so the expansion costs nothing. - A FLEx export in the corpus notes is now a FieldWorks Language Explorer (FLEx) export, matching what the documentation pages already did. Three terms borrowed from elsewhere now say what they mean where a reader first meets them: a `possibility list` is FLEx's name for a controlled vocabulary, which LIFT calls a range; a `tombstone` is a deleted entry; `vendored` is a byte-identical copy committed into the package. `Sense.gloss` said its result was "form-shaped", which is this project's coinage, in a docstring that reaches the generated API reference. It now states the fact instead: each `<gloss>` has its own lang. `byte-exact` becomes `byte-identical`, the term the other two dozen uses already prefer. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The guides and the fidelity contract carried a handful of phrasings that either read as ornament or asked the reader to decode a metaphor: - "the cardinal rule" becomes "the first rule"; a contract page does not need the flourish. - "the scanner is deliberately distrustful" becomes "deliberately conservative: on any doubt it captures no source bytes at all" — the fact the sentence was gesturing at. - comments are "moved next to the run", not "hoisted": in programming, hoisting is what a compiler does to declarations. - "no capability-reduced twin model" becomes "no second, cut-down model to learn", and "Chorus-grade byte chunking" becomes "the same per-entry byte chunking Chorus uses" — the suffix implied a quality tier that was not meant. - an "entry/line-addressed `Problem` stream" now says each problem carries the file, entry, and line it concerns. - "a clean bill of health", "colocated", "carve-outs", and "left for the caller to judge" give way to what they each mean. Adds a note to the fidelity page: "canonical" there is this project's own documented shape, not W3C Canonical XML, which normalizes whitespace inside text nodes and would break the guarantee the page makes — and not libpalaso's `CanonicalXmlSettings` either. Three meanings share one word across this ecosystem, and the one that matters here is the narrowest. The `.lift-ranges` companions get a pointer to "sidecar file", the general term, so a reader who knows that word can find the concept. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This was referenced Aug 11, 2026
Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
imnasnainaec
force-pushed
the
docs/terminology-alignment
branch
from
August 11, 2026 21:07
88e4a5d to
f6c2b23
Compare
imnasnainaec
force-pushed
the
docs/terminology-alignment
branch
from
August 11, 2026 21:35
f6c2b23 to
f9ef165
Compare
imnasnainaec
marked this pull request as ready for review
August 11, 2026 21:35
jasonleenaylor
approved these changes
Aug 12, 2026
jasonleenaylor
left a comment
jasonleenaylor
left a comment
There was a problem hiding this comment.
@jasonleenaylor reviewed 33 files and all commit messages, and made 1 comment.
Reviewable status:complete! all files reviewed, all discussions resolved (waiting on imnasnainaec).
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
2 participants
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.
Audit file used for most of these changes is added for reference in the PR's first commit (2fb8f53) and immediately removed to stay out of the final squash-merge.
Devin review: https://app.devin.ai/review/sillsdev/python-sil-lift/pull/22
This change is