Merge pull request #4845 from MikeMcQuaid/docs-update

docs: various updates.

docs/Acceptable-Formulae.md

@@ -16,7 +16,7 @@ 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 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 things during installation.
+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

docs/Analytics.md

@@ -42,9 +42,7 @@ As far as we can tell it would be impossible for Google to match the randomly ge
 Homebrew's analytics are sent throughout Homebrew's execution to Google Analytics over HTTPS.
 
 ## Who?
-Homebrew's detailed analytics are accessible to Homebrew's current maintainers. Contact @MikeMcQuaid if you are a maintainer and need access.
+Summaries of installation and error analytics are publicly available [here](https://brew.sh/analytics/). A JSON API is also available.
-
-Summaries of installation and error analytics are publicly available [here](https://brew.sh/analytics/).
 
 ## 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.

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. (That's Core 2 for 64-bit OSs, Core for 32-bit.) 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 --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).
@@ -76,6 +76,3 @@ pour_bottle? do
   satisfy { MacOS::CLT.installed? }
 end
 ```
-
-## Planned improvements
-Most bottle features have been (and planned improvements will be) implemented by @MikeMcQuaid. Contact him directly with questions.

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

@@ -2,7 +2,7 @@
 
 ## History
 
-Originally Homebrew was a build-from-source package manager and all user environment variables and non-Homebrew-installed software were available to builds. Since then Homebrew added `Requirement`s to specify dependencies on non-Homebrew software (such as those provided by `brew cask` like X11/XQuartz), the `superenv` build system to strip out unspecified dependencies, environment filtering to stop the user environment leaking into Homebrew builds and `default_formula` to specify that a `Requirement` can be satisifed by a particular formula.
+Originally Homebrew was a build-from-source package manager and all user environment variables and non-Homebrew-installed software were available to builds. Since then Homebrew added `Requirement`s to specify dependencies on non-Homebrew software (such as those provided by `brew cask` like X11/XQuartz), the `superenv` build system to strip out unspecified dependencies, environment filtering to stop the user environment leaking into Homebrew builds and `default_formula` to specify that a `Requirement` can be satisfied by a particular formula.
 
 As Homebrew became primarily a binary package manager, most users were fulfilling `Requirement`s with the `default_formula`, not with arbitrary alternatives. To improve quality and reduce variation, Homebrew now exclusively supports using the default formula, as an ordinary dependency, and no longer supports using arbitrary alternatives.
 

docs/C++-Standard-Libraries.md

@@ -2,19 +2,19 @@
 
 There are two C++ standard libraries supported by Apple compilers.
 
-The default for 10.8 and earlier is **libstdc++**, supported by Apple GCC
+The default for 10.9 and later is **libc++**, which is also the default for `clang` on older
+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.
 
-The default for 10.9 is **libc++**, which is also the default for `clang` on older
-platforms when building C++11 code.
-
 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 from an earlier version** - because the default C++
+**If you've upgraded to or later 10.9 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
 you were directed here by a build error, you can most likely fix the issue if

docs/External-Commands.md

@@ -9,12 +9,12 @@ brew mycommand --option1 --option3 formula
 without modifying Homebrew's internals.
 
 ## Command types
-External commands come in two flavors: Ruby commands and shell scripts.
+External commands come in two flavours: Ruby commands and shell scripts.
 
 In both cases, the command file should be executable (`chmod +x`) and live somewhere in `PATH`.
 
 ### Ruby commands
-An external command `extcmd` implemented as a Ruby command should be named `brew-extcmd.rb`. The command is executed by doing a `require` on the full pathname. As the command is `require`d, it has full access to the Homebrew "environment", i.e. all global variables and modules that any internal command has access to.
+An external command `extcmd` implemented as a Ruby command should be named `brew-extcmd.rb`. The command is executed by doing a `require` on the full pathname. As the command is `require`d, it has full access to the Homebrew "environment", i.e. all global variables and modules that any internal command has access to. Be wary of using Homebrew internals; they may change at any time without warning.
 
 The command may `Kernel.exit` with a status code if it needs to; if it doesn't explicitly exit then Homebrew will return `0`.
 
@@ -37,12 +37,9 @@ All internal and external Homebrew commands can provide styled `--help` output b
 
 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`.
 
-## User-submitted commands
+## Homebrew organisation external commands
-These commands have been contributed by Homebrew users but are not included in the main Homebrew repository, nor are they installed by the installer script. You can install them manually, as outlined above.
 
-Note they are largely untested, and as always, be careful about running untested code on your machine.
+### homebrew-livecheck
-
-### brew-livecheck
 Check if there is a new upstream version of a formula.
 See the [`README`](https://github.com/Homebrew/homebrew-livecheck/blob/master/README.md) for more info and usage.
 
@@ -52,19 +49,32 @@ Install using:
 brew tap homebrew/livecheck
 ```
 
-### brew-gem
+### homebrew-command-not-found
-Install any `gem` package into a self-contained Homebrew Cellar location: <https://github.com/sportngin/brew-gem>
+Ubuntu's `command-not-found equivalent` for Homebrew.
-
+See the [`README`](https://github.com/Homebrew/homebrew-command-not-found/blob/master/README.md) for more info and usage.
-Note this can also be installed with `brew install brew-gem`.
-
-### brew-growl
-Get Growl notifications for Homebrew: <https://github.com/secondplanet/homebrew-growl>
-
-### brew-services
-Simple support for starting formulae using launchctl, has out of the box support for any formula which defines `startup_plist` (e.g. mysql, postgres, redis u.v.m.): <https://github.com/Homebrew/homebrew-services>
 
 Install using:
 
 ```sh
-brew tap homebrew/services
+brew tap homebrew/command-not-found
 ```
+
+### homebrew-aliases
+Allows you to alias your Homebrew commands.
+See the [`README`](https://github.com/Homebrew/homebrew-aliases/blob/master/README.md) for more info and usage.
+
+Install using:
+
+```sh
+brew tap homebrew/aliases
+```
+
+## Unofficial external commands
+These commands have been contributed by Homebrew users but are not included in the main Homebrew organisation, nor are they installed by the installer script. You can install them manually, as outlined above.
+
+Note they are largely untested, and as always, be careful about running untested code on your machine.
+
+### brew-gem
+Install any `gem` package into a self-contained Homebrew Cellar location: <https://github.com/sportngin/brew-gem>
+
+Note this can also be installed with `brew install brew-gem`.

docs/FAQ.md

@@ -108,10 +108,6 @@ cd $(brew --repository)
 hub pull someone_else
 ```
 
-Or:
-
-    brew install https://raw.github.com/user/repo/branch/formula.rb
-
 Or:
 
     brew pull https://github.com/Homebrew/homebrew-core/pull/1234
@@ -142,7 +138,7 @@ anyway.
 Homebrew refuses to work using sudo.
 
 You should only ever sudo a tool you trust. Of course, you can trust Homebrew
-;) But do you trust the multi-megabyte Makefile that Homebrew runs? Developers
+😉 But do you trust the multi-megabyte Makefile that Homebrew runs? Developers
 often understand C++ far better than they understand make syntax. It’s too high
 a risk to sudo such stuff. It could modify (or upload) any files on your
 system.And indeed, we’ve seen some build scripts try to modify `/usr` even when
@@ -205,7 +201,7 @@ 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 realized it was, it was too
+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 ;-)
 

docs/Formula-Cookbook.md

@@ -160,6 +160,8 @@ A Hash (e.g. `=>`) specifies a formula dependency with some additional informati
       depends_on "foo" => :optional # Generated description is "Build with foo support"
       ```
 
+We frown on [`option`](http://www.rubydoc.info/github/Homebrew/brew/master/Formula#option-class_method)s in Homebrew/homebrew-core as they are not tested by CI.
+
 ### Specifying conflicts with other formulae
 
 Sometimes there’s hard conflict between formulae, and it can’t be avoided or circumvented with [`keg_only`](http://www.rubydoc.info/github/Homebrew/brew/master/Formula#keg_only-class_method).
@@ -663,6 +665,8 @@ end
 
 Note that [`option`](http://www.rubydoc.info/github/Homebrew/brew/master/Formula#option-class_method)s that aren’t `build.with? ` or `build.without?` should be deprecated with [`deprecated_option`](http://www.rubydoc.info/github/Homebrew/brew/master/Formula#deprecated_option-class_method). See [wget](https://github.com/Homebrew/homebrew-core/blob/master/Formula/wget.rb#L27-L31) for an example.
 
+We frown on [`option`](http://www.rubydoc.info/github/Homebrew/brew/master/Formula#option-class_method)s in Homebrew/homebrew-core as they are not tested by CI.
+
 ### File level operations
 
 You can use the file utilities provided by Ruby's [`FileUtils`](https://www.ruby-doc.org/stdlib/libdoc/fileutils/rdoc/index.html). These are included in the `Formula` class, so you do not need the `FileUtils.` prefix to use them.

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

@@ -32,7 +32,7 @@ To make a new branch and submit it for review, create a GitHub pull request with
 1. Check out the `master` branch with `git checkout master`.
 2. Retrieve new changes to the `master` branch with `brew update`.
 3. Create a new branch from the latest `master` branch with `git checkout -b <YOUR_BRANCH_NAME> origin/master`.
-4. Make your changes. For formulae, use `brew edit` or your favorite text editor, following all the guidelines in the [Formula Cookbook](Formula-Cookbook.md).
+4. Make your changes. For formulae, use `brew edit` or your favourite text editor, following all the guidelines in the [Formula Cookbook](Formula-Cookbook.md).
   * If there's a `bottle do` block in the formula, don't remove or change it; we'll update it when we pull your PR.
 5. Test your changes by doing the following, and ensure they all pass without issue. For changed formulae, make sure you do the `brew audit` step while your changed formula is installed.
   * `brew tests`

docs/Interesting-Taps-and-Forks.md

@@ -25,8 +25,6 @@ Your taps are Git repositories located at `$(brew --repository)/Library/Taps`.
 
 *   [brewsci/bio](https://github.com/brewsci/homebrew-bio): Bioinformatics formulae.
 
-*   [brewsci/science](https://github.com/brewsci/homebrew-science): Software tailored to scientific endeavours.
-
 *   [davidchall/hep](https://github.com/davidchall/homebrew-hep): High energy physics formulae.
 
 *   [lifepillar/appleii](https://github.com/lifepillar/homebrew-appleii): Formulae for vintage Apple emulation.

docs/Maintainers-Avoiding-Burnout.md

@@ -15,12 +15,12 @@ you should also decide not to be a maintainer and find other things to work on.
 ## 2. No Guilt About Leaving
 
 All maintainers can stop working on Homebrew at any time without any guilt or
-explanation (like a job). We may still ask for your help with questions after
+explanation (like leaving a job). We may still ask for your help with questions
-you leave but you are under no obligation to answer them. Like a job, if you
+after you leave but you are under no obligation to answer them. Like a job, if
-create a big mess and then leave you still have no obligations but we may think
+you create a big mess and then leave you still have no obligations but we may
-less of you (or, realistically, probably just revert the problematic work).
+think less of you (or, realistically, probably just revert the problematic
-Like a job, you should probably take a break from Homebrew at least a few times
+work). Like a job, you should probably take a break from Homebrew at least a few
-a year.
+times a year.
 
 This also means contributors should be consumers. If an owner finds they are
 not using a project in the real world, they should reconsider their involvement

docs/Prose-Style-Guidelines.md

@@ -42,10 +42,10 @@ We prefer:
 * Sentence case in section headings, not Title Case
 * Periods at the ends of list items where most items in that list are complete sentences
 * More generally, parallel list item structure
-* Capitalize 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
+* 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
-  * GitHub Flavored Markdown. GitHub's implementation is the standard, period.
+  * GitHub Flavoured Markdown. GitHub's implementation is the standard, period.
 
 ### Typographical conventions
 
@@ -56,12 +56,12 @@ 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
-* Capitalized proper nouns
+* Capitalised proper nouns
-* We do not defer to extensive nonstandard capitalization, typesetting, or other styling of brand names, aside from the normal capitalization of proper nouns and simple internal capitalization
+* 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", &trade;, <sup>SM</sup>, &copy;, &reg;, or other explicit indicators of rights ownership or trademarks; we take these as understood when the brand name is mentioned
 * Tap names like `homebrew/core` are styled in `fixed width font`. Repository names may be styled in either fixed width font like "`Homebrew/homebrew-core`", as links like "[Homebrew/homebrew-core](https://github.com/homebrew/homebrew-core)", or regular text like "Homebrew/homebrew-core", based on which looks best for a given use.
   * But be consistent within a single document
-  * Capitalize repository names to match the user and repository names on GitHub. Keep tap names in lower case.
+  * Capitalise repository names to match the user and repository names on GitHub. Keep tap names in lower case.
 * Commas
   * No Oxford commas
   * Prefer a "loose" comma style: "when in doubt, leave it out" unless needed for clarity

docs/Querying-Brew.md

@@ -27,8 +27,6 @@ The current schema version is `v1`. Note that fields may be added to the schema
 
 The schema itself is not currently documented outside of the code that generates it: [Formula#to_hash](https://github.com/Homebrew/brew/blob/master/Library/Homebrew/formula.rb)
 
-(**TODO**: add a manpage for the schema)
-
 ## Examples
 
 _The top-level element of the JSON output is always an array, so the `map` operator is used to act on the data._

docs/Shell-Completion.md

@@ -18,7 +18,7 @@ fi
 ```
 
 ## Configuring Completions in `zsh`
-To make Homebrew's completions available in `zsh`, you must get the Homebrew-managed zsh site-functions on your `$FPATH` before initializing `zsh`'s completion facility. Add the following to your `~/.zshrc` file:
+To make Homebrew's completions available in `zsh`, you must get the Homebrew-managed zsh site-functions on your `$FPATH` before initialising `zsh`'s completion facility. Add the following to your `~/.zshrc` file:
 
 ```sh
 if type brew &>/dev/null; then

docs/Taps.md

@@ -59,7 +59,7 @@ If your tap contains a formula that is also present in
 [`homebrew/core`](https://github.com/Homebrew/homebrew-core), that's fine,
 but it means that you must install it explicitly by default.
 
-If you would like to prioritize a tap over `homebrew/core`, you can use
+If you would like to prioritise a tap over `homebrew/core`, you can use
 `brew tap-pin username/repo` to pin the tap,
 and use `brew tap-unpin username/repo` to revert the pin.
 

docs/Tips-N'-Tricks.md

@@ -3,7 +3,7 @@
 ## Installing previous versions of formulae
 
 The supported method of installing specific versions of
-some formulae is to see if there is a versioned formula (e.g. `gcc@6`) available. If the version you’re looking for isn’t available, consider [opening a pull request](How-To-Open-a-Homebrew-Pull-Request.md)!
+some formulae is to see if there is a versioned formula (e.g. `gcc@6`) available. If the version you’re looking for isn’t available, consider using `brew extract`.
 
 ### Installing directly from pull requests
 You can [browse pull requests](https://github.com/Homebrew/homebrew-core/pulls)

docs/Versions.md

@@ -13,7 +13,7 @@ Versioned formulae we include in [homebrew/core](https://github.com/homebrew/hom
 * Formulae that depend on versioned formulae must not depend on the same formulae at two different versions twice in their recursive dependencies. For example, if you depend on `openssl@1.0` and `foo`, and `foo` depends on `openssl` then you must instead use `openssl`.
 * Versioned formulae should only be linkable at the same time as their non-versioned counterpart if the upstream project provides support for it, e.g. using suffixed binaries. If this is not possible, use `keg_only :versioned_formula` to allow users to have multiple versions installed at once.
 * A `keg_only :versioned_formula` should not `post_install` anything in the `HOMEBREW_PREFIX` that conflicts with or duplicates the non-versioned counterpart (or other versioned formulae). For example, a `node@6` formula should not install its `npm` into `HOMEBREW_PREFIX` like the `node` formula does.
-* Versioned formulae submitted should be expected to be used by a large number of people. If this ceases to be the case: they will be removed. We will aim not to remove those in the [top 1000 `install_on_request` formulae](https://brew.sh/analytics/install-on-request/).
+* Versioned formulae submitted should be expected to be used by a large number of people. If this ceases to be the case: they will be removed. We will aim not to remove those in the [top 3,000 `install_on_request` formulae](https://brew.sh/analytics/install-on-request/).
 * Versioned formulae should not have `resource`s that require security updates. For example, a `node@6` formula should not have an `npm` resource but instead rely on the `npm` provided by the upstream tarball.
 * Versioned formulae should be as similar as possible and sensible to the unversioned formulae. Creating or updating a versioned formula should be a chance to ask questions of the unversioned formula e.g. can some unused or useless options be removed or made default?
 * No more than five versions of a formula (including the non-versioned one) will be supported at any given time, regardless of usage. When removing formulae that violate this we will aim to do so based on usage and support status rather than age.