Should `docs/` document input shapes for the family-first name orders, and does a trailing particle belong in the notation?

[derek73]

The three documented input shapes are given-first only. Both family-first orders are shipped and neither is described.

Proposed:

4.  Title Family Given Middle Middle [Particle] [, Suffix]     FAMILY_FIRST
5.  Title Family Middle Middle Given [, Suffix]                FAMILY_FIRST_GIVEN_LAST

[Particle] appears in shape 4 alone, and that is the notation carrying the rule rather than pointing at it: shape 5's trailing slot is the given name by the caller's declaration, so there is nothing there to reinterpret. Particles stay invisible inside Family everywhere else because they are part of the bucket they join — a trailing particle earns a slot precisely because it is displaced from one.

The correspondence with the family-comma format

Shape 4 is shape 2 with the comma removed and the family moved inline. It is not a particle rule that happens to hold — measured after #467, it is a general correspondence between the two formats:

shape written both ways	agree
Family, Given	6/6
Family, Given Middle	12/12
Family, Given Particle	84/84
Family, Given Middle Particle	168/168
Family, Given + suffix comma	6/6
Family, Given Particle + suffix comma	84/84
Family, Dr. Given ≡ Dr. Family Given	6/6
Family, Dr. Given Particle ≡ Dr. Family Given Particle	84/84

450 of 450, including the title cases where the title moves position between the two writings. The trailing particle was the one place it failed before #467 (0 of 216 agreed there).

Ménil, Christophe du   default   family 'du Ménil'   given 'Christophe'
Ménil Christophe de    FF        family 'de Ménil'   given 'Christophe'

Three things follow, and they want three different homes.

As user-facing guidance — this is the useful form for a caller. If your records are family-first without commas, Policy(name_order=FAMILY_FIRST) reads them the way the comma format is read. Belongs wherever name_order is documented, not buried in the shape notation.

As a note in the shapes documentation — not a rule of its own, since it decides nothing a rule does not already, but the place a future change would have to notice it is breaking something.

As an executable invariant — generate the pairs and assert equality. This is the part that earns its keep: it consults no rule, so it catches a rule that is WRONG, which review cannot. It went 0/216 → 216/216 across #467, and it would have failed that change's rejected predecessor (#466) at 72 of 216 — the ambiguous-particle half — without anyone arguing about vocabulary. There is no test of this shape in the suite today.

Two limits it must carry, or it reads as a promise the parser cannot keep:

• It is about one shape written two ways, not about deleting commas. 181 of 247 corpus comma-names parse differently with the comma simply removed — but those are names whose SHAPE changes when the comma goes (Doe, Dr. John → Doe Dr. John puts a title mid-name, which shape 2 never has). Not counterexamples; different shapes.
• Shape 5 has no comma twin. Shape 2 places the given name before the middles, so it corresponds to shape 4 only. There is no comma format that puts the given name last — which is why a trailing particle is shape 4's alone. The asymmetry falls out of which shapes have twins rather than being a carve-out asserted to protect Vietnamese.

Open: the CJK case fits neither shape

East Asian honorifics glue to the END and land in suffix, not title (rules.md#W2):

김민준 씨   →   family '김'   given '민준'   suffix '씨'

So a family-first CJK name has no leading title and no particle slot. That may want a third shape rather than a footnote on shape 4.

Background: what CLDR says, and where it stops

UTS #35's title field is "a string that represents one or more honorifics or titles, such as 'Mr.', or 'Herr Doctor'", and it leads the pattern — {title} {given} {given2} {surname}, {credentials} — including under surname-first, whose worked example is Slavic (г-н Иван Петрович Васильев, honorific leading). Titles are optional; leading empty fields are dropped. No Vietnamese pattern examples are given, so the spec does not settle where a Vietnamese honorific sits.

Worth flagging for a later decision: CLDR has two orders, givenFirst and surnameFirst, with ko vi yue zh all under the latter. Our FF/FFGL split has no CLDR counterpart — the difference we encode as two orders is where the middle name sits, which CLDR expresses through the locale's pattern. Whether that should become a locale property rather than an order is a 3.0-shaped question and is NOT part of this issue.

(The CLDR summary above came through a fetch-and-summarise of the spec; pull the sections verbatim before citing them as normative in rules.md.)

[derek73]

Amended with the measured correspondence. It turned out much broader than the trailing-particle case it came from — 450 of 450 across middles, suffix commas and titles, including the cases where the title changes position between the two writings (Ménil, Dr. Christophe vs Dr. Ménil Christophe).

So it is not a particle rule that happens to hold; the comma format and FAMILY_FIRST are the same format written two ways, and the trailing particle was the one place that failed until #467.

Three homes proposed rather than one: user-facing guidance (the actionable form for a caller with comma-less family-first records), a note in the shapes documentation, and an executable invariant — the last being the part with real value, since it consults no rule and therefore catches a rule that is wrong. It would have failed #466 at 72 of 216 with no argument about vocabulary.