Skip to content

Document the vocabulary model: a reference for editing nameparser/vocab/ and a design overview of the later phases #748

Closed

Description

@derek73

Part of #747. Today the model is described only by decisions/vocabulary-model, which is a dated decision log, and one paragraph of AGENTS.md. Neither explains the model to a new reader.

Two documents, for two readers:

  1. nameparser/vocab/README.md, a reference for anyone editing the TOML, shown by GitHub beside the files:

    • what a file means, and what und and mul are for
    • how an entry is built, with worked entries (do, van, fils)
    • a table of kinds by category, with the compiled set each feeds
    • a table of properties: what each applies to, its default, behavioral or descriptive
    • exclusions and bearer-count provenance
    • adding a word: tools/name_usage.py, tools/vocab/build.py, tools/vocab/query.py, the test
    • which names are reserved for later phases

    The kind and property tables are checked by a test against the names build.py accepts, so the reference cannot drift from the compiler.

  2. docs/design/vocabulary-model-rfc.md, a design overview of where the model is going (alongside nameparser-2.0-rfc.md): derived ambiguity (phase 2), prefer and strict packs (phase 3), order versus shape and the output model (phase 4), and the first-pack order.

decisions/vocabulary-model stays the log that records each decision when it lands.

Done when both documents are merged and the README's tables are test-checked.

Metadata

Metadata

Assignees

Labels

designdocsDocumentation fixes and updatesvocabularyPer-word vocabulary model and language packs

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions