various documentation edits

Library/.editorconfig → .editorconfig

@@ -9,9 +9,13 @@ indent_style = space
 indent_size = 2
 insert_final_newline = true
 
-[{Homebrew/**.rb,.simplecov}]
+[{Library/Homebrew/**.rb,.simplecov}]
 trim_trailing_whitespace = true
 
-[Taps/homebrew/**.rb]
+[Library/Taps/homebrew/**.rb]
 # trailing whitespace is crucial for patches
 trim_trailing_whitespace = false
+
+[**.md]
+trim_trailing_whitespace = true
+x-soft-wrap-text = true

CONTRIBUTING.md

@@ -5,7 +5,7 @@ First time contributing to Homebrew? Read our [Code of Conduct](https://github.c
 
 * Run `brew update` (twice).
 * Run and read `brew doctor`.
-* Read [the Troubleshooting Checklist](https://docs.brew.sh/Troubleshooting).
+* Read the [Troubleshooting checklist](https://docs.brew.sh/Troubleshooting).
 * Open an issue on the formula's repository or on Homebrew/brew if it's not a formula-specific issue.
 
 ### Propose a feature

README.md

@@ -46,7 +46,7 @@ Homebrew/brew's Linux support (and Linuxbrew) maintainers are [Michka Popoff](ht
 
 Homebrew/homebrew-core's other current maintainers are [Claudia](https://github.com/claui), [Michka Popoff](https://github.com/imichka), [Shaun Jackman](https://github.com/sjackman), [Chongyu Zhu](https://github.com/lembacon), [commitay](https://github.com/commitay), [Izaak Beekman](https://github.com/zbeekman), [Sean Molenaar](https://github.com/SMillerDev), [Jan Viljanen](https://github.com/javian), [Viktor Szakats](https://github.com/vszakats), [FX Coudert](https://github.com/fxcoudert), [Steven Peters](https://github.com/scpeters), [JCount](https://github.com/jcount), [Misty De Meo](https://github.com/mistydemeo) and [Tom Schoonjans](https://github.com/tschoonj).
 
-Former maintainers with significant contributions include [Dominyk Tiller](https://github.com/DomT4), [Tim Smith](https://github.com/tdsmith), [Baptiste Fontaine](https://github.com/bfontaine), [Xu Cheng](https://github.com/xu-cheng), [Martin Afanasjew](https://github.com/UniqMartin),  [Brett Koonce](https://github.com/asparagui), [Charlie Sharpsteen](https://github.com/Sharpie), [Jack Nagel](https://github.com/jacknagel), [Adam Vandenberg](https://github.com/adamv), [Andrew Janke](https://github.com/apjanke), [Alex Dunn](https://github.com/dunn), [neutric](https://github.com/neutric), [Tomasz Pajor](https://github.com/nijikon), [Uladzislau Shablinski](https://github.com/vladshablinsky), [Alyssa Ross](https://github.com/alyssais), [ilovezfs](https://github.com/ilovezfs) and Homebrew's creator: [Max Howell](https://github.com/mxcl).
+Former maintainers with significant contributions include [Dominyk Tiller](https://github.com/DomT4), [Tim Smith](https://github.com/tdsmith), [Baptiste Fontaine](https://github.com/bfontaine), [Xu Cheng](https://github.com/xu-cheng), [Martin Afanasjew](https://github.com/UniqMartin), [Brett Koonce](https://github.com/asparagui), [Charlie Sharpsteen](https://github.com/Sharpie), [Jack Nagel](https://github.com/jacknagel), [Adam Vandenberg](https://github.com/adamv), [Andrew Janke](https://github.com/apjanke), [Alex Dunn](https://github.com/dunn), [neutric](https://github.com/neutric), [Tomasz Pajor](https://github.com/nijikon), [Uladzislau Shablinski](https://github.com/vladshablinsky), [Alyssa Ross](https://github.com/alyssais), [ilovezfs](https://github.com/ilovezfs) and Homebrew's creator: [Max Howell](https://github.com/mxcl).
 
 ## Community
 - [discourse.brew.sh (forum)](https://discourse.brew.sh)
@@ -68,7 +68,7 @@ Alternatively, if you'd rather make a one-off payment:
 
 - [Donate with PayPal](https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=V6ZE57MJRYC8L)
 - Donate by USA $ check from a USA bank:
-  - Make check payable to "Software Freedom Conservancy, Inc." and place "Directed donation: Homebrew" in the memo field.  Checks should then be mailed to:
+  - Make check payable to "Software Freedom Conservancy, Inc." and place "Directed donation: Homebrew" in the memo field. Checks should then be mailed to:
     - Software Freedom Conservancy, Inc.
       137 Montague ST  STE 380
       BROOKLYN, NY 11201             USA
@@ -93,7 +93,7 @@ Our bottles (binary packages) are hosted by [Bintray](https://bintray.com/homebr
 
 [![Downloads by Bintray](https://bintray.com/docs/images/downloads_by_bintray_96.png)](https://bintray.com/homebrew)
 
-Secure password storage and syncing provided by [1Password for Teams](https://1password.com/teams/) by [AgileBits](https://agilebits.com).
+Secure password storage and syncing is provided by [1Password for Teams](https://1password.com/teams/) by [AgileBits](https://agilebits.com).
 
 [![AgileBits](https://da36klfizjv29.cloudfront.net/assets/branding/agilebits-fcca96e9b8e815c5c48c6b3e98156cb5.png)](https://agilebits.com)
 

docs/Acceptable-Formulae.md

@@ -15,15 +15,15 @@ We now accept versioned formulae as long as they [meet the requirements](Version
 Software that can upgrade itself does not integrate well with Homebrew's own
 upgrade functionality. The self-update functionality should be disabled (if possible without complicating the formula).
 
-### We don’t like install-scripts that download unversioned things
+### We don’t like install scripts that download unversioned things
 We don't like install scripts that are pulling from the `master` branch of Git repositories or unversioned, unchecksummed tarballs. These should use `resource` blocks with specific revisions or checksummed tarballs instead. Note that we now allow tools like `cargo`, `gem` and `pip` to download specifically versioned libraries during installation.
 
 ### We don’t like binary formulae
 Our policy is that formulae in the core tap
 ([homebrew/core](https://github.com/Homebrew/homebrew-core)) must be open-source
 and either built from source or produce cross-platform binaries (e.g. Java, Mono).
 Binary-only formulae should go to
-[Homebrew Cask](https://github.com/Homebrew/homebrew-cask).
+[homebrew/cask](https://github.com/Homebrew/homebrew-cask).
 
 ### Stable versions
 Formulae in the core repository must have a stable version tagged by
@@ -57,16 +57,16 @@ running a package manager.
 
 ### Stuff that builds an `.app`
 Don’t make your formula build an `.app` (native macOS Application); we
-don’t want those things in Homebrew. Encourage upstream projects to build and support a `.app` that can be distributed by [Homebrew Cask](https://github.com/Homebrew/homebrew-cask) (and used without it, too).
+don’t want those things in Homebrew. Encourage upstream projects to build and support a `.app` that can be distributed by [homebrew/cask](https://github.com/Homebrew/homebrew-cask) (and used without it, too).
 
 ### Stuff that builds a GUI by default (but doesn't have to)
-Make it build a command-line tool or a library by default and, if the GUI is useful and would be widely used, add an option to build the GUI. Don't offer an option for multiple GUI backends e.g. X11 is a bad user experience for GUIs on macOS.
+Make it build a command-line tool or a library by default and, if the GUI is useful and would be widely used, add an option to build the GUI. Don't offer an option for multiple GUI backends, e.g. X11 is a bad user experience for GUIs on macOS.
 
 ### Stuff that doesn't build with the latest, stable Xcode's Clang
 Clang is the default C/C++ compiler on macOS (and has been for a long time). Software that doesn't build with it hasn't been adequately ported to macOS.
 
 ### Stuff that requires heavy manual pre/post-install intervention
-We're a package manager so we want to do things like resolve dependencies and setup applications for our users. If things require too much manual intervention then they aren't useful in a package manager.
+We're a package manager so we want to do things like resolve dependencies and set up applications for our users. If things require too much manual intervention then they aren't useful in a package manager.
 
 ### Sometimes there are exceptions
 Even if all criteria are met we may not accept the formula.

docs/Analytics.md

@@ -25,10 +25,10 @@ Homebrew's analytics record some shared information for every event:
 
 Homebrew's analytics records the following different events:
 
-- an `event` hit type with the `install` event category and the Homebrew formula from a non-private GitHub tap you install plus any used options, e.g. `wget --with-pcre` as the action and an event label e.g. `macOS 10.12, non-/usr/local, CI` to indicate the OS version, non-standard installation location and invocation as part of CI. This allows us to identify the formulae that need fixing and where more easily.
-- an `event` hit type with the `install_on_request` event category and the Homebrew formula from a non-private GitHub tap you have requested to install (e.g. explicitly named it with a `brew install`) plus options and an event label as above. This allows us to differentiate the formulae that users intend to install from those pulled in as dependencies.
-- an `event` hit type with the `cask_install` event category and the Homebrew cask from a non-private GitHub tap you install as the action and an event label as above. This allows us to identify the casks that need fixing and where more easily.
-- an `event` hit type with the `BuildError` event category and the Homebrew formula that failed to install, e.g. `wget` as the action and an event label e.g. `macOS 10.12`.
+- An `event` hit type with the `install` event category and the Homebrew formula from a non-private GitHub tap you install plus any used options, e.g. `wget --with-pcre` as the action and an event label e.g. `macOS 10.12, non-/usr/local, CI` to indicate the OS version, non-standard installation location and invocation as part of CI. This allows us to identify the formulae that need fixing and where more easily.
+- An `event` hit type with the `install_on_request` event category and the Homebrew formula from a non-private GitHub tap you have requested to install (e.g. explicitly named it with a `brew install`) plus options and an event label as above. This allows us to differentiate the formulae that users intend to install from those pulled in as dependencies.
+- An `event` hit type with the `cask_install` event category and the Homebrew cask from a non-private GitHub tap you install as the action and an event label as above. This allows us to identify the casks that need fixing and where more easily.
+- An `event` hit type with the `BuildError` event category and the Homebrew formula that failed to install, e.g. `wget` as the action and an event label e.g. `macOS 10.12`.
 
 You can also view all the information that is sent by Homebrew's analytics by setting `HOMEBREW_ANALYTICS_DEBUG=1` in your environment. Please note this will also stop any analytics from being sent.
 
@@ -45,7 +45,7 @@ Homebrew's analytics are sent throughout Homebrew's execution to Google Analytic
 Summaries of installation and error analytics are publicly available [here](https://brew.sh/analytics/). A JSON API is also available.
 
 ## How?
-The code is viewable in [analytics.rb](https://github.com/Homebrew/brew/blob/master/Library/Homebrew/utils/analytics.rb) and [analytics.sh](https://github.com/Homebrew/brew/blob/master/Library/Homebrew/utils/analytics.sh). They are done in a separate background process and fail fast to avoid delaying any execution. They will fail immediately and silently if you have no network connection.
+The code is viewable in [`analytics.rb`](https://github.com/Homebrew/brew/blob/master/Library/Homebrew/utils/analytics.rb) and [`analytics.sh`](https://github.com/Homebrew/brew/blob/master/Library/Homebrew/utils/analytics.sh). They are done in a separate background process and fail fast to avoid delaying any execution. They will fail immediately and silently if you have no network connection.
 
 ## Opting out
 Homebrew analytics helps us maintainers and leaving it on is appreciated. However, if you want to opt out of Homebrew's analytics, you can set this variable in your environment:

docs/Bottles.md

@@ -10,7 +10,7 @@ Bottles will not be used if the user requests it (see above), if the formula req
 ## Creation
 Bottles are created using the [Brew Test Bot](Brew-Test-Bot.md). This happens mostly when people submit pull requests to Homebrew and the `bottle do` block is updated by maintainers when they `brew pull --bottle` the contents of a pull request. For the Homebrew organisations' taps they are uploaded to and downloaded from [Bintray](https://bintray.com/homebrew).
 
-By default, bottles will be built for the oldest CPU supported by the OS/architecture you're building for (Core 2 for 64-bit OSs). This ensures that bottles are compatible with all computers you might distribute them to. If you *really* want your bottles to be optimized for something else, you can pass the `--bottle-arch=` option to build for another architecture - for example, `brew install foo --bottle-arch=penryn`. Just remember that if you build for a newer architecture some of your users might get binaries they can't run and that would be sad!
+By default, bottles will be built for the oldest CPU supported by the OS/architecture you're building for (Core 2 for 64-bit OSs). This ensures that bottles are compatible with all computers you might distribute them to. If you *really* want your bottles to be optimized for something else, you can pass the `--bottle-arch=` option to build for another architecture; for example, `brew install foo --build-bottle --bottle-arch=penryn`. Just remember that if you build for a newer architecture some of your users might get binaries they can't run and that would be sad!
 
 ## Format
 Bottles are simple gzipped tarballs of compiled binaries. Any metadata is stored in a formula's bottle DSL and in the bottle filename (i.e. macOS version, revision).
@@ -62,7 +62,7 @@ Sometimes bottles may need be updated without bumping the version of the formula
 Contains the SHA-256 hash of a bottle for a particular version of macOS.
 
 ## Formula DSL
-Additionally there is a method available in the formula DSL.
+An additional method is available in the formula DSL.
 
 ### Pour bottle (`pour_bottle?`)
 Optionally returns a boolean to decide whether a bottle should be used for this formula.

docs/Building-Against-Non-Homebrew-Dependencies.md

@@ -8,4 +8,4 @@ As Homebrew became primarily a binary package manager, most users were fulfillin
 
 ## Today
 
-If you wish to build against custom non-Homebrew dependencies that are provided by Homebrew (e.g. a non-Homebrew, non-macOS `ruby`) then you must [create and maintain your own tap](How-to-Create-and-Maintain-a-Tap.md) as these formulae will not be accepted in Homebrew/homebrew-core. Once you have done that you can specify `env :std` in the formula which will allow a e.g. `which ruby` to access your existing `PATH` variable and allow compilation to link against this Ruby.
+If you wish to build against custom non-Homebrew dependencies that are provided by Homebrew (e.g. a non-Homebrew, non-macOS `ruby`) then you must [create and maintain your own tap](How-to-Create-and-Maintain-a-Tap.md) as these formulae will not be accepted in Homebrew/homebrew-core. Once you have done that you can specify `env :std` in the formula which will allow e.g. `which ruby` to access your existing `PATH` variable and allow compilation to link against this Ruby.

docs/C++-Standard-Libraries.md

@@ -7,18 +7,22 @@ platforms when building C++11 code.
 
 The default for 10.8 and earlier was **libstdc++**, supported by Apple GCC
 compilers, GNU GCC compilers, and `clang`. This was marked deprecated with a
-warning during compile as of Xcode 8.
+warning during compilation as of Xcode 8.
 
 There are subtle incompatibilities between several of the C++ standard libraries,
 so Homebrew will refuse to install software if a dependency was built with an
 incompatible C++ library. It's recommended that you install the dependency tree
 using a compatible compiler.
 
-**If you've upgraded to 10.9 or later from an earlier version** - because the default C++
+**If you've upgraded to 10.9 or later from an earlier version:** Because the default C++
 standard library is now libc++, you may not be able to build software using
-dependencies that you built on 10.8 or lower. If you're reading this page because
+dependencies that you built on 10.8 or earlier. If you're reading this page because
 you were directed here by a build error, you can most likely fix the issue if
 you reinstall all the dependencies of the package you're trying to build.
 
-Example install using GCC 4.8: ```brew install DESIRED_FORMULA --cc=gcc-4.8```.
-Get GCC 4.8 via: ```brew install gcc48```
+Example install using GCC 4.8:
+
+```sh
+brew install gcc48
+brew install --cc=gcc-4.8 <formula>
+```

docs/Common-Issues.md

@@ -70,7 +70,7 @@ These are likely due to one of four issues:
 
 1. You are using iTerm. The solution is to use Terminal.app when interacting with `launchctl`.
 2. You are using a terminal multiplexer such as `tmux` or `screen`. You should interact with `launchctl` from a separate Terminal.app shell.
-3. You are attempting to run `launchctl` while logged in remotely.  You should enable screen sharing on the remote machine and issue the command using Terminal.app running on that machine.
+3. You are attempting to run `launchctl` while logged in remotely. You should enable screen sharing on the remote machine and issue the command using Terminal.app running on that machine.
 4. You are `su`'ed as a different user.
 
 ### `brew upgrade` errors out
@@ -99,7 +99,7 @@ git clean -n # if this doesn't list anything that you want to keep, then
 git clean -f # this will remove untracked files
 ```
 
-### Python: easy-install.pth cannot be linked
+### Python: `easy-install.pth` cannot be linked
 
 ```
 Warning: Could not link <formula>. Unlinking...

docs/Custom-GCC-and-cross-compilers.md

@@ -17,6 +17,6 @@ GCC or cross-compiler suite, please link it in here.
 - Homebrew provides a `gcc` formula for use with Xcode 4.2+ or when needing
   C++11 support on earlier versions.
 - Homebrew provides older GCC formulae, e.g. `gcc@4.9` and `gcc@6`.
-- Homebrew provides the LLVM clang, which is bundled with the `llvm` formula.
+- Homebrew provides the LLVM Clang, which is bundled with the `llvm` formula.
 - [RISC-V](https://github.com/riscv/homebrew-riscv) provides the RISC-V
   toolchain including binutils and GCC.

docs/External-Commands.md

@@ -3,7 +3,7 @@
 Homebrew, like Git, supports *external commands*. This lets you create new commands that can be run like:
 
 ```sh
-brew mycommand --option1 --option3 formula
+brew mycommand --option1 --option3 <formula>
 ```
 
 without modifying Homebrew's internals.
@@ -27,15 +27,15 @@ A shell script for a command named `extcmd` should be named `brew-extcmd`. This
 | `HOMEBREW_CELLAR`      | The location of the Homebrew Cellar, where software is staged. This will be `HOMEBREW_PREFIX/Cellar` if that directory exists, or `HOMEBREW_REPOSITORY/Cellar` otherwise.   |
 | `HOMEBREW_LIBRARY_PATH`| The directory containing Homebrew’s own application code.                                                                                                                   |
 | `HOMEBREW_PREFIX`      | Where Homebrew installs software. This is always the grandparent directory of the `brew` executable, `/usr/local` by default.                                               |
-| `HOMEBREW_REPOSITORY`  | If installed from a Git clone, the repository directory (i.e. where Homebrew’s .git directory lives).                                                                       |
+| `HOMEBREW_REPOSITORY`  | If installed from a Git clone, the repository directory (i.e. where Homebrew’s `.git` directory lives).                                                                       |
 
 Note that the script itself can use any suitable shebang (`#!`) line, so an external “shell script” can be written for sh, bash, Ruby, or anything else.
 
 ## Providing `--help`
 
 All internal and external Homebrew commands can provide styled `--help` output by using lines starting with `#:` (a comment then `:` character in both Bash and Ruby) which are then output by `--help`.
 
-For example, see the [header of `brew services`](https://github.com/Homebrew/homebrew-services/blob/a5115e47b05e8d2a632ba7775599e698b240e5a2/cmd/brew-services.rb#L1-L31) which is output with `brew services --help`.
+For example, see the [header of `brew-services.rb`](https://github.com/Homebrew/homebrew-services/blob/a58a1fe9145de4e50e1cbfb5b0e8a30087826393/cmd/brew-services.rb#L1-L23) which is output with `brew services --help`.
 
 ## Homebrew organisation external commands