From e1f76fe7a394dac52bfd60a8ed289560ae9c4992 Mon Sep 17 00:00:00 2001 From: Eric Knibbe Date: Mon, 11 Sep 2023 14:11:36 -0400 Subject: [PATCH] README & docs: update wording/style --- .github/ISSUE_TEMPLATE/config.yml | 2 +- CONTRIBUTING.md | 19 +++++++-------- README.md | 13 +++++----- USAGE.md | 40 +++++++++++++++---------------- 4 files changed, 37 insertions(+), 37 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml index 58e723a4ed8a2..e89a8ac4b9954 100644 --- a/.github/ISSUE_TEMPLATE/config.yml +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -12,4 +12,4 @@ contact_links: about: Having a Homebrew formula problem? Report it to Homebrew/homebrew-core (the formula tap/repository) - name: Ideas for a new feature url: https://docs.brew.sh/How-To-Open-a-Homebrew-Pull-Request - about: If you have an idea for a new feature here's how to add it to Brew + about: If you have an idea for a new feature, here's how to add it to Homebrew diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 115a866a2adfa..520959793037c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -5,13 +5,12 @@ * [Updating a Cask](#updating-a-cask) * [Getting Set Up To Contribute](#getting-set-up-to-contribute) * [Adding a Cask](#adding-a-cask) -* [Style guide](#style-guide) +* [Style Guide](#style-guide) * [Reporting Bugs](README.md#reporting-bugs) - ## Updating a Cask -Notice an application that's out-of-date in Homebrew Cask? In most cases, it's very simple to update it. We have a command that will take care of updating the Cask file and submitting a pull request to us: +Notice an application that's out-of-date in Homebrew Cask? In most cases, it's very simple to update it. We have a command that will take care of updating the cask file and submitting a pull request to us: ```bash brew bump --open-pr @@ -29,15 +28,15 @@ Notice an application that's not in Homebrew Cask yet? Make sure it's not yet in With a bit of work, you can create a cask for it. The documentation on [adding a cask](https://docs.brew.sh/Adding-Software-to-Homebrew#casks) will help you create, test, and submit a new cask to us. -## Style guide +## Style Guide Some style guidelines: -* All Casks and code should be indented using two spaces (never tabs). When `brew style` contradicts this, `style` must be followed. +* All casks and code should be indented using two spaces (never tabs). When `brew style` contradicts this, `style` must be followed. * There should not be any extraneous comments - the only comments that should be used are the ones explicitly defined in the [Cask Cookbook](https://docs.brew.sh/Cask-Cookbook). -* The stanza order and position of newlines is important to make things easier (See [Stanza order](https://docs.brew.sh/Cask-Cookbook#stanza-order)). -* Use string manipulations to improve the maintainability of your Cask (See [`version` methods](https://docs.brew.sh/Cask-Cookbook#version-methods)). -* Test your cask using `brew audit/style` (See [testing](https://docs.brew.sh/Adding-Software-to-Homebrew#testing-your-new-cask)). -* Make one Pull Request per Cask change. -* Do not squash commits after updating a Pull Request. +* The stanza order and position of newlines is important to make things easier (see [Stanza order](https://docs.brew.sh/Cask-Cookbook#stanza-order)). +* Use string manipulations to improve the maintainability of your cask (see [`version` methods](https://docs.brew.sh/Cask-Cookbook#version-methods)). +* Test your cask using `brew audit` and `brew style` (see the documentation on [testing and auditing](https://docs.brew.sh/Adding-Software-to-Homebrew#testing-and-auditing-the-cask)). +* Make one pull request per cask change. +* Do not squash commits after updating a pull request. * Use descriptive commit messages - mention cask name and version/change (ie. `transmission 2.82`, `google-chrome: update zap`). diff --git a/README.md b/README.md index 5bcc92bcd1416..6847887ee2844 100644 --- a/README.md +++ b/README.md @@ -34,7 +34,7 @@ And there we have it. An application installed with one quick command: no clicki * Want to contribute a cask? Awesome! See [CONTRIBUTING.md](CONTRIBUTING.md). * More project-related details and discussion are available in the [documentation](https://docs.brew.sh/Adding-Software-to-Homebrew#casks). -## Reporting bugs +## Reporting Bugs [**If you ignore this guide, your issue may be closed without review**](doc/faq/closing_issues_without_review.md) @@ -45,11 +45,11 @@ If your issue persists, [search for it](https://github.com/Homebrew/homebrew-cas If the issue is still not solved, see the guides for common problems: * [Examples of common errors and their solutions](doc/reporting_bugs/error_examples.md) -* [`curl` error](doc/reporting_bugs/error_examples.md#curl-error) -* [`Permission denied` error](doc/reporting_bugs/error_examples.md#permission-denied-error) -* [`Checksum does not match` error](doc/reporting_bugs/error_examples.md#checksum-does-not-match-error) -* [`source is not there` error](doc/reporting_bugs/error_examples.md#source-is-not-there-error) -* [`wrong number of arguments` error](doc/reporting_bugs/error_examples.md#wrong-number-of-arguments-error) + * [`curl` error](doc/reporting_bugs/error_examples.md#curl-error) + * [`Permission denied` error](doc/reporting_bugs/error_examples.md#permission-denied-error) + * [`Checksum does not match` error](doc/reporting_bugs/error_examples.md#checksum-does-not-match-error) + * [`source is not there` error](doc/reporting_bugs/error_examples.md#source-is-not-there-error) + * [`wrong number of arguments` error](doc/reporting_bugs/error_examples.md#wrong-number-of-arguments-error) * [App isn’t included in `upgrade`](https://docs.brew.sh/FAQ#why-arent-some-apps-included-during-brew-upgrade) * [The app can’t be opened because it is from an unidentified developer](https://docs.brew.sh/FAQ#why-cant-i-open-a-mac-app-from-an-unidentified-developer) * [My problem isn’t listed](https://github.com/Homebrew/homebrew-cask/issues/new?template=01_bug_report.yml) @@ -67,4 +67,5 @@ We’re really rather friendly! Here are the best places to talk about the proje * Join us on [GitHub discussions (forum)](https://github.com/orgs/Homebrew/discussions/categories/casks). ## License + Code is under the [BSD 2 Clause (NetBSD) license](LICENSE). diff --git a/USAGE.md b/USAGE.md index ce9351aad09ab..f7871478053ed 100644 --- a/USAGE.md +++ b/USAGE.md @@ -11,7 +11,7 @@ Homebrew Cask is implemented as part of [Homebrew](https://brew.sh). All Homebre ## Searching for Casks -To search for Casks, use `brew search`. Let’s see if there’s a Cask for Google Chrome: +To search for casks, use `brew search`. Let’s see if there’s a cask for Google Chrome: ```console $ brew search --cask google-chrome @@ -41,7 +41,7 @@ Easy peasy: $ brew uninstall --cask google-chrome ``` -This will both uninstall the Cask and remove applications which were moved to `/Applications`. +This will both uninstall the cask and remove the applications that were moved to `/Applications`. ## Other Commands @@ -114,7 +114,7 @@ KeepingYouAwake.app (App) ## Updating/Upgrading Casks -Since the Homebrew Cask repository is a Homebrew Tap, you’ll pull down the latest Casks every time you issue the regular Homebrew command `brew update`. You can check for outdated Casks with `brew outdated` and install the outdated Casks with `brew upgrade`. Many applications update themselves, so their Casks are ignored by `brew outdated` and `brew upgrade`. This behaviour can be overridden by adding `--greedy` to the command. +Since the Homebrew Cask repository is a Homebrew tap, you’ll pull down the latest casks every time you issue the regular Homebrew command `brew update`. You can check for outdated casks with `brew outdated` and install the outdated casks with `brew upgrade`. Many applications update themselves, so their casks are ignored by `brew outdated` and `brew upgrade`. This behaviour can be overridden by adding `--greedy` to either command. ## Updating/Upgrading the Homebrew Cask Tool @@ -122,22 +122,22 @@ Homebrew [automatically taps and keeps Homebrew Cask updated](https://github.com ## Additional Taps (optional) -The primary Homebrew Cask Tap includes most of the Casks that a typical user will be interested in. There are a few additional Taps where we store different kinds of Casks. +The primary Homebrew Cask tap includes most of the casks that a typical user will be interested in. There are a few additional taps where we store different kinds of casks. -| Tap name | description | +| tap name | description | | -------- | ----------- | -| [Homebrew/cask-versions](https://github.com/Homebrew/homebrew-cask-versions) | contains alternate versions of Casks (_e.g._ betas, nightly releases, old versions) -| [Homebrew/cask-fonts](https://github.com/Homebrew/homebrew-cask-fonts) | contains Casks that install fonts +| [homebrew/cask-versions](https://github.com/Homebrew/homebrew-cask-versions) | contains alternate versions of casks (_e.g._ betas, nightly releases, old versions) +| [homebrew/cask-fonts](https://github.com/Homebrew/homebrew-cask-fonts) | contains casks that install fonts -You can tap any of the above with a `brew tap` command: +You can tap any of the above with the `brew tap` command: ```bash brew tap ``` -after which, Casks from the new Tap will be available to `search` or `install` just like Casks from the main Tap. `brew update` will automatically keep your new Tap up to date. +after which casks from the new tap will be available to `search` or `install` just like casks from the main tap. `brew update` will automatically keep your new tap up to date. -You may also specify a fully-qualified Cask token (which includes the Tap) for any `brew` command. This will implicitly add the Tap if you have not previously added it with `brew tap`: +You may also specify a fully-qualified cask token (which includes the tap) for any `brew` command. This will implicitly add the tap if you have not previously added it with `brew tap`: ```bash brew install homebrew/cask-fonts/font-symbola @@ -150,14 +150,14 @@ brew install homebrew/cask-fonts/font-symbola * `--version`: print version and exit. * `--debug`: output debug information. * `--no-binaries`: skip symlinking executable binaries into `/usr/local/bin`. -* `--require-sha`: abort installation of Cask if no checksum is defined. +* `--require-sha`: abort installation of cask if no checksum is defined. * `--no-quarantine`: [disable Apple’s quarantining](https://docs.brew.sh/FAQ#why-cant-i-open-a-mac-app-from-an-unidentified-developer) for the specific app. -* `--language=[, ... ]`: changes the language of the Cask to be installed. The first matching language is used, otherwise it uses the default language of the Cask. +* `--language=[, ... ]`: changes the language of the cask to be installed. The first matching language is used, otherwise it uses the default language of the cask. You can also modify the default installation locations used when issuing `brew install`: * `--appdir=/my/path` changes the path where the applications will be moved. Default is `/Applications`. -* `--fontdir=/my/path` changes the path for Fonts. Default is `~/Library/Fonts`. +* `--fontdir=/my/path` changes the path for fonts. Default is `~/Library/Fonts`. See `man brew` for the other default installation locations and the flags to change them. @@ -178,19 +178,19 @@ brew install --appdir="/Applications" google-chrome ## Other Ways to Specify a Cask -Most `brew` commands can accept a Cask token as an argument. As described above, the token on the command line can take the form of: +Most `brew` commands can accept a cask token as an argument. As described above, the token on the command line can take the form of: * A simple token, _e.g._: `google-chrome`. -* A fully-qualified token which includes the Tap, _e.g._: `homebrew/cask/google-chrome`. +* A fully-qualified token which includes the tap, _e.g._: `homebrew/cask/google-chrome`. `brew` also accepts three other forms as arguments: -* A path to a Cask file, _e.g._: `/usr/local/Library/Taps/homebrew/homebrew-cask/Casks/google-chrome.rb`. -* A `curl`-retrievable URI to a Cask file, _e.g._: `https://raw.githubusercontent.com/Homebrew/homebrew-cask/f25b6babcd398abf48e33af3d887b2d00de1d661/Casks/google-chrome.rb`. -* A file in the current working directory, _e.g._: `my-modified-google-chrome.rb`. Note that matching Tapped Cask tokens will be preferred over this form when there is a conflict. To force the use of a Cask file in the current directory, specify a pathname with slashes, _e.g._: `./google-chrome.rb`. +* A path to a cask file, _e.g._: `/usr/local/Homebrew/Library/Taps/homebrew/homebrew-cask/Casks/g/google-chrome.rb`. +* A `curl`-retrievable URI to a cask file, _e.g._: `https://raw.githubusercontent.com/Homebrew/homebrew-cask/HEAD/Casks/g/google-chrome.rb`. +* A file in the current working directory, _e.g._: `my-modified-google-chrome.rb`. Note that matching tapped cask tokens will be preferred over this form when there is a conflict. To force the use of a cask file in the current directory, specify a pathname with slashes, _e.g._: `./google-chrome.rb`. -The last three forms are intended for users who wish to maintain private Casks. +The last three forms are intended for users who wish to maintain private casks. ## Taps -You can add Casks to your existing (or new) Taps: just create a directory named `Casks` inside your Tap, put your Cask files there, and everything will just work. +You can add casks to your existing (or new) taps: just create a directory named `Casks` inside your tap, put your cask files there, and everything will just work.