Skip to content

Commit 2cbca15

Browse files
derek73claude
andcommitted
docs: give "Declaring the order settles where a surname ends" subheadings
The section announced "Three limits" and then ran all three through one 20-line paragraph, and "Two cautions" the same way. It now splits into four subsections: the comma/order correspondence, where it stops (the three limits as a bulleted list), where a leading particle run stops, and where the vocabulary answers first (the two cautions as a list). Two fixes ride along. "Those three words" pointed at nothing -- the words were never named; they are do, mc and vd, measured as the particle-and-suffix overlap and dated rather than stated as a standing count. And "The run stops after one name word ... de la Vega y Santos Juan keeps family de la Vega y Santos" followed a sentence about the default order, where that name reads as one family; it now says it is the family-first reading. Every prose claim was re-run, and no inline literal from the old section is missing from the new one. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
1 parent 7a56756 commit 2cbca15

1 file changed

Lines changed: 59 additions & 48 deletions

File tree

‎docs/customize.rst‎

Lines changed: 59 additions & 48 deletions
Original file line numberDiff line numberDiff line change
@@ -634,6 +634,9 @@ order:
634634
>>> family_first.parse("Jong Anke de").family # the order says so
635635
'de Jong'
636636

637+
The comma and the order are one shape
638+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
639+
637640
That pair is not a coincidence but one shape written two ways: form 4
638641
(``Title Family Given Middle Middle [Particle] [, Suffix]``) is form 2
639642
(``Family [Suffix], Title Given (Nickname) Middle Middle[,] Suffix [,
@@ -647,34 +650,40 @@ families and three given names, 630 generated pairs in all — 603 of
647650
630 agree (2026-08-30); the executable form of this correspondence is
648651
``tests/v2/test_order_correspondence.py``.
649652

650-
Three limits keep that statement honest.
651-
652-
The correspondence covers one shape written two ways, not
653-
comma-deletion in general: a name whose shape changes when the comma
654-
is removed — a title or suffix crossing to a different position —
655-
parses as the shape it becomes, not as a disagreeing reading of form
656-
2. Where the trailing word is both particle and suffix vocabulary,
657-
the two writings read it differently, and it is that ASYMMETRY rather
658-
than a precedence that breaks the correspondence. The particle
659-
attachment outranks the suffix reading on the comma side alone —
660-
that is the scope the rule is stated in — so
661-
``parse("Ménil, Christophe vd")`` reads family ``vd Ménil``, while
662-
``family_first.parse("Ménil Christophe vd")`` reads family ``Ménil``
663-
and suffix ``vd``. A listing ending in one of those three words
664-
therefore does not correspond between the two writings — this is the
665-
whole of the 27 disagreeing pairs, not scatter. And ``FAMILY_FIRST`` is the only order the correspondence
666-
reaches at all, because it is the only one that puts a trailing piece
667-
in the *middle*, where a particle means nothing; ``FAMILY_FIRST_GIVEN_LAST``
668-
puts it in the given slot, where your own declaration already says
669-
it is the given name, and no comma format writes the given name
670-
last, so form 5 has no comma twin to correspond to in the first
671-
place:
653+
Where the correspondence stops
654+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
655+
656+
Three limits keep that statement honest:
657+
658+
- **It covers one shape, not comma deletion in general.** A name whose
659+
shape changes when the comma is removed — a title or suffix crossing
660+
to a different position — parses as the shape it becomes, not as a
661+
disagreeing reading of form 2.
662+
- **A word that is both particle and suffix reads differently in the two
663+
writings.** The shipped words in both vocabularies are ``do``,
664+
``mc`` and ``vd`` (2026-10-02). The
665+
particle attachment outranks the suffix reading on the comma side
666+
alone — that is the scope the rule is stated in — so
667+
``parse("Ménil, Christophe vd")`` reads family ``vd Ménil``, while
668+
``family_first.parse("Ménil Christophe vd")`` reads family ``Ménil``
669+
and suffix ``vd``. It is that asymmetry, not a precedence, that
670+
breaks the correspondence, and a listing ending in one of those words
671+
is the whole of the 27 disagreeing pairs measured above, not scatter.
672+
- **Only** ``FAMILY_FIRST`` **is reached.** It is the only order that
673+
puts a trailing piece in the *middle*, where a particle means nothing.
674+
``FAMILY_FIRST_GIVEN_LAST`` puts it in the given slot, where your own
675+
declaration already says it is the given name, and no comma format
676+
writes the given name last, so form 5 has no comma twin to correspond
677+
to in the first place:
672678

673679
.. doctest::
674680

675681
>>> given_last.parse("Nguyen Thi Van").given
676682
'Van'
677683

684+
Where a leading particle run stops
685+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
686+
678687
The declaration also bounds how far a *leading* particle run reaches.
679688
With no order declared, nothing marks where the surname ends and a
680689
particle followed by several words really can be all surname, so the
@@ -690,12 +699,12 @@ follows the family is not more surname, which settles it:
690699
>>> family_first.parse("de Mesnil Jean").given
691700
'Jean'
692701

693-
In the default order, write the comma for that reading. The run stops
694-
after one name *word* rather than one token, so it cannot cut inside a
695-
conjunction-joined run or a bound given-name pair —
696-
``"de la Vega y Santos Juan"`` keeps family ``de la Vega y Santos``.
697-
Where two or more words are left over, the two family-first orders
698-
differ from each other:
702+
In the default order, write the comma for that reading. Under a
703+
family-first order the run stops after one name *word* rather than one
704+
token, so it cannot cut inside a conjunction-joined run or a bound
705+
given-name pair — ``"de la Vega y Santos Juan"`` keeps family
706+
``de la Vega y Santos``. Where two or more words are left over, the two
707+
family-first orders differ from each other:
699708

700709
.. doctest::
701710

@@ -704,26 +713,28 @@ differ from each other:
704713
>>> given_last.parse("de la Cruz Juan Carlos").middle
705714
'Juan'
706715

707-
Two cautions, both places where the vocabulary layer answers before
708-
``name_order`` is consulted at all.
709-
710-
The first is why the example above is not the more obvious
711-
``"Nguyen Van Minh"``: a middle word that is also a shipped particle
712-
is claimed by the vocabulary layer. ``Van`` is the Dutch particle
713-
``van``, so that name reads family ``Nguyen`` with ``Van Minh`` given
714-
under *both* family-first orders, and the choice between them makes no
715-
difference.
716-
717-
The second is at the *front* of a name, and there the vocabulary
718-
overrides the declared order outright: where a particle that can never
719-
be a given name stands alone as the opening piece, the whole name is
720-
the surname, in every ``name_order``. ``"de Mesnil"`` is family ``de
721-
Mesnil`` under both family-first orders exactly as it is by default,
722-
not family ``de`` with ``Mesnil`` given — a word that can never be a
723-
given name leaves the order nothing to decide. Only the never-given
724-
set does this: ``"van Gogh"`` reads family ``van``, given ``Gogh``
725-
under a family-first order, because ``van`` *can* be a given name and
726-
so leaves a real question to answer.
716+
Where the vocabulary answers first
717+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
718+
719+
In two places the vocabulary layer answers before ``name_order`` is
720+
consulted at all:
721+
722+
- **A middle word that is also a shipped particle** is claimed by the
723+
vocabulary. That is why the Vietnamese example above is not the more
724+
obvious ``"Nguyen Van Minh"``: ``Van`` is the Dutch particle ``van``,
725+
so that name reads family ``Nguyen`` with ``Van Minh`` given under
726+
*both* family-first orders, and the choice between them makes no
727+
difference.
728+
- **A never-given particle opening the name** overrides the declared
729+
order outright: where a particle that can never be a given name
730+
stands alone as the opening piece, the whole name is the surname, in
731+
every ``name_order``. ``"de Mesnil"`` is family ``de Mesnil`` under
732+
both family-first orders exactly as it is by default, not family
733+
``de`` with ``Mesnil`` given — a word that can never be a given name
734+
leaves the order nothing to decide. Only the never-given set does
735+
this: ``"van Gogh"`` reads family ``van``, given ``Gogh`` under a
736+
family-first order, because ``van`` *can* be a given name and so
737+
leaves a real question to answer.
727738

728739
`Words that are also ordinary names`_ covers dropping a word from a
729740
vocabulary, or moving one between those two sets.

0 commit comments

Comments
 (0)