Skip to content

Commit 6d9c027

Browse files
derek73claude
andcommitted
Apply the background-before-behavior structure to the other CJK docs
locales.rst: state the naming conventions before the two defaults and name the actual limitation (the script cannot license a Han split) instead of 'waits for the zh pack'. customize.rst: name the mechanism behind the opt-out trap (the split still runs; the positional default then assigns given-first) instead of 'read it twice'. usage.rst: drop the self-referential lead-in sentence. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
1 parent 3280c04 commit 6d9c027

3 files changed

Lines changed: 27 additions & 19 deletions

File tree

docs/customize.rst

Lines changed: 10 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -307,11 +307,12 @@ East Asian defaults, and turning them off
307307
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
308308

309309
Two defaults key on the *script* a name is written in rather than on
310-
anything you set: a name written wholly in Han or Hangul reads
310+
anything you set: a name written wholly in Han or Hangul is assigned
311311
family-first (``script_orders``), and an unspaced hangul name is split
312312
into surname and given name against the shipped Korean census list
313-
(``segment_scripts``). :ref:`east-asian-names` shows what they do —
314-
this is how to switch them off, which you can do separately:
313+
(``segment_scripts``). :ref:`east-asian-names` explains the naming
314+
conventions both rest on — this section is how to switch them off,
315+
which you can do separately:
315316

316317
.. doctest::
317318

@@ -324,10 +325,12 @@ this is how to switch them off, which you can do separately:
324325
>>> unsplit.parse("김민준").family # one token, not split
325326
'김민준'
326327

327-
The middle line is the one to read twice: emptying ``script_orders``
328-
restores the purely positional reading but leaves the token split, so
329-
the surname lands in ``given`` instead. Clear both fields to get
330-
nameparser 2.0's behavior back exactly.
328+
The two switches interact, and clearing only ``script_orders``
329+
produces a third behavior rather than the old one: the split still
330+
runs, so ``김민준`` still becomes two tokens, and the positional
331+
default then assigns them given-first — the surname lands in
332+
``given``. To restore nameparser 2.0's reading exactly, clear both
333+
fields.
331334

332335
To teach the splitter a surname it doesn't ship with, add it to the
333336
``surnames`` vocabulary like any other word:

docs/locales.rst

Lines changed: 16 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -56,16 +56,22 @@ isn't read as a family name. Listing it in ``given_name_titles`` alone
5656
raises ``ValueError`` rather than quietly doing nothing.
5757

5858
Two East Asian behaviors are on by default for the same reason, except
59-
that what selects them is the *script* rather than the word: a name
60-
written wholly in Han or Hangul reads family-first, and an unspaced
61-
Korean name is split into surname and given name. Chinese and Japanese
62-
both write family-first natively, so reading the order takes no guess
63-
about which language it is; hangul is written by nothing but Korean,
64-
whose surnames are a closed census set, so splitting is safe too. See
65-
:ref:`east-asian-names` in :doc:`usage` for what that looks like and
66-
how to turn either half off. Splitting an unspaced *Han* name is the
67-
one piece that does need to know the language — a Chinese surname list
68-
mangles Japanese kanji names — so that half waits for the ``zh`` pack.
59+
that what selects them is the *script* rather than the word. The
60+
background (covered fully under :ref:`east-asian-names` in
61+
:doc:`usage`): Chinese, Japanese, and Korean names put the family name
62+
first in native script and are usually written with no space between
63+
the parts. Both defaults follow from facts the script alone
64+
establishes. A name written wholly in Han or Hangul is assigned
65+
family-first, because every language written in those scripts orders
66+
names that way — no language guess is involved. An unspaced hangul
67+
name is additionally split into surname and given name, because hangul
68+
is written by nothing but Korean and Korean surnames are a closed
69+
census set that ships as default vocabulary. Splitting an unspaced
70+
*Han* name is the one behavior the script cannot license — the same
71+
characters could be a Chinese or a Japanese name, and a Chinese
72+
surname list splits Japanese names in the wrong place — so it is not a
73+
default: the ``zh`` pack below turns it on when you can declare the
74+
data Chinese.
6975

7076
A pack is for something different: a *structural* rule, like reordering
7177
a patronymic, that vocabulary alone can't express.

docs/usage.rst

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -140,8 +140,7 @@ merging two, and is covered next.
140140
East Asian names
141141
-----------------
142142

143-
How these names are built, first, because the parsing rules follow
144-
from it. A Chinese, Japanese, or Korean name written in its own script
143+
A Chinese, Japanese, or Korean name written in its own script
145144
puts the family name first: 毛泽东 is MAO Zedong, 山田太郎 is YAMADA
146145
Taro, 김민준 is KIM Minjun. The family name is short — one Han
147146
character or one hangul syllable, occasionally two — and comes from a

0 commit comments

Comments
 (0)