Merge pull request #6826 from issyl0/vale

Add Vale linting for our docs

.github/workflows/tests.yml

@@ -130,6 +130,12 @@ jobs:
         export PATH="/home/linuxbrew/.linuxbrew/bin:/usr/local/bin:/usr/bin:/bin"
         brew readall --aliases
 
+    - name: Run vale for docs linting
+      run: |
+        export PATH="/home/linuxbrew/.linuxbrew/bin:/usr/local/bin:/usr/bin:/bin"
+        brew install vale
+        vale $(brew --repo)/docs/
+
     - name: Build Docker image
       run: |
         docker pull homebrew/brew

.gitignore

@@ -154,6 +154,7 @@
 !/.editorconfig
 !/.gitignore
 !/.yardopts
+!/.vale.ini
 !/CHANGELOG.md
 !/CONTRIBUTING.md
 !/Dockerfile

.vale.ini

@@ -0,0 +1,4 @@
+StylesPath = ./docs/vale-styles
+
+[*.md]
+BasedOnStyles = Homebrew

Library/Homebrew/manpages/brew.1.md.erb

@@ -9,7 +9,7 @@
 #
 # When done, regenerate the man page and its HTML version by running `brew man`.
 %>
-brew(1) -- The missing package manager for macOS
+brew(1) -- The Missing Package Manager for macOS
 ================================================
 
 ## SYNOPSIS

docs/Bottles.md

@@ -1,4 +1,4 @@
-# Bottles (binary packages)
+# Bottles (Binary Packages)
 
 Bottles are produced by installing a formula with `brew install --build-bottle <formula>` and then bottling it with `brew bottle <formula>`. This outputs the bottle DSL which should be inserted into the formula file.
 

docs/FAQ.md

@@ -204,9 +204,9 @@ our analytics identified it was not widely used.
 
 ## Homebrew is a poor name, it's too generic, why was it chosen?
 @mxcl was too concerned with the beer theme and didn’t consider that the
-project may actually prove popular. By the time he realised it was, it was too
-late. However, today, the first Google hit for “homebrew” is not beer
-related ;‑)
+project may actually prove popular. By the time Max realised that it
+was popular, it was too late. However, today, the first Google hit for
+“homebrew” is not beer related ;‑)
 
 ## What does "keg-only" mean?
 It means the formula is installed only into the Cellar; it is not linked

docs/Formula-Cookbook.md

@@ -732,9 +732,9 @@ Homebrew provides two formula DSL methods for launchd plist files:
 
 Homebrew has multiple levels of environment variable filtering which affects variables available to formulae.
 
