From 785e181fc6733cca1a9c8bfa11f3d8b4f43cbdc1 Mon Sep 17 00:00:00 2001 From: Patrick Linnane Date: Mon, 20 Jul 2026 13:29:18 -0700 Subject: [PATCH] docs: enforce sentence-case headings and codify prose conventions Signed-off-by: Patrick Linnane --- .vale.ini | 6 ++ docs/AGENTS.md | 4 +- docs/Prose-Style-Guidelines.md | 3 + docs/index.md | 2 +- docs/vale-styles/Homebrew/Headings.yml | 89 ++++++++++++++++++++++++++ 5 files changed, 102 insertions(+), 2 deletions(-) create mode 100644 docs/vale-styles/Homebrew/Headings.yml diff --git a/.vale.ini b/.vale.ini index 13f035651a..e78ba99762 100644 --- a/.vale.ini +++ b/.vale.ini @@ -5,3 +5,9 @@ rb = md [*.{md,rb}] BasedOnStyles = Homebrew + +[{docs/,}Manpage.md] +Homebrew.Headings = NO + +[{docs/,}governance/*.md] +Homebrew.Headings = NO diff --git a/docs/AGENTS.md b/docs/AGENTS.md index 8f60504245..22aa18be4b 100644 --- a/docs/AGENTS.md +++ b/docs/AGENTS.md @@ -21,6 +21,8 @@ These instructions apply when working in `docs/`. This keeps diffs small and readable. - Format tables so the raw Markdown is readable: pad each column with spaces so the cell borders line up vertically. - Use UK spelling and punctuation. +- Use `licence` for the noun and `license` for the verb. + Keep `license` when referring to the exact DSL stanza, command-line option or other interface name. - Avoid em-dashes (prefer semicolons, colons and commas) and Oxford commas. - Do not use bare URLs; use Markdown links. Internal links must point at the `.md` file (for example `[Bottles](Bottles.md)`), not a `docs.brew.sh` URL. @@ -40,7 +42,7 @@ At a minimum, from `docs/` run: Also run these from the repository root when docs content changes: -- `HOMEBREW_NO_AUTO_UPDATE=1 vale docs/` +- `rg --files docs -0 -g '*.md' -g '!vendor/**' -g '!_site/**' -g '!rubydoc/**' | xargs -0 vale` - `HOMEBREW_NO_AUTO_UPDATE=1 brew style docs` ## Notes diff --git a/docs/Prose-Style-Guidelines.md b/docs/Prose-Style-Guidelines.md index c5e2907884..7ff770146c 100644 --- a/docs/Prose-Style-Guidelines.md +++ b/docs/Prose-Style-Guidelines.md @@ -34,6 +34,7 @@ We prefer: ### Style and usage * British/Commonwealth English over American English, in general +* "licence" as a noun and "license" as a verb, while preserving literal interface names such as the `license` stanza * "e.g." and "i.e.": Go ahead and use "e.g." or "i.e." instead of spelling them out. Don't worry about putting a comma after them. * "e.g." means "for example"; "i.e." means "that is" * Offset nontrivial subordinate clauses with commas @@ -52,6 +53,7 @@ We prefer: * Capitalise all list items if you want, even if they're not complete sentences; just be consistent within each list, and preferably, throughout the whole page * Use a subordinate list item instead of dropping a multi-sentence paragraph-long item into a list of sentence fragments * Prefer Markdown over other markup formats unless their specific features are needed +* One sentence per source line in Markdown, without wrapping prose to a fixed width * GitHub Flavoured Markdown. GitHub's implementation is the standard, period. * Link to other documentation pages with relative links to the Markdown filename rather than the full URL * e.g. `FAQ.md` instead of `https://docs.brew.sh/FAQ` @@ -65,6 +67,7 @@ We prefer: * No "$" with environment variables mentioned outside code snippets * e.g. "Set `BLAH` to 5", not "Set `$BLAH` to 5" * One space after periods, not two +* Commas, colons or semicolons instead of em dashes * Capitalised proper nouns * We do not defer to extensive nonstandard capitalisation, typesetting, or other styling of brand names, aside from the normal capitalisation of proper nouns and simple internal capitalisation * No "TM", ™, SM, ©, ®, or other explicit indicators of rights ownership or trademarks; we take these as understood when the brand name is mentioned diff --git a/docs/index.md b/docs/index.md index a8aafd627d..168e57afa0 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,5 +1,5 @@ --- -last_review_date: "2026-06-08" +last_review_date: "2026-07-18" --- Start with [installation](Installation.md), diff --git a/docs/vale-styles/Homebrew/Headings.yml b/docs/vale-styles/Homebrew/Headings.yml new file mode 100644 index 0000000000..fc90ad6596 --- /dev/null +++ b/docs/vale-styles/Homebrew/Headings.yml @@ -0,0 +1,89 @@ +extends: capitalization +message: "'%s' should be in sentence case" +level: error +scope: + - heading.h2 + - heading.h3 + - heading.h4 + - heading.h5 + - heading.h6 +match: $sentence +threshold: 1.0 +exceptions: + - Annual General Meeting + - Apple Silicon + - AGM + - AI + - API + - ARM32 + - ASCII + - CI + - CLI + - CLT + - CMake + - Claude Desktop + - Codecov + - Cursor + - DSL + - Dock + - Git + - GitHub + - Go + - Homebrew + - HTTPS + - ID + - How do I + - after I + - should I + - Can I + - can I + - when I + - JDK + - JSON + - Linux + - LLM + - Launchpad + - MPI + - OSDN + - Ops Team + - PLC + - PRs + - PowerShell + - Python + - Project Leader + - Project Leadership Committee + - Ruby + - Rust + - SHA-256 + - SPDX + - Security Team + - SOS + - Sublime Text + - SourceForge + - Subversion + - URL + - URLs + - Terminal.app + - Tier 1 Support + - Tier 2 Support + - Tier 3 Support + - Open man Page + - VS Code + - Visual Studio Code + - Windows + - Windows Subsystem for Linux + - Windows 10 Subsystem for Linux + - Xcode + - Zed + - Brewfiles + - Command Line Tools + - Lead Maintainer + - Lead Maintainers + - PLC Members + - caveats + - fish + - formulae.brew.sh + - macOS + - target + - x86 + - zsh