Merge pull request #19209 from Homebrew/docs-prefix-priority

docs: prefer `/opt/homebrew` in examples

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

@@ -40,31 +40,31 @@ Linux distribution without requiring `sudo`.
 
 **prefix**
 
-: path in which Homebrew is installed, e.g. `/usr/local`
+: path in which Homebrew is installed, e.g. `/opt/homebrew` or `/home/linuxbrew/.linuxbrew`
 
 **keg**
 
-: installation destination directory of a given **formula** version, e.g. `/usr/local/Cellar/foo/0.1`
+: installation destination directory of a given **formula** version, e.g. `/opt/homebrew/Cellar/foo/0.1`
 
 **rack**
 
-: directory containing one or more versioned **kegs**, e.g. `/usr/local/Cellar/foo`
+: directory containing one or more versioned **kegs**, e.g. `/opt/homebrew/Cellar/foo`
 
 **keg-only**
 
 : a **formula** is *keg-only* if it is not symlinked into Homebrew's prefix
 
 **opt prefix**
 
-: a symlink to the active version of a **keg**, e.g. `/usr/local/opt/foo`
+: a symlink to the active version of a **keg**, e.g. `/opt/homebrew/opt/foo`
 
 **Cellar**
 
-: directory containing one or more named **racks**, e.g. `/usr/local/Cellar`
+: directory containing one or more named **racks**, e.g. `/opt/homebrew/Cellar`
 
 **Caskroom**
 
-: directory containing one or more named **casks**, e.g. `/usr/local/Caskroom`
+: directory containing one or more named **casks**, e.g. `/opt/homebrew/Caskroom`
 
 **external command**
 

docs/Acceptable-Casks.md

