@@ -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+
637640That 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
647650630 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+
678687The declaration also bounds how far a *leading * particle run reaches.
679688With no order declared, nothing marks where the surname ends and a
680689particle 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
729740vocabulary, or moving one between those two sets.
0 commit comments