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. `TexmakerMacosxLion.zip` unzips to a folder called `TexmakerMacosxLion`.
-1. The folder `TexmakerMacosxLion` contains the application `texmaker.app`.
+1. Simple Floating Clock is downloaded to the file `sfc.zip`.
+1. `sfc.zip` unzips to a folder called `Simple Floating Clock`.
+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
-  version "3.48.0"
-  sha256 "68829cd902b8e0b2b7d5cf7be132df37bcc274a1e5720b4605d2dd95f3a29168"
+cask "libreoffice" do
+  arch arm: "aarch64", intel: "x86-64"
+  folder = on_arch_conditional arm: "aarch64", intel: "x86_64"
 
-  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"
+  version "7.6.0"
+  sha256 arm:   "81eab945a33622fc156951e804024d23aa9a745c06743b4947215ed9303ad1c4",
+         intel: "ede541af151487f60eb518e310d20dad1a973f3dbe9ff78d782dd29b14ba2946"
 
-  livecheck do
-    url "https://github.com/kovidgoyal/calibre"
-    strategy :github_latest
+  url "https://download.documentfoundation.org/libreoffice/stable/#{version}/mac/#{folder}/LibreOffice_#{version}_MacOS_#{arch}.dmg",
+      verified: "download.documentfoundation.org/libreoffice/stable/"
+```
+
+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
+cask "inkscape" do
+  arch arm: "arm64", intel: "x86_64"
+
+  on_arm do
+    version "1.3.0,42339"
+    sha256 "e37b5f8b8995a0ecc41ca7fcae90d79bcd652b7a25d2f6e52c4e2e79aef7fec1"
   end
-end
+  on_intel do
+    version "1.3.0,42338"
+    sha256 "e97de6804d8811dd2f1bc45d709d87fb6fe45963aae710c24a4ed655ecd8eb8a"
+  end
+
+  url "https://inkscape.org/gallery/item/#{version.csv.second}/Inkscape-#{version.csv.first}_#{arch}.dmg"
 ```
 
-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)):
+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
-arch arm: "arm64", intel: "x86_64"
+cask "calibre" do
+  on_high_sierra :or_older do
+    version "3.48.0"
+    sha256 "68829cd902b8e0b2b7d5cf7be132df37bcc274a1e5720b4605d2dd95f3a29168"
 
-on_arm do
-  version "1.3.0,42339"
-  sha256 "e37b5f8b8995a0ecc41ca7fcae90d79bcd652b7a25d2f6e52c4e2e79aef7fec1"
-end
-on_intel do
-  version "1.3.0,42338"
-  sha256 "e97de6804d8811dd2f1bc45d709d87fb6fe45963aae710c24a4ed655ecd8eb8a"
-end
+    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"
 
-url "https://inkscape.org/gallery/item/#{version.csv.second}/Inkscape-#{version.csv.first}_#{arch}.dmg"
+    livecheck do
+      url "https://github.com/kovidgoyal/calibre"
+      strategy :github_latest
+    end
+  end
 ```
 
-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))
+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