@@ -106,7 +106,7 @@ Before submitting a cask to any of our repositories, you must read our [document
 
 Common reasons to reject a cask entirely:
 
-* App fails with GateKeeper enabled on Homebrew supported macOS versions and platforms (e.g. unsigned apps fail on Macs with Apple Silicon/ARM).
+* App fails with GateKeeper enabled on Homebrew supported macOS versions and platforms (e.g. unsigned apps will not launch on Apple Silicon Macs).
 * App is too obscure. Examples:
   * An app from a code repository that is not notable enough (under 30 forks, 30 watchers, 75 stars).
   * [Electronic Identification (eID) software](https://github.com/Homebrew/homebrew-cask/issues/59021).

docs/Acceptable-Formulae.md

@@ -13,7 +13,7 @@ Some formulae should not go in [homebrew/core](https://github.com/Homebrew/homeb
 
 ### Supported platforms
 
-The formula needs to build and pass tests on the latest 3 supported macOS versions ([x86_64 and Apple Silicon/ARM](Installation.md#macos-requirements)) and on x86_64 [Linux](Linux-CI.md). Please have a look at the continuous integration jobs on a pull request in `homebrew/core` to see the full list of OSs. If upstream does not support one of these platforms, an exception can be made and the formula can be disabled for that platform.
+The formula needs to build and pass tests on the latest 3 supported macOS versions ([Apple Silicon and x86_64](Installation.md#macos-requirements)) and on x86_64 [Linux](Linux-CI.md). Please have a look at the continuous integration jobs on a pull request in `homebrew/core` to see the full list of OSs. If upstream does not support one of these platforms, an exception can be made and the formula can be disabled for that platform.
 
 ### Duplicates of system packages
 

docs/Cask-Cookbook.md

@@ -129,7 +129,7 @@ Each cask must declare one or more *artifacts* (i.e. something to install).
 | [`pkg`](#stanza-pkg)             | yes                           | Relative path to a `.pkg` file containing the distribution. |
 | [`installer`](#stanza-installer) | yes                           | Describes an executable which must be run to complete the installation. |
 | [`binary`](#stanza-binary)       | yes                           | Relative path to a Binary that should be linked into the `$(brew --prefix)/bin` folder on installation. |
-| `manpage`                        | yes                           | Relative path to a Man Page that should be linked into the respective man page folder on installation, e.g. `/usr/local/share/man/man3` for `my_app.3`. |
+| `manpage`                        | yes                           | Relative path to a Man Page that should be linked into the respective man page folder on installation, e.g. `/opt/homebrew/share/man/man3` for `my_app.3`. |
 | `colorpicker`                    | yes                           | Relative path to a ColorPicker plugin that should be moved into the `~/Library/ColorPickers` folder on installation. |
 | `dictionary`                     | yes                           | Relative path to a Dictionary that should be moved into the `~/Library/Dictionaries` folder on installation. |
 | `font`                           | yes                           | Relative path to a Font that should be moved into the `~/Library/Fonts` folder on installation. |
@@ -417,17 +417,17 @@ The available symbols for hardware are:
 
 | symbol     | meaning        |
 | ---------- | -------------- |
+| `:arm64`   | Apple Silicon |
 | `:x86_64`  | 64-bit Intel |
 | `:intel`   | 64-bit Intel |
-| `:arm64`   | Apple Silicon |
 
 The following are all valid expressions:
 
 ```ruby
+depends_on arch: :arm64
 depends_on arch: :intel
 depends_on arch: :x86_64            # same meaning as above
 depends_on arch: [:x86_64]          # same meaning as above
-depends_on arch: :arm64
 ```
 
 #### `depends_on` parameters
@@ -1182,7 +1182,7 @@ If no additional files are discovered, instead of a zap stanza, include the foll
 
 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)):
+If your cask's artifact is offered as separate downloads for Apple Silicon and Intel 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
 cask "libreoffice" do

docs/Common-Issues.md

@@ -127,7 +127,7 @@ This is an issue in the connection between your machine and GitHub, rather than
 
 Upgrading macOS can cause errors like the following:
 
-* `dyld: Library not loaded: /usr/local/opt/icu4c/lib/libicui18n.54.dylib`
+* `dyld: Library not loaded: /opt/homebrew/opt/icu4c/lib/libicui18n.76.dylib`
 * `configure: error: Cannot find libz`
 
 Following a macOS upgrade it may be necessary to reinstall the Xcode Command Line Tools and then `brew upgrade` all installed formulae:

docs/External-Commands.md

@@ -33,7 +33,7 @@ An executable script for a command named `extcmd` should be named `brew-extcmd`.
 | variable               | description |
 | ---------------------- | ----------- |
 | `HOMEBREW_CACHE`       | Where Homebrew caches downloaded tarballs to, by default `~/Library/Caches/Homebrew`. |
-| `HOMEBREW_PREFIX`      | Where Homebrew installs software. `/usr/local` by default for macOS Intel, `/opt/homebrew` for Apple Silicon and `/home/linuxbrew/.linuxbrew` for Linux. |
+| `HOMEBREW_PREFIX`      | Where Homebrew installs software. `/opt/homebrew` by default for Apple Silicon, `/usr/local` for macOS Intel and `/home/linuxbrew/.linuxbrew` for Linux. |
 | `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_REPOSITORY`  | The Git repository directory (i.e. where Homebrew’s `.git` directory lives). Usually either the same as `HOMEBREW_PREFIX` or a `Homebrew` subdirectory. |

docs/FAQ.md

@@ -96,8 +96,8 @@ We aim to bottle everything.
 
 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:
 
-* `/usr/local` for macOS on Intel,
-* `/opt/homebrew` for macOS on Apple Silicon/ARM, and
+* `/opt/homebrew` for macOS on Apple Silicon,
+* `/usr/local` for macOS on Intel, and
 * `/home/linuxbrew/.linuxbrew` for Linux.
 
 Do yourself a favour and install to the default prefix so that you can use our pre-built binary packages. *Pick another prefix at your peril!*