Give Boundaries subheadings, shorter paragraphs, and examples

[derek73]

Summary

The Boundaries subsection of usage.rst ran 1,444 words in 11 paragraphs with no subheadings, one of them 410 words on its own. The rationale in it is good, but it was hard to scan and impossible to link to.

Now 8 subheadings, longest prose paragraph 112 words, and 6 doctest blocks where the prose previously asserted behavior without showing it.

Structure

Boundaries
  When the script rules don't apply
  Honorifics come off first
  Commas and dots
  Credentials after a comma
  Spacing, and where the name divides
  Which honorifics peel when glued
  When a division was a judgment call
  When a segmenter misbehaves

The 410-word paragraph became three of those: honorifics coming off first, what commas and dots do and don't stop, and the credentials-run rule. The orphaned 35-word command-line paragraph folded into the last section.

Examples

Six doctest blocks, all verified. The two most valuable pin rules that are hard to believe without seeing:

>>> parse("김, 민준 지훈씨").suffix     # second run, still in reach
'씨'
>>> parse("김, 민준, 지훈씨").suffix    # a third run, left whole
'지훈씨'

>>> credential = parse("田中さん, V.")
>>> credential.family, credential.suffix
('田中', 'さん')

All of them run under the default configuration. The Korean and Chinese honorific cases go through vocabulary rather than a segmenter, so nothing here needs namedivider, which is installed only in the ja-extra CI job and not in the main matrix. The segmenter contrast (佐藤 氏 vs bare 佐藤 under the JA pack) stays prose for exactly that reason, matching how the existing JA examples are written as code-block rather than doctest.

Other

Em-dashes 22 → 0. Word count 1,444 → 1,504; the small growth is the subheadings and the example blocks, with prose slightly tightened where paragraphs were split.

Content is Derek's, restructured rather than rewritten.

Verification

• sphinx-build -b doctest — exit 0, all 6 new blocks pass
• sphinx-build -b html — exit 0, 0 warnings (the internal When the parser had to guess_ reference still resolves)
• python -m doctest README.rst — exit 0
• uv run pytest -q — 3064 passed

No code changed.

🤖 Generated with Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 98.48%. Comparing base (c2bc8a0) to head (03b1bd8).

Additional details and impacted files

@@           Coverage Diff           @@
##           master     #338   +/-   ##
=======================================
  Coverage   98.48%   98.48%           
=======================================
  Files          41       41           
  Lines        2845     2845           
=======================================
  Hits         2802     2802           
  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.