Skip to content

docs: describe the parser as vocabulary + positional layers in README#275

Closed
derek73 wants to merge 1 commit into
masterfrom
docs/readme-how-it-works
Closed

docs: describe the parser as vocabulary + positional layers in README#275
derek73 wants to merge 1 commit into
masterfrom
docs/readme-how-it-works

Conversation

@derek73

@derek73 derek73 commented Jul 7, 2026

Copy link
Copy Markdown
Owner

Reorganizes the README's how-it-works prose around the two-layer model of the parser:

  • New "How It Works" section replacing the three loose paragraphs after the name-structure list: a vocabulary layer that recognizes pieces by what they are (the customizable sets — titles, suffixes, prefixes, conjunctions, nickname delimiters), and a positional layer that assigns everything unclaimed by where it sits.
  • States explicitly that parsing is deterministic — no statistical models or machine learning; the same input always parses the same way.
  • Names the load-bearing assumption directly: the positional layer assumes Western name order, replacing the vaguer "not likely to be useful for languages that do not conform".
  • The "positional, not semantic" paragraph after the quick-start example is now a one-line callback to the positional layer (the "1 & 2, 3 4 5, Mr." example is unchanged).
  • The Customization section now says why customization is mostly set-editing: it feeds the vocabulary layer.

All claims from the previous prose are preserved (conjunction chaining, prefix joining, capitalization correction, the pre/post-nominal aside, "not perfect, but it gets you pretty far").

Verified: docutils renders the README with no warnings (PyPI-safe) and the README doctests pass.

🤖 Generated with Claude Code

Reorganize the README's how-it-works prose around the two-layer model:
a vocabulary layer that recognizes pieces by what they are (the
customizable sets), and a positional layer that assigns the rest by
where it sits. States explicitly that parsing is deterministic (no
statistical models) and that the positional layer assumes Western name
order. All claims from the previous prose are preserved.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@codecov-commenter

codecov-commenter commented Jul 7, 2026

Copy link
Copy Markdown

⚠️ Please install the 'codecov app svg image' to ensure uploads and comments are reliably processed by Codecov.

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 97.68%. Comparing base (c9e9f1b) to head (90b3c32).
⚠️ Report is 1 commits behind head on master.
❗ Your organization needs to install the Codecov GitHub app to enable full functionality.

Additional details and impacted files
@@           Coverage Diff           @@
##           master     #275   +/-   ##
=======================================
  Coverage   97.68%   97.68%           
=======================================
  Files          13       13           
  Lines         906      906           
=======================================
  Hits          885      885           
  Misses         21       21           

☔ 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.

@derek73

derek73 commented Jul 7, 2026

Copy link
Copy Markdown
Owner Author

Closing — docs-only changes go directly on master rather than through PRs.

@derek73 derek73 closed this Jul 7, 2026
@derek73 derek73 deleted the docs/readme-how-it-works branch July 7, 2026 22:53
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants