[derek73]

A fresh read of the user docs (usage, customize, concepts, locales, index, README.rst) and the autodoc docstrings against what 3.0 shipped. The pages had already dropped the compiled-constant names. What was left: one stale claim, the surname views missing from the locales page, and recipes that never said whether a language choice was the better lever. Every reading below was run on master (e793b1b).

The finding that decides the recipes

A choice of languages keeps every name reading, and switches off other languages' vocabulary readings of a word its own language lists as vocabulary. So:

• It leaves the fork where the chosen file holds both readings. parser_for(nl, strict=True) still reads Van Buren as given Van and reports it, and strict en still reports JOHN SMITH MA. The Lexicon recipes for van, ma, dean and neto stay the advice there.
• It ends the fork where it drops another language's reading. JOSE SILVA DO reports suffix-or-name by default; under locales.PT the English credential reading is off and DO is a family-name word, with nothing reported.

The docs now recommend a choice first where the data's language is known: for those clashes, and for the conventions a pack carries (two family names, Vietnamese order, a given-name reading held off by default: Lady under es, Hon under a zh choice, Guru under ne).

(The first commit stated this too broadly, as "no choice settles a word with a name reading", and said pt reads a trailing DO as a particle. The comment-analyzer review caught both; the fix commit corrects them.)

Changes

usage.rst

• The "Words that attach" table gains a row for titles that are also particles (Jan Freiherr von Berg → family Freiherr von Berg, while Freiherr Hans von Berg is a title), with a doctest. Its Titles row now notes that a title which is also a given name is a title only inside a title phrase.
• The "other way round" paragraph names the glued honorifics (words(kind="honorific", attached="after")) beside the Korean surnames.
• New subsection, "Inspecting the vocabulary": readings_of (what a word may be) beside Token.reading (what it was read as). It also notes that a lexicon answers only for readings it has on: Lady's given reading shows only on parser_for(locales.ES).lexicon.
• surname2 names the es, es_ar, cs and sk packs that fill it.
• Token.reading is described as having "the same parts" rather than "three".

customize.rst

• Removed the stale "there is no vn locale pack" and pointed to locales.VI (also for Nguyen Van Minh, which VI reads as middle Van, given Minh).
• The vocabulary section now opens with a language choice as the first lever, cross-linking plain and strict choices. strict=True was never mentioned on this page before.
• "Words that are also ordinary names" states the limit above.
• Cross-links for the DO/do clash and for the given-name readings a language turns on.

concepts.rst

• The Lexicon bullet describes readings instead of "word lists".
• New paragraph on what a Locale and a choice of languages are.

locales.rst

• The pre-existing "under any choice" sentence on name readings is scoped to a plain choice, with the strict case beside it.
• The Spanish section shows surname1, surname2 and surname1_base under es, with a doctest. The Czech/Slovak section and the packs table name the views.
• New vietnamese-names label.

Docstrings

• surname1: its two-family example now names its switch. By default Juan de la Vega del Valle has surname1 del Valle.
• initials(): states what spec, delimiter and separator do, instead of v1 history.
• Token.reading: mentions Reading.languages.
• ParsedName: lists its derived views.

docs/AGENTS.md gains the language-choice check above.

No release-log bullet: these are doc corrections plus one new subsection.

Checks

• sphinx-build -b doctest and -b html print nothing.
• python -m doctest README.rst passes.
• uv run pytest: 40,185 passed.
• ruff check is clean.

Reviews

• pr-review-toolkit:comment-analyzer (prose and docstrings): 9 findings, all confirmed by running them and fixed in 6eea91f. The choice claim and the DO paragraph were wrong; the rank/saint row, Hon under zh, the vi sentence, the Token.reading wording and a vacuous surname1_base example were overbroad.
• code-reviewer: 2 findings (the saint words in the rank row, Hon under the zh pack), both fixed in 6eea91f.
• second round (comment-analyzer) on 6eea91f: a strict choice drops name readings too, so a strict nl choice reads JOHN SMITH MA family MA, unreported. The fix's paragraph and a pre-existing locales.rst sentence ("under any choice") now say plain choice. The vi syllable lists read as complete and became examples; first_surname is set under middle_as_family too. Fixed in 9205054.
• third round (comment-analyzer) on 9205054: the strict clause was scoped to a word no chosen file holds, but strict pt also drops Do's English given reading (Do Smith → family Do Smith, unreported). It is now stated reading by reading, in 9828fd1. Every example in that commit was run before it was pushed: strict en MA reported, strict nl MA family, strict pt Do Smith family, plain pt Do given and reported.

The trap that cost two rounds is recorded in docs/AGENTS.md (Claims): test a claim about what a language choice settles on a word of each reading layout, under both a plain and a strict choice.

(design-docs-reviewer is not needed: nothing under docs/design/ changes.)

🤖 Generated with Claude Code