-Firstly, the overall environment in which Homebrew runs is filtered to avoid environment contamination breaking from-source builds (<https://github.com/Homebrew/brew/issues/932>).  In particular, this process filters all but the given whitelisted variables, but allows environment variables prefixed with `HOMEBREW_`. The specific implementation can be seen in [`bin/brew`](https://github.com/Homebrew/brew/blob/master/bin/brew).
+Firstly, the overall environment in which Homebrew runs is filtered to avoid environment contamination breaking from-source builds (<https://github.com/Homebrew/brew/issues/932>). In particular, this process filters all but the given whitelisted variables, but allows environment variables prefixed with `HOMEBREW_`. The specific implementation can be seen in [`bin/brew`](https://github.com/Homebrew/brew/blob/master/bin/brew).
 
-The second level of filtering removes sensitive environment variables (such as credentials like keys, passwords or tokens) to avoid malicious subprocesses obtaining them (<https://github.com/Homebrew/brew/pull/2524>).  This has the effect of preventing any such variables from reaching a formula's Ruby code as they are filtered before it is called.  The specific implementation can be seen in the [`ENV.clear_sensitive_environment!` method](https://github.com/Homebrew/brew/blob/master/Library/Homebrew/extend/ENV.rb).
+The second level of filtering removes sensitive environment variables (such as credentials like keys, passwords or tokens) to avoid malicious subprocesses obtaining them (<https://github.com/Homebrew/brew/pull/2524>). This has the effect of preventing any such variables from reaching a formula's Ruby code as they are filtered before it is called. The specific implementation can be seen in the [`ENV.clear_sensitive_environment!` method](https://github.com/Homebrew/brew/blob/master/Library/Homebrew/extend/ENV.rb).
 
 In summary, environment variables used by a formula need to conform to these filtering rules in order to be available.
 

docs/Homebrew-linuxbrew-core-Maintainer-Guide.md

@@ -1,4 +1,4 @@
-# Homebrew linuxbrew-core Maintainer Guide
+# Homebrew/linuxbrew-core Maintainer Guide
 
 ## Merging formulae updates from Homebrew/homebrew-core
 
@@ -23,7 +23,7 @@ export HOMEBREW_NO_AUTO_UPDATE=1
 Once we've done that, we need to get access to the `merge-homebrew`
 command that will be used for the merge. To do that we have to tap the
 [`Homebrew/linux-dev`](https://github.com/Homebrew/homebrew-linux-dev)
-repo:
+repository:
 
 ```bash
 brew tap homebrew/linux-dev
@@ -235,7 +235,7 @@ against the formulae:
 And it skips formulae if any of the following are true:
 - it doesn't need a bottle
 - it already has a bottle
-- the formula's tap is Homebrew/homebrew-core (the upstream macOS repo)
+- the formula's tap is Homebrew/homebrew-core (the upstream macOS repository)
 - there is already an open PR for the formula's bottle
 - the current branch is not master
 

docs/How-To-Open-a-Homebrew-Pull-Request.md

@@ -1,4 +1,4 @@
-# How To Open a Homebrew Pull Request (and get it merged)
+# How To Open a Homebrew Pull Request
 
 The following commands are used by Homebrew contributors to set up a fork of Homebrew's Git repository on GitHub, create a new branch and create a GitHub pull request ("PR") of the changes in that branch.
 

docs/How-to-Build-Software-Outside-Homebrew-with-Homebrew-keg-only-Dependencies.md

@@ -1,4 +1,4 @@
-# How to build software outside Homebrew with Homebrew `keg_only` dependencies
+# How to Build Software Outside Homebrew with Homebrew `keg_only` Dependencies
 
 ## What does "keg-only" mean?
 

docs/Manpage.md

@@ -1,4 +1,4 @@
-brew(1) -- The missing package manager for macOS
+brew(1) -- The Missing Package Manager for macOS
 ================================================
 
 ## SYNOPSIS

docs/Prose-Style-Guidelines.md

@@ -1,3 +1,5 @@
+<!-- vale off -->
+<!-- Disable vale linting for the whole of the style guide, because it contains deliberately bad examples. -->
 # Prose Style Guidelines
 
 This is a set of style and usage guidelines for Homebrew's prose documentation aimed at users, contributors, and maintainers (as opposed to executable computer code). It applies to documents like those in `docs` in the `Homebrew/brew` repository, announcement emails, and other communications with the Homebrew community.
@@ -39,7 +41,7 @@ We prefer:
 
 ### Structure and markup
 
-* Sentence case in section headings, not Title Case
+* Title Case in `h1` headings; sentence case in all other headings
 * Periods at the ends of list items where most items in that list are complete sentences
 * More generally, parallel list item structure
 * 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
@@ -86,3 +88,5 @@ Refer to these guidelines to make decisions about style and usage in your own wr
 PRs that fix style and usage throughout a document or multiple documents are okay and encouraged. PRs for just one or two style changes are a bit much.
 
 Giving style and usage feedback on a PR or commit that involves documents is okay and encouraged. But keep in mind that these are just guidelines, and for any change, the author may have made a deliberate choice to break these rules in the interest of understandability or aesthetics.
+
+<!-- vale on -->

docs/Taps.md

@@ -1,4 +1,4 @@
-# Taps (third-party repositories)
+# Taps (Third-Party Repositories)
 
 `brew tap` adds more repositories to the list of formulae that `brew` tracks, updates,
 and installs from. By default, `tap` assumes that the repositories come from GitHub,
@@ -16,12 +16,15 @@ mistydemeo/tigerbrew
 dunn/emacs
 ```
 
+<!-- vale Homebrew.Terms = OFF -->
+<!-- The `terms` lint suggests changing "repo" to "repository". But we need the abbreviation in the tap syntax and URL example. -->
 * `brew tap <user/repo>` makes a shallow clone of the repository at
   https://github.com/user/repo. After that, `brew` will be able to work on
   those formulae as if they were in Homebrew's canonical repository. You can
   install and uninstall them with `brew [un]install`, and the formulae are
   automatically updated when you run `brew update`. (See below for details
   about how `brew tap` handles the names of repositories.)
+<!-- vale Homebrew.Terms = ON -->
 
 * `brew tap <user/repo> <URL>` makes a shallow clone of the repository at URL.
   Unlike the one-argument version, URL is not assumed to be GitHub, and it

docs/_config.yml

@@ -7,6 +7,7 @@ exclude:
   - bin
   - CNAME
   - Gemfile*
+  - vale-styles
   - vendor
 
 plugins:

docs/vale-styles/Homebrew/Abbreviations.yml

@@ -0,0 +1,12 @@
+---
+extends: substitution
+message: Use '%s'
+ignorecase: false
+link: 'https://github.com/Homebrew/brew/blob/master/docs/Prose-Style-Guidelines.md#style-and-usage'
+level: error
+nonword: true
+swap:
+  '\beg\b': e.g.
+  '\bie\b': i.e.
+  'e\.g\.,': e.g.
+  'i\.e\.,': i.e.

docs/vale-styles/Homebrew/OxfordComma.yml

@@ -0,0 +1,8 @@
+---
+extends: existence
+message: 'No Oxford commas!'
+link: 'https://github.com/Homebrew/brew/blob/master/docs/Prose-Style-Guidelines.md#typographical-conventions'
+scope: sentence
+level: warning
+tokens:
+  - '(?:[^,]+,){1,}\s\w+,\sand'

docs/vale-styles/Homebrew/Pronouns.yml

@@ -0,0 +1,15 @@
+---
+extends: existence
+message: Avoid gender-specific language when not necessary.
+link: 'https://github.com/Homebrew/brew/blob/master/docs/Prose-Style-Guidelines.md#personal-pronouns'
+level: warning
+ignorecase: true
+tokens:
+  - him
+  - her
+  - she
+  - he
+  - his
+  - hers
+  - himself
+  - herself

docs/vale-styles/Homebrew/README.md

@@ -0,0 +1 @@
+Based on Homebrew's [Prose Style Guidelines](http://docs.brew.sh/Prose-Style-Guidelines.html).

docs/vale-styles/Homebrew/Spacing.yml

@@ -0,0 +1,9 @@
+---
+extends: existence
+message: "'%s' should have one space."
+link: 'https://github.com/Homebrew/brew/blob/master/docs/Prose-Style-Guidelines.md#typographical-conventions'
+level: error
+nonword: true
+tokens:
+  - '[a-z][.?!][A-Z]'
+  - '[.?!] {2,}[A-Z]'

docs/vale-styles/Homebrew/Terms.yml

@@ -0,0 +1,10 @@
+---
+extends: substitution
+message: Use '%s' instead of '%s'.
+link: 'https://github.com/Homebrew/brew/blob/master/docs/Prose-Style-Guidelines.md#terminology-words-and-word-styling'
+level: error
+scope: $paragraph
+swap:
+  Pull Request: pull request
+  repo: repository
+  Rubocop: RuboCop

docs/vale-styles/Homebrew/Titles.yml

@@ -0,0 +1,10 @@
+extends: capitalization
+message: "'%s' should be in title case"
+level: warning
+scope: heading.h1
+match: $title
+style: AP
+exceptions:
+  - brew(1)
+  - Homebrew/homebrew-core
+  - Homebrew/linuxbrew-core

docs/vale-styles/Homebrew/Trademarks.yml

@@ -0,0 +1,12 @@
+---
+extends: existence
+message: 'No "TM", ™, SM, ©, ®, or other explicit indicators of rights ownership or trademarks'
+link: 'https://github.com/Homebrew/brew/blob/master/docs/Prose-Style-Guidelines.md#typographical-conventions'
+level: error
+nonword: true
+tokens:
+  - \bTM\b
+  - ™
+  - \bSM\b
+  - ©
+  - ®

manpages/brew.1

@@ -4,7 +4,7 @@
 .TH "BREW" "1" "December 2019" "Homebrew" "brew"
 .
 .SH "NAME"
-\fBbrew\fR \- The missing package manager for macOS
+\fBbrew\fR \- The Missing Package Manager for macOS
 .
 .SH "SYNOPSIS"
 \fBbrew\fR \fB\-\-version\fR