Skip to content

Split rules.md#S2 into the six rules it holds: 324 lines is too long to review as one #682

Open

Description

@derek73

rules.md#S2 ("generational suffixes and credentials are recognized by vocabulary…") has grown to 324 lines, with 82 examples and 5 Accepted clauses, cited 97 times across 22 files (measured 2026-10-14). It has become hard to review as one rule: #681 needed two design-docs review rounds to get a single clause right. The first round found the code's ASCII test credited to the wrong half of the statement. The second found that the statement's reason for refusing non-Latin words didn't cover the words being refused.

Read without its examples, the statement is six rules that each have their own evidence:

  1. Recognition and position. A trailing suffix word reads as a suffix, and a suffix never opens the string. Periods make an ambiguous acronym unambiguous; a single trailing period doesn't.
  2. The ambiguous class by count. A bare MA/Ma is consumed only with words to spare. This rule also names which slots report the fork.
  3. The given part's trailing slot after a family comma. The count says nothing there. This covers the never-given particle exception (SMITH, VD MA), how far the slot reaches past credentials and titles, and the particle that ends that reach (P6).
  4. Written case as evidence. Capitals mean credential, any other cased form means name, and only in a mixed-case name. This rule also says how case and C1's count share the first slot after a comma.
  5. Company. An unambiguous credential in front of a member decides it. This includes what does and doesn't pass the company along.
  6. The trailing run (Should a name word after a credential join the suffix? John Smith PhD Jones reads middle Smith PhD #602). A Latin suffix word after the name core makes the rest of its part a suffix. This covers what never starts the run, and the honorific refusal "Junior" in more languages: Alexandre Dumas fils reads family fils #679 is reconsidering.

Proposal: give each its own ID (S2 through S7, or S2a–S2f), and move each example and Accepted clause to the rule it witnesses. No behavior change.

Mechanics:

  • test_doc_citations.py checks every citation, so retargeting the 97 is mechanical. Each needs a reader's judgment about which new rule it meant, not a search-and-replace.
  • decisions.md#S2's history: link should point at all six.
  • The case-table notes and the release log quote "S2" too.

Open question: do the existing S3 (dotted chunks) and S4+ numbers move, or do the new rules take letters to keep every other citation stable?

Activity

  1. added
    docsDocumentation fixes and updates
    on Oct 14, 2026
  2. self-assigned this
    on Oct 14, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

docsDocumentation fixes and updates

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions