Merge pull request #15960 from EricFromCanada/docs-more-additions

Docs: more additions and improvements

README.md

@@ -39,7 +39,7 @@ We'd love you to contribute to Homebrew. First, please read our [Contribution Gu
 
 We explicitly welcome contributions from people who have never contributed to open-source before: we were all beginners once! We can help build on a partially working pull request with the aim of getting it merged. We are also actively seeking to diversify our contributors and especially welcome contributions from women from all backgrounds and people of colour.
 
-A good starting point for contributing is to first [tap Homebrew/homebrew-core](https://docs.brew.sh/FAQ#can-i-edit-formulae-myself), run `brew audit --strict` with some of the packages you use (e.g. `brew audit --strict wget` if you use `wget`) and then read through the warnings, try to fix them until `brew audit --strict` shows no results and [submit a pull request](https://docs.brew.sh/How-To-Open-a-Homebrew-Pull-Request). If no formulae you use have warnings you can run `brew audit --strict` without arguments to have it run on all packages and pick one.
+A good starting point for contributing is to first [tap `homebrew/core`](https://docs.brew.sh/FAQ#can-i-edit-formulae-myself), then run `brew audit --strict` with some of the packages you use (e.g. `brew audit --strict wget` if you use `wget`) and read through the warnings. Try to fix them until `brew audit --strict` shows no results and [submit a pull request](https://docs.brew.sh/How-To-Open-a-Homebrew-Pull-Request). If no formulae you use have warnings you can run `brew audit --strict` without arguments to have it run on all packages and pick one.
 
 Alternatively, for something more substantial, check out one of the issues labeled `help wanted` in [Homebrew/brew](https://github.com/homebrew/brew/issues?q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22) or [Homebrew/homebrew-core](https://github.com/homebrew/homebrew-core/issues?q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22).
 

docs/Acceptable-Casks.md

@@ -28,7 +28,7 @@ Stable versions live in the main repository at [Homebrew/homebrew-cask](https://
 
 #### But there is no Stable version!
 
-When software is only available as a beta, development, or unstable version, its cask can go in the main homebrew-cask repository. When stable versions become available, only those will be accepted as subsequent updates.
+When software is only available as a beta, development, or unstable version, its cask can go in the main `homebrew/cask` repository. When stable versions become available, only those will be accepted as subsequent updates.
 
 ### Beta, Unstable, Development, Nightly, or Legacy
 
@@ -57,7 +57,7 @@ We do not accept these casks since they involve a higher-than-normal security ri
 
 ### Fonts
 
-Font casks live in the [Homebrew/homebrew-cask-fonts](https://github.com/Homebrew/homebrew-cask-fonts) repository. See the homebrew-cask-fonts repository [CONTRIBUTING.md](https://github.com/Homebrew/homebrew-cask-fonts/blob/HEAD/CONTRIBUTING.md) for details.
+Font casks live in the [Homebrew/homebrew-cask-fonts](https://github.com/Homebrew/homebrew-cask-fonts) repository. See the `homebrew/cask-fonts` repository [CONTRIBUTING.md](https://github.com/Homebrew/homebrew-cask-fonts/blob/HEAD/CONTRIBUTING.md) for details.
 
 ## Apps that bundle malware
 
@@ -78,7 +78,7 @@ If a cask you depend on was removed due to these rules, fear not. Removal of a c
 Casks which do not reach a minimum notability threshold (see [Rejected Casks](#rejected-casks)) aren’t accepted in the main repositories because the increased maintenance burden doesn’t justify the poor usage numbers they will likely get. This notability check is performed automatically by the audit commands we provide, but its decisions aren’t set in stone. A cask which fails the notability check can be added if it is:
 
 1. A popular app that has its own website but the developers use GitHub for hosting the binaries. That repository won’t be notable but the app may be.
-2. Submitted by a maintainer or prolific contributor. A big part of the reasoning for the notability rule is unpopular software garners less attention and the cask gets abandoned, outdated, and broken. Someone with a proven investment in Hombrew Cask is less likely to let that happen for software they depend on.
+2. Submitted by a maintainer or prolific contributor. A big part of the reasoning for the notability rule is unpopular software garners less attention and the cask gets abandoned, outdated, and broken. Someone with a proven investment in Homebrew Cask is less likely to let that happen for software they depend on.
 3. A piece of software that was recently released to great fanfare—everyone is talking about it on Twitter and Hacker News and we’ve even gotten multiple premature submissions for it. That’d be a clear case of an app that will reach the threshold in no time so that’s a PR we won’t close immediately (but may wait to merge).
 
 Note that none of these exceptions is a guarantee for inclusion, but examples of situations where we may take a second look.
@@ -118,7 +118,7 @@ Common reasons to reject a cask entirely:
 * App installer is a `pkg` that requires [`allow_untrusted: true`](https://docs.brew.sh/Cask-Cookbook#pkg-allow_untrusted).
 * App fails with GateKeeper enabled on Homebrew supported macOS versions and platforms (e.g. unsigned apps fail on Macs with Apple silicon/ARM).
 
-Common reasons to reject a cask from the main homebrew-cask repository:
+Common reasons to reject a cask from the main `homebrew/cask` repository:
 
 * Cask was submitted to the wrong repository. When drafting a cask, consult [Finding a Home For Your Cask](#finding-a-home-for-your-cask) to see where it belongs.
 

docs/Adding-Software-to-Homebrew.md

@@ -22,7 +22,7 @@ If everything checks out, you're ready to get started on a new formula!
 
 1. Make sure you write a good test as part of your formula. Refer to the [Add a test to the formula](Formula-Cookbook.md#add-a-test-to-the-formula) section of the Cookbook for help with this.
 
-1. Try installing your formula using `brew install --build-from-source <formula>`, where \<formula> is the name of your formula. If any errors occur, correct your formula and attempt to install it again. The formula installation should finish without errors by the end of this step.
+1. Try installing your formula using `brew install --build-from-source <formula>`, where *\<formula>* is the name of your formula. If any errors occur, correct your formula and attempt to install it again. The formula installation should finish without errors by the end of this step.
 
 If you're stuck, ask for help on GitHub or the [Homebrew discussion forum](https://github.com/orgs/Homebrew/discussions). The maintainers are very happy to help but we also like to see that you've put effort into trying to find a solution first.
 
@@ -34,7 +34,7 @@ If you're stuck, ask for help on GitHub or the [Homebrew discussion forum](https
 
 ### Submitting the formula
 
-You're finally ready to submit your formula to the [homebrew-core](https://github.com/Homebrew/homebrew-core) repository. If you haven't done this before, you can refer to the [How to Open a Homebrew Pull Request](How-To-Open-a-Homebrew-Pull-Request.md) documentation for help. Maintainers will review the pull request and provide feedback about any areas that need to be addressed before the formula can be added to Homebrew.
+You're finally ready to submit your formula to the [homebrew-core](https://github.com/Homebrew/homebrew-core) repository. If you haven't done this before, you can refer to the [How to Open a Homebrew Pull Request](How-To-Open-a-Homebrew-Pull-Request.md#formulae-related-pull-request) documentation for help. Maintainers will review the pull request and provide feedback about any areas that need to be addressed before the formula can be added to Homebrew.
 
 If you've made it this far, congratulations on submitting a Homebrew formula! We appreciate the hard work you put into this and you can take satisfaction in knowing that your work may benefit other Homebrew users as well.
 
@@ -47,7 +47,7 @@ If you've made it this far, congratulations on submitting a Homebrew formula! We
 
 ### Writing the cask
 
-Making a new cask is easy. Follow the directions in [Getting Set Up To Contribute](https://github.com/Homebrew/homebrew-cask/blob/HEAD/CONTRIBUTING.md#getting-set-up-to-contribute) to begin.
+Making a new cask is easy. Follow the directions in [How to Open a Homebrew Pull Request](How-To-Open-a-Homebrew-Pull-Request.md#cask-related-pull-request) to begin.
 
 #### Examples
 
@@ -83,6 +83,8 @@ cask "noisy" do
   homepage "https://github.com/jonshea/Noisy"
 
   app "Noisy.app"
+
+  zap trash: "~/Library/Preferences/com.rathertremendous.noisy.plist"
 end
 ```
 
@@ -92,17 +94,17 @@ You will also see how to adapt `version` to the download `url`. Use [our custom
 
 ```ruby
 cask "airdisplay" do
-  version "3.4.2,26581"
+  version "3.4.2"
   sha256 "272d14f33b3a4a16e5e0e1ebb2d519db4e0e3da17f95f77c91455b354bee7ee7"
 
-  url "https://www.avatron.com/updates/software/airdisplay/ad#{version.before_comma.no_dots}.zip"
+  url "https://www.avatron.com/updates/software/airdisplay/ad#{version.no_dots}.zip"
   name "Air Display"
   desc "Utility for using a tablet as a second monitor"
   homepage "https://avatron.com/applications/air-display/"
 
   livecheck do
     url "https://www.avatron.com/updates/software/airdisplay/appcast.xml"
-    strategy :sparkle
+    strategy :sparkle, &:short_version
   end
 
   depends_on macos: ">= :mojave"
@@ -120,7 +122,7 @@ end
 
 The cask **token** is the mnemonic string people will use to interact with the cask via `brew install`, etc. The name of the cask **file** is simply the token with the extension `.rb` appended.
 
-The easiest way to generate a token for a cask is to run this command:
+The easiest way to generate a token for a cask is to run `generate_cask_token`:
 
 ```bash
 $(brew --repository homebrew/cask)/developer/bin/generate_cask_token "/full/path/to/new/software.app"
@@ -142,7 +144,7 @@ Once you know the token, create your cask with the handy-dandy `brew create --ca
 brew create --cask download-url --set-name my-new-cask
 ```
 
-This will open `$EDITOR` with a template for your new cask, to be stored in the file `my-new-cask.rb`. Running the `create` command above will get you a template that looks like this:
+This will open `EDITOR` with a template for your new cask, to be stored in the file `my-new-cask.rb`. Running the `create` command above will get you a template that looks like this:
 
 ```ruby
 cask "my-new-cask" do
@@ -198,13 +200,13 @@ When a downloaded archive expands to a subfolder, the subfolder name must be inc
 
 Example:
 
-1. Texmaker is downloaded to the file `TexmakerMacosxLion.zip`.
+1. Simple Floating Clock is downloaded to the file `sfc.zip`.
-1. `TexmakerMacosxLion.zip` unzips to a folder called `TexmakerMacosxLion`.
+1. `sfc.zip` unzips to a folder called `Simple Floating Clock`.
-1. The folder `TexmakerMacosxLion` contains the application `texmaker.app`.
+1. The folder `Simple Floating Clock` contains the application `SimpleFloatingClock.app`.
 1. So, the `app` stanza should include the subfolder as a relative path:
 
    ```ruby
-   app "TexmakerMacosxLion/texmaker.app"
+   app "Simple Floating Clock/SimpleFloatingClock.app"
    ```
 
 ### Testing and auditing the cask
@@ -246,7 +248,7 @@ If your application and Homebrew Cask do not work well together, feel free to [f
 
 See the [Acceptable Casks documentation](Acceptable-Casks.md#finding-a-home-for-your-cask).
 
-Hop into your Tap and check to make sure your new cask is there:
+Hop into your tap and check to make sure your new cask is there:
 
 ```bash
 $ cd "$(brew --repository)"/Library/Taps/homebrew/homebrew-cask
@@ -268,7 +270,7 @@ Switched to a new branch 'my-new-cask-branch'
 Stage your cask with:
 
 ```bash
-git add Casks/my-new-cask.rb
+git add Casks/m/my-new-cask.rb
 ```
 
 You can view the changes that are to be committed with:

docs/Brew-Livecheck.md

@@ -27,7 +27,7 @@ This can be accomplished by adding a `livecheck` block to the formula/cask/resou
 
 * **Only use `strategy` when it's necessary**. For example, if livecheck is already using the `Git` strategy for a URL, it's not necessary to use `strategy :git`. However, if `Git` applies to a URL but we need to use `PageMatch`, it's necessary to specify `strategy :page_match`.
 
-* **Only use the `GithubLatest` and `GithubReleases` strategies when they are necessary and correct**. GitHub rate limits API requests, so we only use these strategies when `Git` isn't sufficient or appropriate. `GithubLatest` should only be used if the upstream repository has a "latest" release for a suitable version and either the formula/cask uses a release asset or the `Git` strategy can't correctly identify the latest release version. `GithubReleases` should only be used if the upstream repository uses releases and both the `Git` and `GithubLatest` strategies aren't suitable.
+* **Only use the `GithubLatest` and `GithubReleases` strategies when they are necessary and correct**. GitHub rate-limits API requests, so we only use these strategies when `Git` isn't sufficient or appropriate. `GithubLatest` should only be used if the upstream repository has a "latest" release for a suitable version and either the formula/cask uses a release asset or the `Git` strategy can't correctly identify the latest release version. `GithubReleases` should only be used if the upstream repository uses releases and both the `Git` and `GithubLatest` strategies aren't suitable.
 
 ### URL guidelines
 

docs/Cask-Cookbook.md

@@ -1135,52 +1135,71 @@ Manual creation can be facilitated with:
 
 ### Handling different system configurations
 
-Casks can deliver specific versions of artifacts depending on the current system version or CPU architecture by using the [`on_<system>` syntax](Formula-Cookbook.md#handling-different-system-configurations), which replaces conditional statements using `MacOS.version` or `Hardware::CPU`. Each block can contain stanzas that set which version to download and customize installation/uninstallation and livecheck behaviour for each supported system. Example (from [calibre.rb](https://github.com/Homebrew/homebrew-cask/blob/482c34e950da8d649705f4aaea7b760dcb4b5402/Casks/c/calibre.rb#L2-L34)):
+Casks can deliver specific versions of artifacts depending on the current macOS release or CPU architecture by either tailoring the URL / SHA-256 hash / version, using the [`on_<system>` syntax](Formula-Cookbook.md#handling-different-system-configurations) (which replaces conditional statements using `MacOS.version` or `Hardware::CPU`), or both.
+
+If your cask's artifact is offered as separate downloads for Intel and Apple Silicon architectures, they'll presumably be downloadable at distinct URLs that differ only slightly. To adjust the URL depending on the current CPU architecture, supply a hash for each to the `arm:` and `intel:` parameters of `sha256`, and use the special `arch` stanza to define the unique components of the respective URLs for substitution in the `url`. Additional substitutions can be defined by calling `on_arch_conditional` directly. Example (from [libreoffice.rb](https://github.com/Homebrew/homebrew-cask/blob/a4164b8f5084fdaefb6e2e2f4f699270690b7845/Casks/l/libreoffice.rb#L1-L10)):
 
 ```ruby
-on_high_sierra :or_older do
+cask "libreoffice" do
-  version "3.48.0"
+  arch arm: "aarch64", intel: "x86-64"
-  sha256 "68829cd902b8e0b2b7d5cf7be132df37bcc274a1e5720b4605d2dd95f3a29168"
+  folder = on_arch_conditional arm: "aarch64", intel: "x86_64"
 
-  livecheck do
+  version "7.6.0"
-    skip "Legacy version"
+  sha256 arm:   "81eab945a33622fc156951e804024d23aa9a745c06743b4947215ed9303ad1c4",
-  end
+         intel: "ede541af151487f60eb518e310d20dad1a973f3dbe9ff78d782dd29b14ba2946"
-end
-on_mojave do
-  # ...
-end
-on_catalina do
-  # ...
-end
-on_big_sur :or_newer do
-  version "6.25.0"
-  sha256 "a7ed19ae0526630ccb138b9afee6dc5169904180b02f7a3089e78d3e0022753b"
 
-  livecheck do
+  url "https://download.documentfoundation.org/libreoffice/stable/#{version}/mac/#{folder}/LibreOffice_#{version}_MacOS_#{arch}.dmg",
-    url "https://github.com/kovidgoyal/calibre"
+      verified: "download.documentfoundation.org/libreoffice/stable/"
-    strategy :github_latest
-  end
-end
 ```
 
-To adjust the URL depending on the current CPU architecture, use the special `arch` stanza to define the unique components of the respective URLs for substitution in the `url`, and locate the unique `version` and `sha256` stanzas within `on_arm` an `on_intel` blocks. Example (from [inkscape.rb](https://github.com/Homebrew/homebrew-cask/blob/11f6966bf17628b98895d64a61a4fb0bc1bb31bf/Casks/i/inkscape.rb#L2-L13)):
+If the version number is different for each architecture, locate the unique `version` and (if checked) `sha256` stanzas within `on_arm` and `on_intel` blocks. Example (from [inkscape.rb](https://github.com/Homebrew/homebrew-cask/blob/11f6966bf17628b98895d64a61a4fb0bc1bb31bf/Casks/i/inkscape.rb#L1-L13)):
 
 ```ruby
-arch arm: "arm64", intel: "x86_64"
+cask "inkscape" do
+  arch arm: "arm64", intel: "x86_64"
 
-on_arm do
+  on_arm do
-  version "1.3.0,42339"
+    version "1.3.0,42339"
-  sha256 "e37b5f8b8995a0ecc41ca7fcae90d79bcd652b7a25d2f6e52c4e2e79aef7fec1"
+    sha256 "e37b5f8b8995a0ecc41ca7fcae90d79bcd652b7a25d2f6e52c4e2e79aef7fec1"
-end
+  end
-on_intel do
+  on_intel do
-  version "1.3.0,42338"
+    version "1.3.0,42338"
-  sha256 "e97de6804d8811dd2f1bc45d709d87fb6fe45963aae710c24a4ed655ecd8eb8a"
+    sha256 "e97de6804d8811dd2f1bc45d709d87fb6fe45963aae710c24a4ed655ecd8eb8a"
-end
+  end
 
-url "https://inkscape.org/gallery/item/#{version.csv.second}/Inkscape-#{version.csv.first}_#{arch}.dmg"
+  url "https://inkscape.org/gallery/item/#{version.csv.second}/Inkscape-#{version.csv.first}_#{arch}.dmg"
 ```
 
-More complex URL adjustments can be done by calling `on_arch_conditional` directly. (Example: [paraview.rb](https://github.com/Homebrew/homebrew-cask/blob/aa461148bbb5119af26b82cccf5003e2b4e50d95/Casks/p/paraview.rb#L2-L10))
+To adjust the installed version depending on the current macOS release, use a series of `on_<system>` blocks that cover the range of supported releases. Each block can contain stanzas that set which version to download and customize installation/uninstallation and livecheck behaviour for one or more releases. Example (from [calibre.rb](https://github.com/Homebrew/homebrew-cask/blob/482c34e950da8d649705f4aaea7b760dcb4b5402/Casks/c/calibre.rb#L1-L34)):
+
+```ruby
+cask "calibre" do
+  on_high_sierra :or_older do
+    version "3.48.0"
+    sha256 "68829cd902b8e0b2b7d5cf7be132df37bcc274a1e5720b4605d2dd95f3a29168"
+
+    livecheck do
+      skip "Legacy version"
+    end
+  end
+  on_mojave do
+    # ...
+  end
+  on_catalina do
+    # ...
+  end
+  on_big_sur :or_newer do
+    version "6.25.0"
+    sha256 "a7ed19ae0526630ccb138b9afee6dc5169904180b02f7a3089e78d3e0022753b"
+
+    livecheck do
+      url "https://github.com/kovidgoyal/calibre"
+      strategy :github_latest
+    end
+  end
+```
+
+Such `on_<system>` blocks can be nested and contain other stanzas not listed here. Examples: [calhash.rb](https://github.com/Homebrew/homebrew-cask/blob/HEAD/Casks/c/calhash.rb), [openzfs.rb](https://github.com/Homebrew/homebrew-cask/blob/HEAD/Casks/o/openzfs.rb), [r.rb](https://github.com/Homebrew/homebrew-cask/blob/HEAD/Casks/r/r.rb), [wireshark.rb](https://github.com/Homebrew/homebrew-cask/blob/HEAD/Casks/w/wireshark.rb)
 
 ### Switch Between Languages or Regions
 

docs/FAQ.md

@@ -88,16 +88,6 @@ If available, bottled binaries will be used by default except under the followin
 
 We aim to bottle everything.
 
-## How do I get a formula from someone else’s pull request?
-
-```sh
-brew install hub
-brew update
-cd "$(brew --repository homebrew/core)"
-hub fetch github_username
-hub pr checkout pull_request_number
-```
-
 ## Why should I install Homebrew in the default location?
 
 Homebrew's pre-built binary packages (known as [bottles](Bottles.md)) of many formulae can only be used if you install in the default installation prefix, otherwise they have to be built from source. Building from source takes a long time, is prone to failure, and is not supported. The default prefix is:
@@ -158,6 +148,18 @@ Yes! It’s easy! If you already have a local copy of `homebrew/core` (see above
 
 If you want your new formula to be part of `homebrew/core` or want to learn more about writing formulae, then please read the [Formula Cookbook](Formula-Cookbook.md).
 
+## How do I get a formula from someone else’s pull request?
+
+Ensure you have a [local copy of `homebrew/core`](#can-i-edit-formulae-myself), then:
+
+```sh
+brew update
+brew install hub
+cd "$(brew --repository homebrew/core)"
+hub fetch github_username
+hub pr checkout pull_request_number
+```
+
 ## Why was a formula deleted or disabled?
 
 Use `brew log <formula>` to find out! Likely because it had [unresolved issues](Acceptable-Formulae.md) and/or [our analytics](https://formulae.brew.sh/analytics/) indicated it was not widely used.

docs/Formula-Cookbook.md

@@ -9,8 +9,8 @@ A *formula* is a package definition written in Ruby. It can be created with `bre
 
 | term                 | description                                                               | example |
 | -------------------- | ------------------------------------------------------------------------- | ------- |
-| **formula**          | Homebrew package definition that builds from upstream sources             | `/usr/local/Homebrew/Library/Taps/homebrew/homebrew-core/Formula/foo.rb`
+| **formula**          | Homebrew package definition that builds from upstream sources             | `/usr/local/Homebrew/Library/Taps/homebrew/homebrew-core/Formula/f/foo.rb`
-| **cask**             | Homebrew package definition that installs macOS native applications       | `/usr/local/Homebrew/Library/Taps/homebrew/homebrew-cask/Casks/bar.rb`
+| **cask**             | Homebrew package definition that installs macOS native applications       | `/usr/local/Homebrew/Library/Taps/homebrew/homebrew-cask/Casks/b/bar.rb`
 | **prefix**           | path in which Homebrew is installed                                       | `/usr/local`
 | **keg**              | installation destination directory of a given **formula** version         | `/usr/local/Cellar/foo/0.1`
 | **rack**             | directory containing one or more versioned **kegs**                       | `/usr/local/Cellar/foo`
@@ -21,6 +21,7 @@ A *formula* is a package definition written in Ruby. It can be created with `bre
 | **external command** | `brew` subcommand defined outside of the Homebrew/brew GitHub repository  | [`brew alias`](https://github.com/Homebrew/homebrew-aliases)
 | **tap**              | directory (and usually Git repository) of **formulae**, **casks** and/or **external commands**       | `/usr/local/Homebrew/Library/Taps/homebrew/homebrew-core`
 | **bottle**           | pre-built **keg** poured into a **rack** of the **Cellar** instead of building from upstream sources | `qt--6.5.1.ventura.bottle.tar.gz`
+| **tab**              | information about a **keg**, e.g. whether it was poured from a **bottle** or built from source       | `/usr/local/Cellar/foo/0.1/INSTALL_RECEIPT.json`
 | **Brew Bundle**      | an [extension of Homebrew](https://github.com/Homebrew/homebrew-bundle) to describe dependencies     | `brew 'myservice', restart_service: true`
 | **Brew Services**    | an [extension of Homebrew](https://github.com/Homebrew/homebrew-services) to manage services         | `brew services start myservice`
 
@@ -28,7 +29,7 @@ A *formula* is a package definition written in Ruby. It can be created with `bre
 
 Homebrew uses Git for storing formulae and contributing to the project.
 
-As of [Homebrew 4.0.0](https://brew.sh/2023/02/16/homebrew-4.0.0/), formulae are downloaded as JSON from <https://formulae.brew.sh> which is automatically regenerated by a scheduled [Homebrew/formulae.brew.sh](https://github.com/Homebrew/formulae.brew.sh) job from the `master` branch of the `homebrew/core` repository.
+As of [Homebrew 4.0.0](https://brew.sh/2023/02/16/homebrew-4.0.0/), formulae are downloaded as JSON from <https://formulae.brew.sh> which is automatically regenerated by a scheduled [Homebrew/formulae.brew.sh](https://github.com/Homebrew/formulae.brew.sh) job from the `master` branch of the Homebrew/homebrew-core repository.
 
 Homebrew installs formulae to the Cellar at `$(brew --cellar)` and then symlinks some of the installation into the prefix at `$(brew --prefix)` (e.g. `/opt/homebrew`) so that other programs can see what's going on. We suggest running `brew ls` on a few of the kegs in your Cellar to see how it is all arranged.
 
@@ -38,7 +39,7 @@ Packages are installed according to their formulae. Read over a simple one, e.g.
 
 Make sure you run `brew update` before you start. This ensures your Homebrew installation is a Git repository.
 
-To create or edit formulae locally, you'll need to `brew tap --force homebrew/core` if you haven't previously. This clones the `homebrew/core` Git repository to `$(brew --repository homebrew/core)`. As you are developing, you'll also need to set `HOMEBREW_NO_INSTALL_FROM_API=1` before any `install`, `reinstall` or `upgrade` commands, to force `brew` to use the local repository instead of the API.
+To create or edit formulae locally, you'll need to first [tap `homebrew/core`](https://docs.brew.sh/FAQ#can-i-edit-formulae-myself) if you haven't previously. This clones the Homebrew/homebrew-core Git repository to `$(brew --repository homebrew/core)`. As you're developing, you'll also need to set `HOMEBREW_NO_INSTALL_FROM_API=1` in your shell environment or before any `install`, `reinstall` or `upgrade` commands to force `brew` to use the local repository instead of the API.
 
 Before submitting a new formula make sure your package:
 
@@ -59,7 +60,7 @@ Run `brew create` with a URL to the source tarball:
 brew create https://example.com/foo-0.1.tar.gz
 ```
 
-This creates `$(brew --repository)/Library/Taps/homebrew/homebrew-core/Formula/foo.rb` and opens it in your `EDITOR`. If run without any options to customize the output for specific build systems (check `brew create --help` to see which are available) it'll look something like:
+This creates `$(brew --repository)/Library/Taps/homebrew/homebrew-core/Formula/f/foo.rb` and opens it in your `EDITOR`. If run without any options to customize the output for specific build systems (check `brew create --help` to see which are available) it'll look something like:
 
 ```ruby
 class Foo < Formula
@@ -171,6 +172,8 @@ A `Hash` (e.g. `=>`) adds information to a dependency. Given a string or symbol,
   depends_on "foo" => :optional # Generated description would otherwise be "Build with foo support"
   ```
 
+* `"<option-name>"` (not allowed in `Homebrew/homebrew-core`) requires a dependency to have been built with the specified option.
+
 ### Specifying conflicts with other formulae
 
 Sometimes there’s a hard conflict between formulae that can’t be avoided or circumvented with [`keg_only`](https://rubydoc.brew.sh/Formula#keg_only-class_method).
@@ -372,12 +375,12 @@ Use `brew info` and check if the version guessed by Homebrew from the URL is cor
 Everything is built on Git, so contribution is easy:
 
 ```sh
-brew update # required in more ways than you think (initialises the brew git repository if you don't already have it)
+brew update # required in more ways than you think (initialises the Homebrew/brew Git repository if you don't already have it)
 cd "$(brew --repository homebrew/core)"
 # Create a new git branch for your formula so your pull request is easy to
 # modify if any changes come up during review.
 git checkout -b <some-descriptive-name> origin/master
-git add Formula/foo.rb
+git add Formula/f/foo.rb
 git commit
 ```
 
@@ -399,7 +402,7 @@ Ensure you reference any relevant GitHub issue, e.g. `Closes #12345` in the comm
 
 Now you just need to push your commit to GitHub.
 
-If you haven’t forked Homebrew yet, [go to the `homebrew/core` repository and hit the Fork button](https://github.com/Homebrew/homebrew-core).
+If you haven’t forked Homebrew yet, [go to the Homebrew/homebrew-core repository and hit the Fork button](https://github.com/Homebrew/homebrew-core).
 
 If you have already forked Homebrew on GitHub, then you can manually push (just make sure you have been pulling from the `Homebrew/homebrew-core` master):
 
@@ -554,7 +557,7 @@ Instead of `git diff | pbcopy`, for some editors `git diff >> path/to/your/formu
 
 ## Advanced formula tricks
 
-If anything isn’t clear, you can usually figure it out by `grep`ping the `$(brew --repository homebrew/core)` directory for examples. Please submit a pull request to amend this document if you think it will help!
+See the [Formula API](https://rubydoc.brew.sh/Formula) for the full list of methods available within a formula. If anything isn’t clear, you can usually figure it out by `grep`ping the `$(brew --repository homebrew/core)` directory for examples. Please submit a pull request to amend this document if you think it will help!
 
 ### Handling different system configurations
 
@@ -661,7 +664,7 @@ class Nginx < Formula
   head "https://hg.nginx.org/nginx/", using: :hg
 ```
 
-Homebrew offers anonymous download strategies.
+Homebrew offers these anonymous download strategies.
 
 | `:using` value   | download strategy             |
 | ---------------- | ----------------------------- |
@@ -853,7 +856,8 @@ class Yourformula < Formula
   option "with-ham", "Description of the option"
   option "without-spam", "Another description"
 
-  depends_on "foo" => :optional  # will automatically add a with-foo option
+  depends_on "foo" => :optional  # automatically adds a with-foo option
+  depends_on "bar" => :recommended  # automatically adds a without-bar option
   ...
 ```
 
@@ -871,7 +875,20 @@ end
 
 [`option`](https://rubydoc.brew.sh/Formula#option-class_method) names should be prefixed with the words `with` or `without`. For example, an option to run a test suite should be named `--with-test` or `--with-check` rather than `--test`, and an option to enable a shared library `--with-shared` rather than `--shared` or `--enable-shared`. See the [alternative `ffmpeg`](https://github.com/homebrew-ffmpeg/homebrew-ffmpeg/blob/HEAD/Formula/ffmpeg.rb) formula for examples.
 
-[`option`](https://rubydoc.brew.sh/Formula#option-class_method)s that aren’t `build.with?` or `build.without?` should be deprecated with [`deprecated_option`](https://rubydoc.brew.sh/Formula#deprecated_option-class_method). See the [`wget`](https://github.com/Homebrew/homebrew-core/blob/3f762b63c6fbbd49191ffdf58574d7e18937d93f/Formula/wget.rb#L27-L31) formula for an example.
+[`option`](https://rubydoc.brew.sh/Formula#option-class_method)s that aren’t `build.with?` or `build.without?` should be deprecated with [`deprecated_option`](https://rubydoc.brew.sh/Formula#deprecated_option-class_method). See the [`wget`](https://github.com/Homebrew/homebrew-core/blob/3f762b63c6fbbd49191ffdf58574d7e18937d93f/Formula/wget.rb#L27-L31) formula for a historical example.
+
+### Running commands after installation
+
+Any initialization steps that aren't necessarily part of the install process can be located in a `post_install` block, such as setup commands or data directory creation. This block can be re-run separately with `brew postinstall <formula>`.
+
+```ruby
+def post_install
+  rm_f pkgetc/"cert.pem"
+  pkgetc.install_symlink Formula["ca-certificates"].pkgetc/"cert.pem"
+end
+```
+
+In the above example, the [`libressl`](https://github.com/Homebrew/homebrew-core/blob/442f9cc511ce6dfe75b96b2c83749d90dde914d2/Formula/lib/libressl.rb#L53-L56) formula replaces its stock list of certificates with a symlink to that of the `ca-certificates` formula.
 
 ### Handling files that should persist over formula upgrades
 

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

@@ -1,8 +1,8 @@
 # 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.
+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") for the changes in that branch.
 
-The type of change you want to make influences which of Homebrew's main repositories you'll need to send your pull request to. If you want to submit a change to Homebrew's core code (the `brew` implementation), you should open a pull request on [Homebrew/brew](https://github.com/Homebrew/brew). If you want to submit a change for a formula, you should open a pull request on the [homebrew/core](https://github.com/Homebrew/homebrew-core) tap, while for casks you should open the pull request on the [homebrew/cask](https://github.com/Homebrew/homebrew-cask) tap or another [official tap](https://github.com/Homebrew), based on the formula type.
+The type of change you want to make influences which of Homebrew's main repositories you'll need to send your pull request to. If you want to submit a change to Homebrew's core code (the `brew` implementation), you should open a pull request on [Homebrew/brew](https://github.com/Homebrew/brew). If you want to submit a change for a formula, you should open a pull request on the [homebrew/core](https://github.com/Homebrew/homebrew-core) tap, while for casks you should open the pull request on the [homebrew/cask](https://github.com/Homebrew/homebrew-cask) tap or another [official tap](https://github.com/Homebrew), depending on the formula type.
 
 ## Submit a new version of an existing formula
 
@@ -14,7 +14,7 @@ The type of change you want to make influences which of Homebrew's main reposito
 
 ## Set up your own fork of the Homebrew repository
 
-### Core `brew` code related pull request
+### Core `brew` code pull request
 
 1. [Fork the Homebrew/brew repository on GitHub](https://github.com/Homebrew/brew/fork).
    * This creates a personal remote repository that you can push to. This is needed because only Homebrew maintainers have push access to the main repositories.
@@ -32,7 +32,7 @@ The type of change you want to make influences which of Homebrew's main reposito
 
    * `<YOUR_USERNAME>` is your GitHub username, not your local machine username.
 
-### Formulae related pull request
+### Formulae-related pull request
 
 1. [Fork the Homebrew/homebrew-core repository on GitHub](https://github.com/Homebrew/homebrew-core/fork).
    * This creates a personal remote repository that you can push to. This is needed because only Homebrew maintainers have push access to the main repositories.
@@ -56,7 +56,7 @@ The type of change you want to make influences which of Homebrew's main reposito
 
    * `<YOUR_USERNAME>` is your GitHub username, not your local machine username.
 
-### Cask related pull request
+### Cask-related pull request
 
 1. [Fork the Homebrew/homebrew-cask repository on GitHub](https://github.com/Homebrew/homebrew-cask/fork).
    * This creates a personal remote repository that you can push to. This is needed because only Homebrew maintainers have push access to the main repositories.

docs/Installation.md

@@ -84,7 +84,7 @@ Create a Homebrew installation wherever you extract the tarball. Whichever `brew
 
 ## Uninstallation
 
-Uninstallation is documented in the [FAQ](FAQ.md).
+Uninstallation is documented in the [FAQ](FAQ.md#how-do-i-uninstall-homebrew).
 
 <a data-proofer-ignore name="1"><sup>1</sup></a> For 32-bit or PPC support see [Tigerbrew](https://github.com/mistydemeo/tigerbrew).
 

docs/Tips-N'-Tricks.md

@@ -65,8 +65,32 @@ The beer emoji can also be replaced with other character(s):
 export HOMEBREW_INSTALL_BADGE="☕️ 🐸"
 ```
 
+## Migrate a Homebrew installation to a new location
+
+Run `brew bundle dump` and `brew bundle install` record an installation to and install from a `Brewfile`. See `brew bundle --help` for more details.
+
+## Appoint Homebrew Cask to manage a manually-installed app
+
+Run `brew install --cask` with the `--adopt` switch:
+
+```console
+$ brew install --cask --adopt textmate
+==> Downloading https://github.com/textmate/textmate/releases/download/v2.0.23/TextMate_2.0.23.tbz
+...
+==> Installing Cask textmate
+==> Adopting existing App at '/Applications/TextMate.app'
+==> Linking Binary 'mate' to '/opt/homebrew/bin/mate'
+🍺  textmate was successfully installed!
+```
+
 ## Editor plugins
 
+### Visual Studio Code
+
+- [Brewfile](https://marketplace.visualstudio.com/items?itemName=sharat.vscode-brewfile) adds Ruby syntax highlighting for [Homebrew Bundle](https://github.com/Homebrew/homebrew-bundle) `Brewfile`s.
+
+- [Brew Services](https://marketplace.visualstudio.com/items?itemName=beauallison.brew-services) is an extension for starting and stopping Homebrew services.
+
 ### Sublime Text
 
 - [Homebrew-formula-syntax](https://github.com/samueljohn/Homebrew-formula-syntax) can be installed with Package Control in Sublime Text 2/3, which adds highlighting for inline patches.

docs/Troubleshooting.md

@@ -26,6 +26,6 @@ If your problem hasn't been solved or reported, then create an issue:
   * If your have a non-formula problem: collect the output of `brew config` and `brew doctor`.
 
 1. Create a new issue on the issue tracker for [Homebrew/homebrew-core](https://github.com/Homebrew/homebrew-core/issues/new/choose), [Homebrew/homebrew-cask](https://github.com/Homebrew/homebrew-cask/issues/new/choose) or [Homebrew/brew](https://github.com/Homebrew/brew/issues/new/choose) and follow the instructions:
-  * Give your issue a descriptive title which includes the formula name (if applicable) and the version of macOS or Linux you are using. For example, if a formula fails to build, title your issue "\<formula> failed to build on \<platform>", where "\<formula>" is the name of the formula that failed to build, and "\<platform>" is the name and version of macOS or Linux you are using.
+  * Give your issue a descriptive title which includes the formula name (if applicable) and the version of macOS or Linux you are using. For example, if a formula fails to build, title your issue "\<formula> failed to build on \<platform>", where *\<formula>* is the name of the formula that failed to build, and *\<platform>* is the name and version of macOS or Linux you are using.
   * Include the URL provided by `brew gist-logs <formula>` (if applicable) plus links to any additional Gists you may have created.
   * Include the output of `brew config` and `brew doctor`.