Merge pull request #315 from derek73/docs/period-abbreviation-scoping

docs: correct the scope of the period-abbreviation title rule

Author: derek73

AGENTS.md

@@ -172,7 +172,7 @@ Add a dedicated `copy.deepcopy()` round-trip test for it too (see `test_regexes_
 
 **Titles permanently shadow first names — be conservative** — any word in `TITLES` is always consumed as a title and can never be parsed as a first name. `"Dean"` is the canonical example: it's a common academic title *and* a common given name, so it is intentionally absent from the default titles (see `docs/customize.rst` — users who need it add it via opt-in `Constants`). Before adding a word to `TITLES`, ask: "Could this plausibly be someone's given name in any culture?" If yes, don't add it globally; it belongs in caller-supplied `Constants` instead. This same caution applies to international honorifics — `Prince`, `Sheikh`, `Frau` are all first names in some contexts. It also applies to any prefix sub-set gated on "never a first name": obscure-looking foreign particles are surprisingly often real given names — `Von` (Von Miller), `Vander` (Brazilian, also the Arcane character). When unsure, exclude — a missing member just means that name isn't auto-handled, whereas a wrong member misparses a real person.
 
-**`is_leading_title()` infers titles beyond the `TITLES` set, but only in leading position** — an unrecognized multi-letter word ending in a single trailing period (matched via the `period_abbreviation` regex, `{2,}` letters) is treated as a title when it appears before the first name is set, e.g. `"Major. Dona Smith"` → `title='Major.'`. It's distinct from `is_title()` and does not mutate `C.titles`, so the periodless form (`"Major"`) is unaffected elsewhere. The `{2,}` length requirement — not a separate initials check — is what excludes single-letter initials like `"J."` from being swallowed as titles; the same word after the first name is left as a middle name. (#109; see `docs/usage.rst` "Leading Period-Abbreviation Titles")
+**The period-abbreviation title inference runs at the head of the GIVEN-NAME part, not the head of the name** — an unrecognized multi-letter word ending in a single trailing period (`_assign._PERIOD_ABBREV`, a hand copy of the `period_abbreviation` regex, `{2,}` letters) is treated as a title in the leading title run, e.g. `"Insp. Jane Morse"` → `title='Insp.'`. "Leading" is per SEGMENT: `_peel_leading_titles` is called for NO_COMMA segment 0, SUFFIX_COMMA segment 0, and FAMILY_COMMA **segment 1**, so `"Morse, Det. Insp. Jane"` → `title='Det. Insp.'` and a lone `"Smith, Xyz."` → `title='Xyz.'` — long-standing, verified against 1.4.0, and the mechanism behind #296 (`"Smith, Jr."` → title, which the shape rule claims even once `jr` leaves `TITLES`). The docs said "leading word" until 2026-08-01 and were wrong for every comma path. It does not mutate `C.titles`, so the periodless form (`"Insp"`) is unaffected elsewhere. The `{2,}` length requirement — not a separate initials check — is what excludes single-letter initials like `"J."`; the same word after the given name is left as a middle name. **The inference OUTRANKS vocabulary where it runs**: `"Esq. Smith"` → `title='Esq.'` even though `esq` is suffix-only vocabulary, because the shape rule fires before anything consults the suffix sets. **And it runs in one direction only**: a trailing abbreviation has no structural counterpart and is matched against the suffix vocabulary alone, so a trailing TITLE word is not a title (`"John Smith Prof."` → `family='Prof.'`, and the comma path disagrees — `"Smith, Prof."` → `title='Prof.'`). Meanwhile `period_joined_vocab` resolves INTERIOR-period tokens (`Lt.Gov.`, `Msc.Ed.`) to title-or-suffix by vocabulary, and `_extract._suffix_shaped` treats any period-final delimited content as not-a-nickname. Four trailing-period behaviors, four different resolutions; unifying them is open design work, not settled. (#109; see `docs/usage.rst` "Titles you didn't configure")
 
 **Cyrillic suffix regexes need `re.I` even when the pattern is suffix-only** — a Latin title-cased word (`Ivanovich`) keeps its suffix lowercase, so `re.I` seemed skippable; but an irregular Cyrillic suffix can be nearly the whole word (`ильич`), so title-casing capitalizes into the suffix itself (`Ильич`). `east_slavic_patronymic_cyrillic` shipped without `re.I` on the Latin reasoning and silently failed on capitalized irregular forms — don't assume Latin's title-case safety transfers to Cyrillic. (#185)
 
@@ -216,7 +216,7 @@ Don't use the bare `python3 -m doctest <file>.rst` CLI (no `optionflags`) to che
 
 **Prefix-join uses value-based `list.index()`** in `join_on_conjunctions` — fragile when a token value repeats (e.g. a trailing title that's also a suffix acronym, or two `van`s); constrain such lookups to start at `i + 1`. See #100.
 
-**Title vs suffix is purely positional** — a word matching `TITLES` at the front of a name becomes `title`; the same word matching `SUFFIX_ACRONYMS`/`SUFFIX_NOT_ACRONYMS` at the end becomes `suffix` (never both, regardless of the word's real-world meaning). External test sources (old issue gists, etc.) sometimes assert `suffix` for a leading professional abbreviation like `RA`/`PD`/`Dipl.-Ing.` — that's the source data being wrong, not a parser bug. Verify position before "fixing" it.
+**Title vs suffix is positional for BARE words, and the leading period-abbreviation rule overrides even that** — a word matching `TITLES` at the front of a name becomes `title`; the same word matching `SUFFIX_ACRONYMS`/`SUFFIX_NOT_ACRONYMS` at the end becomes `suffix` (never both, regardless of the word's real-world meaning). External test sources (old issue gists, etc.) sometimes assert `suffix` for a leading professional abbreviation like `RA`/`PD`/`Dipl.-Ing.` — that's the source data being wrong, not a parser bug. Verify position before "fixing" it. Two qualifications the older "purely positional" wording papered over, both measured 2026-08-01: a PERIOD-marked leading word is claimed by the shape rule before any vocabulary is read (`"Esq. Smith"` → `title`, though `esq` is suffix-only), and trailing position has no such rule at all, so a title word there is neither title nor suffix but a NAME part (`"John Smith Prof."` → `family='Prof.'`) — which is what the comma path already disagrees with. Why it is not simply inverted to "vocabulary decides": `TITLES` holds 692 words that are in no suffix set, and many are ordinary surnames (`king`, `bishop`, `prince`, `pope`, `judge`, `sheriff`, `baron`, `master`, ...), so a vocabulary-first trailing rule would read `"Mary Jane King"` as `title='King'`, `family='Jane'`. The period is what separates the safe case from that one — `King` is a surname, `King.` is not.
 
 ### Tests (`tests/`)
 

docs/customize.rst

@@ -70,9 +70,10 @@ go together:
     'Hon'
 
 Emptying the vocabulary does not switch titles off entirely, though. A
-leading word that ends in a period is read as a title structurally,
-without consulting ``titles`` at all — that is what lets unfamiliar
-ranks and abbreviations work (see :ref:`abbreviated-titles`):
+word ending in a period, standing at the front of the part that carries
+the given name, is read as a title structurally, without consulting
+``titles`` at all — that is what lets unfamiliar ranks and
+abbreviations work (see :ref:`abbreviated-titles`):
 
 .. doctest::
 

docs/release_log.rst

@@ -31,6 +31,10 @@ Release Log
     - Fix NFD-decomposed input missing the East Asian defaults entirely: script classification now normalizes to NFC before deciding, so a Korean or Japanese name typed on macOS — where decomposed text is routine — gets the same order rule as its composed twin, which it silently did not before. Segmentation MATCHING deliberately stays raw, so an unspaced NFD hangul name is ordered correctly but not split, rather than being split in the wrong place. One gotcha worth stating plainly: parse output preserves the encoding it was given, so for NFD input ``name.family == "김"`` is ``False`` even though it is the same name — compare NFC-normalized text when comparing across encodings (#272)
     - Fix the Ukrainian conjunction ``й`` not joining the pieces around it: it is the euphonic alternate of ``і``, the two chosen by the surrounding vowel and consonant rather than by meaning (``"Олесь і Олена"`` but ``"Марія й Петро"``), so real Ukrainian data carries both spellings and shipping only ``і`` recognized just one of them. ``"Олесь й Олена Коваленки"`` now gives given ``"Олесь й Олена"`` where the ``й`` previously landed in ``middle``. Same treatment as the ``и``/``і`` entries added in 2.0.0, single-letter carve-out included: the conjunction joins only once the name has enough pieces, and a punctuated initial still wins, so ``"Й. Сліпий"`` is unaffected. Raised in a comment on #267
 
+    **Documentation**
+
+    - Correct the documented scope of the period-abbreviation title rule. It was described as applying to "a leading word", which was never true of any comma form: the rule runs at the front of the part that carries the given name, which after a family comma is the part *after* the comma — so ``"Morse, Det. Insp. Jane"`` gives title ``Det. Insp.``. Behavior is unchanged and matches 1.4.0; only the description was wrong. The examples now use real abbreviations absent from the shipped vocabulary (``Det. Insp.``) rather than whole words carrying a stray period, so they demonstrate the structural inference instead of merely surviving it
+
 * 2.0.0 - July 27, 2026
 
     Two release candidates preceded this release (rc1 on 2026-07-23,

docs/usage.rst

@@ -530,34 +530,55 @@ what that field marks and how to add to it.
 Titles you didn't configure
 -----------------------------
 
-A leading word that ends in a period is read as a title even when it is
-in no vocabulary list, which is what lets unfamiliar ranks, honorifics
-and abbreviations work without configuring anything:
+A trailing period marks an abbreviation, and the parts of a name that
+get abbreviated are the ones standing outside it — titles and
+post-nominals. So a word ending in a period, in no vocabulary list at
+all, is read as a title when it stands where a title stands: at the
+front of the part that carries the given name. That is what lets
+unfamiliar ranks, honorifics and abbreviations work without configuring
+anything:
 
 .. doctest::
 
-    >>> parse("Major. Dona Smith").title
-    'Major.'
-    >>> parse("Foo. Xyz. John Smith").title      # chains
-    'Foo. Xyz.'
+    >>> parse("Insp. Jane Morse").title
+    'Insp.'
+    >>> parse("Det. Insp. Jane Morse").title     # chains
+    'Det. Insp.'
+
+Neither ``det`` nor ``insp`` is in the shipped vocabulary; the periods
+are doing all the work.
+
+The part that carries the given name is not always the front of the
+string. After a family comma it is the part *after* the comma, and the
+rule applies there in exactly the same way:
+
+.. doctest::
+
+    >>> parse("Morse, Det. Insp. Jane").title
+    'Det. Insp.'
 
 The rule is bounded in three ways, so it doesn't swallow ordinary
 names. Single initials are left alone, so are abbreviations with
-interior periods, and the rule only applies to the leading run — the
-same word after the given name is a middle name:
+interior periods, and it applies only to that leading run — the same
+word after the given name is a middle name:
 
 .. doctest::
 
     >>> parse("J. Smith").given
     'J.'
     >>> parse("E.T. Jones").given
     'E.T.'
-    >>> parse("John Major. Smith").middle
-    'Major.'
+    >>> parse("Jane Insp. Morse").middle
+    'Insp.'
 
 Because this is structural rather than vocabulary-driven, emptying
 ``titles`` does not switch it off; see :doc:`customize`.
 
+Only the title direction is inferred this way. A *trailing*
+abbreviation is matched against the suffix vocabulary and nothing more,
+so an abbreviated post-nominal is recognized only if it is a word the
+parser already knows.
+
 Comparing names
 ----------------