Skip to content

Commit b23b08f

Browse files
derek73claude
andcommitted
docs: explain which words attach to their neighbors
"Input shapes" says where the fields sit; nothing said which words merge into one field rather than standing alone. Between them those are most of what decides a parse, so the new section sits next to it. Organized by which field the word pulls into rather than by what kind of word it is. The fields are a closed list the reader has just learned — seven of them — whereas the word kinds (particles, bound given names, conjunctions, maiden markers, title chains, suffix runs) are an open-ended taxonomy with no natural stopping point, which is what makes the set feel incomprehensible when listed that way. The one genuinely position-sensitive behavior gets its own paragraph instead of a mostly-empty column: a particle at the start of a name has no surname to attach to yet, so it either becomes the given name or turns the whole name into a surname, depending on whether it can double as a given name. Explaining that by cause turns two arbitrary-looking outcomes into one rule with two branches. Table examples are prose, not doctests, so CI cannot catch a wrong one — each was verified by hand against the parser. The conjunction and leading-particle claims are pinned as doctests. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
1 parent a6bd04c commit b23b08f

1 file changed

Lines changed: 61 additions & 0 deletions

File tree

docs/usage.rst

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -54,6 +54,67 @@ given-then-family:
5454
For family-first input *without* a comma — common outside Europe — set
5555
``name_order``; see :doc:`customize`.
5656

57+
Words that attach to their neighbors
58+
--------------------------------------
59+
60+
Input shapes tell you where the fields sit. This tells you which words
61+
merge into one field instead of standing alone — between them, that is
62+
most of what decides a parse.
63+
64+
Most words stand alone. A few pull a neighbor in, and the thing worth
65+
knowing is which field they pull into:
66+
67+
.. list-table::
68+
:header-rows: 1
69+
:widths: 14 42 44
70+
71+
* - Pulls into
72+
- Example
73+
- Words
74+
* - ``family``
75+
- ``Juan de la Vega`` → ``de la Vega``
76+
- Particles (``de``, ``van``, ``von``, ``bin``), and conjunctions
77+
inside a surname (``y``)
78+
* - ``given``
79+
- ``abdul salam ahmed`` → ``abdul salam``
80+
- Bound given names (``abdul``, ``abu``, ``umm``, ``عبد``)
81+
* - ``title``
82+
- ``Asst. Vice Chancellor John Smith`` → ``Asst. Vice Chancellor``
83+
- Consecutive titles chain
84+
* - ``suffix``
85+
- ``John Smith PhD MD`` → ``PhD, MD``
86+
- Consecutive suffixes
87+
* - ``maiden``
88+
- ``Jane Smith née Jones`` → ``Jones``
89+
- Maiden markers (``née``, ``geb.``)
90+
91+
A conjunction joins whatever sits on both sides of it, so it can pull
92+
two given names together as easily as two surnames:
93+
94+
.. doctest::
95+
96+
>>> parse("John and Jane Smith").given
97+
'John and Jane'
98+
>>> parse("Juan de la Vega y Rodriguez").family
99+
'de la Vega y Rodriguez'
100+
101+
Position matters in exactly one place: the start of a name. A particle
102+
there has no surname to attach to yet, so it either becomes the given
103+
name or turns the whole name into a surname, depending on whether it is
104+
one that can double as a given name:
105+
106+
.. doctest::
107+
108+
>>> parse("van Gogh").given # 'van' can be a given name
109+
'van'
110+
>>> parse("de Mesnil").given # 'de' cannot
111+
''
112+
>>> parse("de Mesnil").family
113+
'de Mesnil'
114+
115+
:doc:`customize` covers how to change which words are in each of these
116+
sets, including which particles may double as given names.
117+
57118
Aggregate views
58119
----------------
59120

0 commit comments

Comments
 (0)