Repository navigation
Case repair: letter masks for the exceptions map (phd → PhD, bsc → BSc), md leaves the map, and roman numerals past iv (john smith xi → Xi) #459
Description
Activity
- changed the title
[-]`HumanName('JOHN SMITH MBA').capitalize()` gives `John Smith Mba` — a credential acronym is title-cased as an ordinary word[/-][+]Case repair: letter masks for the exceptions map (phd → PhD, bsc → BSc), md leaves the map, and roman numerals past iv (john smith xi → Xi)[/+]on Sep 11, 2026 Rescoped after #521. PR #521 (IMGillusion) takes the headline half of this issue as a narrow fix: a word the parse put in the suffix role from
suffix_acronymsis repaired to all capitals, with the exceptions map consulted first, soJOHN SMITH MBA→John Smith MBAandjohn smith jd→John Smith JDwhilemdandphdkeepM.D.andPh.D.for now. It also dropsphfrom the acronym set (measured: 0 corpus names move on any field). Once it merges, what remains of the Statement above is this issue's scope:CAPITALIZATION_EXCEPTIONSvalues become letter masks applied over whatever the writer punctuated:phd → PhDandph.d. → Ph.D.from one entry, no period added or removed.bsc → BScandmsc → MScjoin the map (Dr. med. univ. Margit Popp, MScis a corpus name and readsMSCunderforce=Trueafter fix(#459): repair one-case suffix acronyms to all-caps in case repair #521); a caller shipsdphil → DPhilthemselves (thedocs/customize.rstexample usesdphilfor exactly that).mdleaves the map so it readsMDlike every other acronym;ii,iii,ivstay.- Roman numerals past
ivare the same defect keyed onsuffix_words, which fix(#459): repair one-case suffix acronyms to all-caps in case repair #521 does not reach:john smith xi→John Smith Xi(likewisevi,vii,ix). The boundary line in the Statement — generational abbreviations keep title case — is right forjr/srand wrong for a numeral, so the rule needs to say numeral vs. abbreviation, not acronym vs. suffix word. - The given-role half of
QC MP(Qc MPafter fix(#459): repair one-case suffix acronyms to all-caps in case repair #521): whether a bare acronym read as a given name should ever repair to caps is left open here; fix(#459): repair one-case suffix acronyms to all-caps in case repair #521's description argues no, anded/ma/baare the reason. - Accepted-cost bookkeeping fix(#459): repair one-case suffix acronyms to all-caps in case repair #521's decisions bullet records and this issue inherits: the ambiguous five (
ba,do,ed,jd,ma) reaching the suffix role by a non-acronym route (john smith ed→ED), and the within-run coverage inconsistency (John Doe CLU, CFP, Lutc).
Related, not this issue: #492 (a cased roman-numeral suffix counting as case evidence in R5's already-mixed test, so
juan garcia IIIdeclines no-force repair).- added a commit that references this issue
on Sep 13, 2026 - added 4 commits that reference this issue
on Sep 22, 2026 The narrow half shipped. PR #521 (IMGillusion, with a maintainer fix-up) merged 2026-09-22 as 4d0680e: a single-case word the parse put in the suffix role from
suffix_acronymsrepairs to all-caps, exceptions map first, before the Mac/Mc convention (JOHN SMITH MBA→John Smith MBA,john smith jd→JD,mcse→MCSE), andphleft the acronym set (its cost, a barephwith noD.behind it losing the suffix reading, is classified on all five ledgers). Record: theR4entry and theExcluded (SUFFIX_ACRONYMS -- ph)block ofdocs/design/decisions.md, and the 2.4.0 release log. The rescoped Statement above is unchanged and is what remains here: letter masks,mdleaving the map, the given-role half ofQC MP, and the numerals pastiv.- added a commit that references this issue
on Sep 25, 2026 The remainder shipped. PR #539 merged 2026-09-25 as
120033b5, closing this with #492 and #478. The exceptions map now holds letter masks: a value is its key's own letters and digits recased, laid over the word as the writer punctuated it, so onephd → PhDentry givesphd→PhD,ph.d.→Ph.D.andPH.D.→Ph.D., and repair never writes the value's punctuation into the word (john smith iii.keeps its period). The shipped map isphd,bsc,mscplus fifteen masks for listed acronyms whose usual spelling is mixed case (psyd → PsyD,dsc → DSc,pharmd → PharmD,mdiv → MDiv, …);md,ii,iiiandivleft it,mdnow written by the acronym clause and a suffix roman numeral by shape (john smith xi→XI). A word in a name role repairs as a name word (QC MP→Qc MP,iv smith→Iv Smith, Option A). A value that does not spell its key raisesValueError, at construction for aLexiconand at the first parse for a v1Constants, the one decided exception to the shim's never-raise rule.eddandmenggot no mask because both are names; the vocabulary half of that was #540. Record:rules.md#R4, the 2026-09-23/24R4bullets and twoExcludedblocks ofdocs/design/decisions.md, and the 2.4.0 release log.- added 5 commits that reference this issue
on Oct 8, 2026
The parser has already decided these are credential acronyms —
mba,jd,qcandmpare insuffix_acronyms, and each is assigned theSUFFIXrole. Case repair consults neither the role nor the vocabulary. It falls through tostr.capitalize()and title-cases an initialism as though it were a name word.mdandphdescape only because they are hand-listed inCAPITALIZATION_EXCEPTIONS, which holds exactly{ii, iii, iv, md, phd}and has been byte-identical since the 2011 svn import (45a1539). Its docstring says "Any pieces that are not capitalized by capitalizing the first letter." 577 of the 579 shipped alphabetic suffix acronyms have no entry (measured 2026-08-29).Rationale
An acronym is written in capitals because each letter stands for a word. Capitalizing only the first letter discards that, and the parser already knows which words are acronyms — it put them in the suffix role from the acronym vocabulary.
Case repair decides which letters are capital. It should not add or remove characters: what the writer punctuated stays punctuated, and what they left bare stays bare. Two of the five existing map entries break that —
md → M.D.andphd → Ph.D.insert periods the writer never typed. That is substitution, not capitalization, and it is also why the map never grew: you cannot hand-write 577 dotted forms.Statement
Where the parser has assigned the
SUFFIXrole to a word fromsuffix_acronyms, case repair capitalizes every letter of it and leaves every other character exactly as written.The boundary is the generational half of the suffix vocabulary:
jr,srandesquireare abbreviations, not initialisms, and title case is right for them.CAPITALIZATION_EXCEPTIONSvalues become letter masksSome acronyms are conventionally written in mixed case, and the existing config surface is the right home for them once its values are read as which letters are capital rather than as replacement strings:
Applied as a mask over whatever the writer punctuated, this gives
phd → PhDandph.d. → Ph.D.from one entry, with no period added or removed either way. A caller who shipsdphiladdsdphil → DPhilthemselves.This is not a one-off for
phd:bscandmscare shipped acronyms whose conventional casing is mixed, andDr. med. univ. Margit Popp, MScis already a differential corpus name.mdleaves the map — the all-caps default covers it, and there is no reason for it to behave differently fromjdorlcpc.ii,iiiandivstay: they are generational, not acronyms, and need the map becausestr.capitalize()would giveIi.Two vocabulary entries should go
esqleavessuffix_acronyms. It is the only word in bothsuffix_acronymsandsuffix_words, and it abbreviates "Esquire" rather than initializing anything — without this it would capitalize toESQ. An acronym reading (Environmental, Safety & Quality) is a special case a caller adds to their own lexicon.phleavessuffix_acronyms. It exists to prop up the space-separatedPh. D., and it is what would producePH. D.under the rule above. Removing it moves 0 of 1094 corpus names across all seven fields — the dotted-abbreviation handling carries that spelling, not this entry. With it gone the fragment capitalizes as an ordinary initial andPh. D.is left as written.Accepted consequences
Measured over the 1094-name differential corpus, 2026-08-29:
JOHN SMITH MA,MD - DO - DDS,MD, DO, DDS,QC MP. Every other affected name is mixed case, so the case-repair gate (rules.md#R5) already returns it untouched.force=True, 75 more change.Three of the changed names make an existing defect louder rather than causing one:
Aishwarya Rai → Aishwarya RAI,Donald mc → Donald MCandJohn Smith Mc V → John Smith MC Vare read as suffixes today when they should be name words (#342, #454). Rendering a wrong parse more visibly is arguably a benefit.Same principle as #458
#458says the render views should honor what the parser decided instead of re-deciding from the word. This is that principle in a second view: the parse classified the token as a credential acronym, and case repair renders it as though it had not. Keyed on the role and the acronym vocabulary, the fix needs no new wordlist.Not proposed here
md → M.D.is a separate concern from capitalization and would belong in a separate method if it is wanted at all;phdwould be its exception. This issue removes period insertion from case repair rather than extending it.Ph. D.toPh.D.. Nothing does this today, all 16 spaced spellings in the corpus are mixed case so the gate never reaches them, and the space is not valid grammar for the degree. Left as written.CAPITALIZATION_EXCEPTIONS— that is the wordlist approach, and it would leave every caller-added acronym broken.