Report the conventions: given-or-family (#449) and title-or-name (#491)

docs/concepts.rst

@@ -176,7 +176,14 @@ de Souza"`` it sits mid-name, where nothing has to choose between
 readings — so nothing is recorded. A comma can settle the question
 before it arises, too: ``"Ma, Jack"`` fixes the family name, so the
 credential reading never comes up, while ``"John Smith MA"`` has to
-call it and says so.
+call it and says so. Some decisions are conventions rather than
+readings — a name of one name word has nothing to compare, and an
+input the title peel eats down to one last title word reads that word
+as the name for want of anything else — and since 2.3 those are
+reported too, so a field the library merely had to pick is a field you
+can see it picked. A title standing entirely alone reports nothing:
+``"Dr."``, ``"Sir"`` and ``"Prince of Wales"`` are all title and no
+name, so there is no reading to have doubted.
 
 An empty ``ambiguities`` is therefore not a certificate of certainty.
 Reporting is deliberately partial: :class:`~nameparser.AmbiguityKind`

docs/design/rules.md

@@ -29,7 +29,7 @@ The marker's unit is the whole rule, because that is the unit `tools/differentia
 
 ## Titles & honorifics (H)
 
-Background: an honorific title precedes a name and is not itself part of it; it addresses or ranks the person. Most titles address by surname ("Mr. Johnson"), but a few — knighthoods, some clerical and courtesy titles — address by given name ("Sir John"). The library keeps a vocabulary of titles and, separately, of these given-name titles. What a TRAILING title-vocabulary word should do is unresolved (#316): today "John Smith Prof." keeps Prof. a name word while "Smith, Prof." reads it as a title — the two comma paths disagree, and TITLES holding ordinary surnames (king, judge, bishop) is what bars the blanket vocabulary-wins answer. Two criteria govern two different questions here. Membership in the given-name-title list follows HOW THE TITLE ADDRESSES: a title that precedes and addresses by the given name belongs (Sir, Sheikh, the Arabic honorifics الدكتور/الشيخ — which qualify even though those traditions fully retain family names). Whether an EMPTY FAMILY is correct output is the separate question, governed by surname retention: renunciation abolishes the surname, so for Swami, Guru, Baba or Lama family="" is right (#346), while rabbi and imam traditions keep surnames — "Rabbi Cohen" addresses by title and keeps family "Cohen". Conflating the two criteria either ejects the Arabic entries or sweeps in titles that break
+Background: an honorific title precedes a name and is not itself part of it; it addresses or ranks the person. Most titles address by surname ("Mr. Johnson"), but a few — knighthoods, some clerical and courtesy titles — address by given name ("Sir John"). The library keeps a vocabulary of titles and, separately, of these given-name titles. What a TRAILING title-vocabulary word should do is unresolved (#316): today "John Smith Prof." keeps Prof. a name word while "Smith, Prof." reads it as a title — the two comma paths disagree, and TITLES holding ordinary surnames (king, judge, bishop) is what bars the blanket vocabulary-wins answer. An input the title peel eats down to one last title-vocabulary word is H4's, and what it does with that word is a convention rather than a reading of the vocabulary. Two criteria govern two different questions here. Membership in the given-name-title list follows HOW THE TITLE ADDRESSES: a title that precedes and addresses by the given name belongs (Sir, Sheikh, the Arabic honorifics الدكتور/الشيخ — which qualify even though those traditions fully retain family names). Whether an EMPTY FAMILY is correct output is the separate question, governed by surname retention: renunciation abolishes the surname, so for Swami, Guru, Baba or Lama family="" is right (#346), while rabbi and imam traditions keep surnames — "Rabbi Cohen" addresses by title and keeps family "Cohen". Conflating the two criteria either ejects the Arabic entries or sweeps in titles that break
 "Rabbi Cohen".
 
 H1. Rationale: a title normally addresses by surname, so a title
@@ -103,6 +103,90 @@ H3. Rationale: compound titles are written as a run of title words,
       "Dr. Smith, John"           →  family="Dr. Smith"
     interacts: C1 · implemented: nameparser/_pipeline/_pieces.py
 
+H4. Rationale: this is a name parser, not a title parser. Handed a
+    string the title peel eats down to one last word which is itself
+    title vocabulary, it still has to name somebody, and that word is
+    the only candidate there is — a guess fixed in advance, so the
+    same input reads the same way every time, not a claim that the
+    word is a surname. The same reasoning covers a string that is
+    nothing but post-nominal vocabulary: something has to be the name.
+    An input whose only remaining name word after the title peel is
+    itself title vocabulary reads that word as the name by convention
+    and reports `title-or-name`; an input whose every word is
+    post-nominal vocabulary reads its first word as a name and
+    reports `suffix-or-name`. A single title word reads as a title
+    with no name beside it and reports nothing: the peel took the
+    whole string, so no word was left standing to be read as a name
+    and no reading was chosen.
+      "Lord Chancellor"           →  family="Chancellor"
+      "Lord Chancellor"           →  ambiguities=("title-or-name",)
+      "The Right Hon. the President of the Queen's Bench Division"  →  family="Division"
+      "The Right Hon. the President of the Queen's Bench Division"  →  ambiguities=("title-or-name",)
+      "Dr. King"                  →  ambiguities=("title-or-name",)
+      "Dr."                       →  title="Dr."  · boundary
+      "Dr."                       →  ambiguities=()
+      "Dr. Smith"                 →  ambiguities=()
+    Accepted: ONE site takes both halves — the assignment that places
+    the lone name word — so neither report depends on the declared
+    order. Under the default order H1 retags the title-vocabulary
+    word from given to family afterwards; under a declared
+    family-first order the assignment places it in the family
+    directly and H1 never runs. Same reading either way, so the same
+    kind is reported either way.
+    Accepted: the suffix half is reached only where no title was
+    peeled first, so a title in front of the run takes the input out
+    of this rule and leaves it H1's — "Dr. King MD" reports nothing,
+    the credential having been read as the name after a title peel
+    rather than for want of one.
+      "Rinpoche"                  →  ambiguities=("suffix-or-name",)
+      "QC MP"                     →  given="QC"
+      "Jr."                       →  title="Jr."
+      "Jr."                       →  ambiguities=()
+    Accepted: `Jr.` is post-nominal vocabulary and still reads as a
+    title, H2's opening-abbreviation shape outranking the vocabulary
+    where it fires — so the suffix half never sees a dotted lone
+    credential.
+    Accepted: the suffix half is scoped to names no script order
+    placed, so a lone CJK honorific written by itself — さん, 씨,
+    선생님 — reports nothing. The same shape, read through the
+    glued-honorific rules (W2) and the script's own order, and left
+    to the arc that revisits those readings. That silence is a SCOPE
+    on the script rule having placed the name, not a claim about the
+    honorific: a caller who declares no script orders at all gets the
+    report on the same input, since nothing then resolves the order
+    and the word reaches the carve-out as any other lone credential
+    does. The pair is pinned in the case table rather than here,
+    a policy that empties the script table having no example spelling
+    in this document.
+    Accepted: one name UNIT of more than one word carrying title
+    vocabulary reports `title-or-name` as well, the fork there being
+    whether the title word inside the unit is a title at all. Usually
+    a join (P3), and a particle chain (P4) is the same shape and
+    reports too — `St St née` reads family "St née" with `st` title
+    vocabulary inside it. The
+    clause reaches EVERY join whose non-leading member is TITLES
+    vocabulary, not the one word that prompted it: `Smith and King`,
+    `John and King`, `Smith and Bishop` and `John of Judge` all
+    report it, as `John of Prince` and `Smith and Prince` do. That
+    reach is the king/judge/bishop collision set met inside a join,
+    and the report is the honest answer there rather than a
+    misfire — a second surname that is also title vocabulary is
+    exactly the doubt the kind names, and those words stay in the
+    vocabulary for the addressing forms, which is
+    decisions.md#vocabulary-collisions' call.
+    A join OPENING the name with a title word is a title run (H3)
+    instead. Behind a peeled title the join is not: a title needs a
+    following piece and the join is the last one, so `Attorney General
+    of Minnesota` and `Deputy Secretary of State` keep `Attorney` and
+    `Deputy` as the title and report the rest — the two corpus names
+    the clause reaches, and `General` or `Secretary` being a title is
+    exactly the fork. Nothing in front of the join silences the
+    clause, a title, a maiden name or a claimed word each deciding
+    which FIELD the unit takes and none of them whether the word
+    inside it is a title. The other measured inputs are pinned in the
+    case table rather than here.
+    history: decisions.md#H4 · interacts: H1, H2, H3, S2, O5 · implemented: nameparser/_pipeline/_assign.py
+
 ## Particles & surname prefixes (P)
 
 Background: particles ("de", "la", "van", "von", "bin") link forward to a surname and are written as part of it. Some are never anyone's given name; others ("Van", "Bin") are ordinary given names in some cultures, so the vocabulary distinguishes never-given particles from ambiguous ones, and only the never-given ones license special treatment. A separate small vocabulary binds forward to a GIVEN name instead: words like "abdul" that are not complete given names alone (P5). Which particles fall on which side of the never-given line is its own open question (#360).
@@ -1068,10 +1152,25 @@ O5. Rationale: O4 reads a name by comparing where its words stand,
     suffix stands beside them too, which its count does not set
     aside; and a maiden name beside it does the same (M4), except
     where the vocabulary or the word's own shape has claimed the
-    word already. What the library should SAY about a reading it
-    merely fixed — whether the convention is worth reporting as an
-    ambiguity — is open, and #449 holds the measurement that makes
-    it a design question rather than an implementation one.
+    word already. The convention is reported: a name whose one name
+    word nothing else decided carries a `given-or-family` ambiguity
+    naming the field the convention chose. The report is exactly as
+    narrow as the convention, so every rule named above silences it
+    where it fires, a family comma — a comma with a name segment
+    after it — silences it, a script whose own convention settles
+    the order (W4) silences it, and so does the word's own claim — a
+    particle, a bound given name, an initial's shape. A comma with
+    nothing after it names no family and silences nothing, so
+    `سلمان،` and `Smith,` report where `Smith, Andrew` does not. A
+    comma with only a TITLE after it names no family either, but the
+    title still decides the field wherever it stands, so `John V, Dr.`
+    is silent for H1's reason and not the comma's. A word with no
+    letter or digit in it is no name word and
+    reports nothing (A2). Where the one name unit carries title
+    vocabulary in a word beside the one it places, or is itself title
+    vocabulary left standing by the title peel, the doubt reported is `title-or-name`
+    instead, which H4 states — so a title silences THIS kind, not
+    every report at the site.
       "Smith"                     →  given="Smith"
       "Garcia"  family-first      →  family="Garcia"
       "Sir John"                  →  given="John"
@@ -1080,7 +1179,16 @@ O5. Rationale: O4 reads a name by comparing where its words stand,
       "Mr. Johnson"               →  family="Johnson"  · boundary
       "'Smitty' Jones"            →  family="Jones"  · boundary
       "Smith née Jones"           →  family="Smith"  · boundary
-    interacts: O4, H1, N3, M4 · implemented: nameparser/_pipeline/_assign.py
+      "Andrew"                    →  ambiguities=("given-or-family",)
+      "Garcia"  family-first      →  ambiguities=("given-or-family",)
+      "Juan & Garcia"             →  ambiguities=("given-or-family",)
+      "'Smitty' Jones Jr."        →  ambiguities=("given-or-family",)
+      "Smith Jr."                 →  ambiguities=("given-or-family",)
+      "Dr. Smith"                 →  ambiguities=()  · boundary
+      "Sir John"                  →  ambiguities=()
+      "Smith née Jones"           →  ambiguities=()
+      "abd née Jones"             →  ambiguities=()
+    history: decisions.md#O5 · interacts: O4, H1, N3, M4, H4, W4, P3, A2 · implemented: nameparser/_pipeline/_assign.py
 
 ## Scripts & writing systems (W)
 

docs/release_log.rst

@@ -30,6 +30,10 @@ Release Log
 
     - **Add Bengali honorifics -- the first Bengali vocabulary in the default lexicon (#343):** ``ড``, ``ডঃ``, ``ডক্টর``, ``ডাঃ``, ``ডা``, ``ডাক্তার``, ``শ্রী``, ``শ্রীমতী``, ``জনাব``, ``অধ্যাপক``, ``প্রফেসর``, ``বিচারপতি``, ``মাওলানা``, ``মুফতি``, ``আলহাজ্ব``, ``আলহাজ``, ``মিঃ``, ``মি``, ``মিসেস``, ``মোঃ``, ``মো``, ``মোসাঃ``, ``মোসা``, ``মোছাঃ`` and ``মোছা`` as titles, and ``স্বামী``, ``শ্রীল``, ``গুরু``, ``বাবা`` as given-name titles. ``ড. মুহাম্মদ ইউনূস`` reads title ``ড.``, first ``মুহাম্মদ``, last ``ইউনূস`` -- the vocabulary beats the initial reading -- while real initials are untouched: ``র. কে. নারায়ণ`` is unchanged. ``মোঃ আবদুল করিম`` reads title ``মোঃ``, first ``আবদুল``, last ``করিম``, the mirror of Latin ``Md``; the visarga spelling and the ``মো.`` period spelling both match, and the women's ``মোসাঃ``/``মোসা.`` rides the same pair of entries. ``ঠাকুর`` stays out, being Tagore. Latin transliterations (``Sri``, ``Pandit``, ``Mst``) are not added -- they collide with real given names where the native scripts cannot -- and belong to the opt-in packs of #345 (closes #343)
 
+    - **Add AmbiguityKind.GIVEN_OR_FAMILY, reported when a name of one name word had nothing to decide which field it is:** ``parse("Andrew")`` still gives given ``Andrew`` and now says that field was a convention rather than a reading -- one word gives the positional rule nothing to compare, so the library picks the given name under the default order and the family name under a declared family-first one, and ``detail`` names the field it picked. A trailing suffix does not decide it either: ``parse("Smith Jr.")`` reports it too, the suffix being peeled and the convention placing the one name word left. A name something DID decide stays silent -- ``"Dr. Smith"``, ``"Smith née Jones"``, ``"'Smitty' Jones"`` and ``"Smith, Andrew"`` -- and so do ``"abdul"`` and ``"de"``, where the bound given-name and particle vocabularies claimed the word, and ``"J."``, claimed by the initial's own shape. A name whose script settles the order is silent too: ``"毛泽东"`` reads family by convention of the writing system, not of this rule. Twenty-seven names in the differential corpora gain the report, and no field moves anywhere. See the ``O5`` entry of ``docs/design/decisions.md`` (closes #449)
+
+    - **Add AmbiguityKind.TITLE_OR_NAME, reported when an input that is nothing but honorifics had its last word read as the name:** ``parse("Lord Chancellor")`` still gives title ``Lord``, family ``Chancellor``, and now says so -- this is a name parser, not a title parser, so handed a string with no name in it, it reads the last title word as one. ``"The Right Hon. the President of the Queen's Bench Division"`` and ``"His Holiness"`` move the same way, and so does ``"Dr. King"``, ``king`` being title vocabulary for the addressing forms. A title with an ordinary word behind it is silent (``"Dr. Smith"``, ``"King Charles"``), and so is a lone title word: ``parse("Dr.")`` is a title with no name beside it, the peel having taken the whole string, so no word was left standing to be read as a name and nothing was chosen. The same convention on the other vocabulary reports the existing suffix-or-name -- ``parse("Rinpoche")`` gives given ``Rinpoche`` and flags it, as does ``"QC MP"`` -- while ``"Jr."`` is unchanged and unflagged, reading as a title on its shape. The same doubt inside a joined unit reports too -- ``parse("Attorney General of Minnesota")`` reads title ``Attorney``, family ``General of Minnesota``, and whether ``General`` is a title is the fork. Ten names in the differential corpora gain a report, and no field moves. See the ``H4`` entry of ``docs/design/decisions.md`` (closes #491)
+
 * 2.2.0 - August 31, 2026
 
     nameparser 2.2 is a rename plus about thirty parsing fixes.