docs: assume core repositories are untapped

Library/Homebrew/tap.rb

@@ -321,7 +321,7 @@ class Tap
     elsif (core_tap? || core_cask_tap?) && !Homebrew::EnvConfig.no_install_from_api? && !force
       # odeprecated: move to odie in the next minor release. This may break some CI so we should give notice.
       opoo "Tapping #{name} is no longer typically necessary.\n" \
-           "Add #{Formatter.option("--force")} if you are sure you need one."
+           "Add #{Formatter.option("--force")} if you are sure you need it done."
     end
 
     clear_cache

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 running `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/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.
 
 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/Adding-Software-to-Homebrew.md

@@ -14,7 +14,7 @@ If everything checks out, you're ready to get started on a new formula!
 
 ### Writing the formula
 
-1. It's a good idea to find existing formulae in Homebrew that have similarities to the software you want to add. This will help you to understand how specific languages, build methods, etc. are typically handled.
+1. It's a good idea to find existing formulae in Homebrew that have similarities to the software you want to add. This will help you to understand how specific languages, build methods, etc. are typically handled. Start by tapping `homebrew/core`: first set `HOMEBREW_NO_INSTALL_FROM_API=1` in your shell environment, then run `brew tap homebrew/core` to clone the `homebrew/core` tap to the path returned by `brew --repository homebrew/core`.
 
 1. If you're starting from scratch, you can use the [`brew create` command](Manpage.md#create-options-url) to produce a basic version of your formula. This command accepts a number of options and you may be able to save yourself some work by using an appropriate template option like `--python`.
 

docs/FAQ.md

@@ -140,7 +140,13 @@ If all maintainer feedback has been addressed and all tests are passing, bump it
 
 ## Can I edit formulae myself?
 
-Yes! It’s easy! If `brew tap` doesn't show `homebrew/core`, run `brew tap homebrew/core` first. Then just `brew edit <formula>`. You don’t have to submit modifications back to `homebrew/core`, just edit the formula to what you personally need and `brew install <formula>`. As a bonus, `brew update` will merge your changes with upstream so you can still keep the formula up-to-date **with** your personal modifications!
+Yes! It’s easy! If `brew tap` doesn't show `homebrew/core`, set yourself up to edit a local copy:
+
+1. Set `HOMEBREW_NO_INSTALL_FROM_API=1` in your shell environment,
+2. Run `brew tap homebrew/core` and wait for the clone to complete, then
+3. Run `brew edit <formula>` to open the formula in `EDITOR`.
+
+You don’t have to submit modifications back to `homebrew/core`, just edit the formula to what you personally need and `brew install <formula>`. As a bonus, `brew update` will merge your changes with upstream so you can still keep the formula up-to-date **with** your personal modifications!
 
 Note that if you are editing a core formula or cask you must set `HOMEBREW_NO_INSTALL_FROM_API=1` before using `brew install` or `brew update` otherwise they will ignore your local changes and default to the API.
 
@@ -148,7 +154,7 @@ To undo all changes you have made to any of Homebrew's repositories, run `brew u
 
 ## Can I make new formulae?
 
-Yes! It’s easy! Just `brew create URL`. Homebrew will then open the formula in `EDITOR` so you can edit it, but it probably already installs; try it: `brew install <formula>`. If you encounter any issues, run the command with the `--debug` switch like so: `brew install --debug <formula>`, which drops you into a debugging shell.
+Yes! It’s easy! If you already have a local copy of `homebrew/core` (see above), just use the [`brew create` command](Manpage.md#create-options-url). Homebrew will then open the formula in `EDITOR` so you can edit it, but it probably already installs; try it: `brew install <formula>`. If you encounter any issues, run the command with the `--debug` switch like so: `brew install --debug <formula>`, which drops you into a debugging shell.
 
 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).
 

docs/Formula-Cookbook.md

@@ -23,7 +23,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 from JSON in <https://formulae.brew.sh> which is automatically regenerated by a scheduled 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/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.
 
@@ -33,7 +33,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 homebrew/core` if you haven't previously. This taps homebrew-core, creating a Git repository in `$(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 `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.
 
 Before submitting a new formula make sure your package:
 

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

@@ -36,7 +36,7 @@ The type of change you want to make influences which of Homebrew's main reposito
 
 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.
-2. Download a local clone ("tap") the repository of core Homebrew formulae:
+2. Tap (download a local clone of) the repository of core Homebrew formulae:
 
    ```sh
    brew tap --force homebrew/core
@@ -60,7 +60,7 @@ The type of change you want to make influences which of Homebrew's main reposito
 
 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.
-2. Download a local clone ("tap") the repository of core Homebrew casks:
+2. Tap (download a local clone of) the repository of core Homebrew casks:
 
    ```sh
    brew tap --force homebrew/cask
@@ -108,7 +108,7 @@ To make changes on a new branch and submit it for review, create a GitHub pull r
 
    ```sh
    brew tests
-   brew install --build-from-source <CHANGED_FORMULA|CHANGED_CASK>
+   HOMEBREW_NO_INSTALL_FROM_API=1 brew install --build-from-source <CHANGED_FORMULA|CHANGED_CASK>
    brew test <CHANGED_FORMULA|CHANGED_CASK>
    brew audit --strict --online <CHANGED_FORMULA|CHANGED_CASK>
    ```

docs/Installation.md

@@ -36,7 +36,7 @@ export HOMEBREW_NO_INSTALL_FROM_API=1
 
 This will make Homebrew install formulae and casks from the `homebrew/core` and `homebrew/cask` taps using local checkouts of these repositories instead of Homebrew’s API.
 
-Note, this will take effect in supported configurations (i.e. using the default Homebrew prefix and, if on macOS, on a supported version).
+Note that this will automatically be set on unsupported configurations (i.e. not using the default Homebrew prefix or, if on macOS, on an unsupported version).
 
 ## Unattended installation