docs: review locales.rst and migrate.rst against the tree; state the kana license correctly

[derek73]

Two parallel reviewers checked locales.rst and migrate.rst against the current tree. Each claim was measured, then fixed. There are five commits: one cross-page fix, then drift and structure for each page.

Cross-page: the kana license (638d2315)
Five pages paraphrased the script_orders kana rule as "kanji mixed with kana", including concepts.rst's wording from #592. The predicate admits any name within kanji and kana that holds some kana and isn't katakana alone. Wholly-hiragana やまだ はなこ and unspaced さくらエミ read family-first; ヤマダ タロウ stays positional. Fixed in concepts, customize (three places), locales, modules and usage.

locales.rst drift (4fb7e253), each measured:

• given_name_titles alone doesn't raise; the entry is inert.
• The "a fragment is validated alone" example used given_name_titles, which works fine in a fragment. The rule really applies to particles_ambiguous, suffix_acronyms_ambiguous and honorific_tails.
• Merge rules: two packs setting the same scalar warn even when the values agree, a pack overrides the base silently, and segment_scripts unions like the other set fields.
• ru and tr_az rows: the ru shape was described backwards (it is family/given/patronymic). The tr_az row now says four words ending in the marker.
• Segmenters aren't offered every token. A wrong-type answer or a cut outside the token raises too.
• ja without a segmenter now warns.
• The stand-down example was a name the ru rule doesn't match at all.
• Counts and links: "seven scripts" was a standing count that also left out the CJK vocabulary. The page cited Wrong parsing of vietnamese names #146, which is closed; it now cites Ship hi and bn locale packs for Latin-transliterated Indic honorifics #345.

locales.rst structure (b1ce51f5): subheadings throughout. The merge rules move to "Stacking packs" as a list. The stand-down note leaves the warning box. The Kapitan example now comes before the validation rule. Doctest variables get distinct names, and :doc: links become section :ref:s.

migrate.rst drift (f6c22760):

• capitalization_exceptions advice: the guide's dataclasses.replace(..., capitalization_exceptions={...}) replaced every shipped mask, so phd repaired to PHD, and it failed mypy. It now links customize.rst's extend-the-defaults recipe.
• 1.x docs link: it pointed at readthedocs stable, which now serves 2.3.0. It now targets /en/v1.4.0/.
• Breaks after 2.0: "runs clean on 1.4 → runs on 2.0, four exceptions" is scoped to 2.0.0, and a new list covers later 2.x breaks 1.4 never warned about: TITLES.add raises, retired config names warn, non-mask exceptions raise, and unmatchable entries are dropped with a warning.
• Behavior changes now point at every 2.x release-log section, with a new list of the shapes 2.2–2.4 moved on HumanName. Each 1.4.0 reading was measured with PYTHONSAFEPATH=1 from outside the worktree (asserting __file__), and each current reading is pinned by a doctest.
• Small additions: the Lexicon fields with no v1 attribute are named, and the dean recipes are now doctests.

migrate.rst structure (71079efa): subheadings in "Before you upgrade", "Config map" and "Behavior changes". The particles flip warning moves up next to the table row that points to it; it used to sit about 200 lines below. Over-long cells are shortened, and section :ref:s are added.

Review rounds. Two reviewers checked the first five commits, and a third checked the fix commit. Every finding was verified against the parser, or against 1.4.0, 2.1.0, 2.2.0 and 2.3.0 installs, before fixing (fab01a13, f247082b):

• migrate.rst: every 1.4.0 reading held, but my one-line explanations of why each changed didn't:
  • The Queen/Prince change was really two 2.3 mechanisms: a run of titles matched by its last title, and newly added titles that address by given name. Dr Harry is unchanged.
  • md simply left the exceptions map.
  • In an all-lowercase or all-caps name, only e reads as an initial; y still joins.
  • i links two surnames only in a mixed-case name.
  • The capitals and dotted-credential bullets now state their conditions, with unchanged counterexamples.
  • No listed shape changed in 2.2, so the subsection is "Changed in 2.3 and 2.4" and each bullet names its release.
  • The unmatchable-entry warning also covers entries made only of full stops, and capitalization_exceptions keys.
• locales.rst:
  • Stand-down: under FAMILY_FIRST_GIVEN_LAST the declared order wins and the last word reads as the given name (for tr_az that's the separate oglu marker).
  • Segmenter: it's still asked when a word in another script sits beside the token (Dr. 高橋一郎).
  • Fragment validation: only particles_ambiguous, suffix_acronyms_ambiguous and honorific_tails are checked against the set they mark.
  • Script coverage: katakana ships no honorific.
  • Pack warnings: the scalar-conflict warning fires only between packs with different codes.

Out of scope, filed as #594: halfwidth katakana (ﾀﾛｳ) is unclassified, so 山田 ﾀﾛｳ stays positional where 山田 エミ reads family-first.

No behavior change. sphinx-build -b doctest docs (0 failures) and -b html both print nothing. A diff of inline literals per page shows nothing dropped except deliberate link retargets.

🤖 Generated with Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 98.98%. Comparing base (7a9788a) to head (f247082).

Additional details and impacted files

@@           Coverage Diff           @@
##           master     #593   +/-   ##
=======================================
  Coverage   98.98%   98.98%           
=======================================
  Files          45       45           
  Lines        4220     4220           
=======================================
  Hits         4177     4177           
  Misses         43       43           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.