diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 923af1638c7..cbf8c063722 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -51,9 +51,9 @@ With a bit of work, you can create a Cask for it. The document [Adding A Cask](d Some style guidelines: * 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.md). -* The stanza order and position of newlines is important to make things easier (See [Stanza order](https://docs.brew.sh/Cask-Cookbook.md#stanza-order)). -* Use string manipulations to improve the maintainability of your Cask (See [`version` methods](https://docs.brew.sh/Cask-Cookbook.md#version-methods)). +* 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](doc/development/adding_a_cask.md#testing-your-new-cask)). * Make one Pull Request per Cask change. * Do not squash commits after updating a Pull Request. diff --git a/doc/development/adding_a_cask.md b/doc/development/adding_a_cask.md index d24dfa666dc..06535e0d194 100644 --- a/doc/development/adding_a_cask.md +++ b/doc/development/adding_a_cask.md @@ -47,9 +47,9 @@ cask "noisy" do end ``` -Here is a last example for `airdisplay`, which uses a `pkg` installer to install the application instead of a stand-alone application bundle (`.app`). Note the [`uninstall pkgutil` stanza](https://docs.brew.sh/Cask-Cookbook.md#uninstall-key-pkgutil), which is needed to uninstall all files which were installed using the installer. +Here is a last example for `airdisplay`, which uses a `pkg` installer to install the application instead of a stand-alone application bundle (`.app`). Note the [`uninstall pkgutil` stanza](https://docs.brew.sh/Cask-Cookbook#uninstall-key-pkgutil), which is needed to uninstall all files which were installed using the installer. -You will also see how to adapt `version` to the download `url`. Use [our custom `version` methods](https://docs.brew.sh/Cask-Cookbook.md#version-methods) to do so, resorting to the standard [Ruby String methods](https://ruby-doc.org/core/String.html) when they don’t suffice. +You will also see how to adapt `version` to the download `url`. Use [our custom `version` methods](https://docs.brew.sh/Cask-Cookbook#version-methods) to do so, resorting to the standard [Ruby String methods](https://ruby-doc.org/core/String.html) when they don’t suffice. ```ruby cask "airdisplay" do @@ -126,24 +126,24 @@ Fill in the following stanzas for your Cask: | name | value | | ------------------ | ----------- | | `version` | application version -| `sha256` | SHA-256 checksum of the file downloaded from `url`, calculated by the command `shasum -a 256 `. Can be suppressed by using the special value `:no_check`. (see [sha256](https://docs.brew.sh/Cask-Cookbook.md#stanza-sha256)) -| `url` | URL to the `.dmg`/`.zip`/`.tgz`/`.tbz2` file that contains the application.
A [`verified` parameter](https://docs.brew.sh/Cask-Cookbook#when-url-and-homepage-hostnames-differ-add-verified) must be added if the hostnames in the `url` and `homepage` stanzas differ. [Block syntax](https://docs.brew.sh/Cask-Cookbook.md#using-a-block-to-defer-code-execution) is available for URLs that change on every visit -| `name` | the full and proper name defined by the vendor, and any useful alternate names (see [Name Stanza Details](https://docs.brew.sh/Cask-Cookbook.md#stanza-name)) -| `desc` | one-line description of the software (see [Desc Stanza Details](https://docs.brew.sh/Cask-Cookbook.md#stanza-desc)) +| `sha256` | SHA-256 checksum of the file downloaded from `url`, calculated by the command `shasum -a 256 `. Can be suppressed by using the special value `:no_check`. (see [sha256](https://docs.brew.sh/Cask-Cookbook#stanza-sha256)) +| `url` | URL to the `.dmg`/`.zip`/`.tgz`/`.tbz2` file that contains the application.
A [`verified` parameter](https://docs.brew.sh/Cask-Cookbook#when-url-and-homepage-hostnames-differ-add-verified) must be added if the hostnames in the `url` and `homepage` stanzas differ. [Block syntax](https://docs.brew.sh/Cask-Cookbook#using-a-block-to-defer-code-execution) is available for URLs that change on every visit +| `name` | the full and proper name defined by the vendor, and any useful alternate names (see [Name Stanza Details](https://docs.brew.sh/Cask-Cookbook#stanza-name)) +| `desc` | one-line description of the software (see [Desc Stanza Details](https://docs.brew.sh/Cask-Cookbook#stanza-desc)) | `homepage` | application homepage; used for the `brew home` command -| `app` | relative path to an `.app` bundle that should be moved into the `/Applications` folder on installation (see [App Stanza Details](https://docs.brew.sh/Cask-Cookbook.md#stanzas-app)) +| `app` | relative path to an `.app` bundle that should be moved into the `/Applications` folder on installation (see [App Stanza Details](https://docs.brew.sh/Cask-Cookbook#stanza-app)) Other commonly-used stanzas are: | name | value | | ------------------ | ----------- | | `livecheck` | Ruby block describing how to find updates for this Cask (see [Livecheck Stanza Details](https://docs.brew.sh/Cask-Cookbook#stanza-livecheck)) -| `pkg` | relative path to a `.pkg` file containing the distribution (see [Pkg Stanza Details](https://docs.brew.sh/Cask-Cookbook.md#stanza-pkg)) -| `caveats` | a string or Ruby block providing the user with Cask-specific information at install time (see [Caveats Stanza Details](https://docs.brew.sh/Cask-Cookbook.md#stanza-caveats)) -| `uninstall` | procedures to uninstall a Cask. Optional unless the `pkg` stanza is used. (see [Uninstall Stanza Details](https://docs.brew.sh/Cask-Cookbook.md#stanza-uninstall)) -| `zap` | additional procedures for a more complete uninstall, including configuration files and shared resources (see [Zap Stanza Details](https://docs.brew.sh/Cask-Cookbook.md#stanza-zap)) +| `pkg` | relative path to a `.pkg` file containing the distribution (see [Pkg Stanza Details](https://docs.brew.sh/Cask-Cookbook#stanza-pkg)) +| `caveats` | a string or Ruby block providing the user with Cask-specific information at install time (see [Caveats Stanza Details](https://docs.brew.sh/Cask-Cookbook#stanza-caveats)) +| `uninstall` | procedures to uninstall a Cask. Optional unless the `pkg` stanza is used. (see [Uninstall Stanza Details](https://docs.brew.sh/Cask-Cookbook#stanza-uninstall)) +| `zap` | additional procedures for a more complete uninstall, including configuration files and shared resources (see [Zap Stanza Details](https://docs.brew.sh/Cask-Cookbook#stanza-zap)) -Additional `artifact` stanzas you might need for special use-cases can be found [here](https://docs.brew.sh/Cask-Cookbook.md#at-least-one-artifact-stanza-is-also-required). Even more special-use stanzas are listed at [Optional Stanzas](https://docs.brew.sh/Cask-Cookbook.md#optional-stanzas). +Additional `artifact` stanzas you might need for special use-cases can be found [here](https://docs.brew.sh/Cask-Cookbook#at-least-one-artifact-stanza-is-also-required). Even more special-use stanzas are listed at [Optional Stanzas](https://docs.brew.sh/Cask-Cookbook#optional-stanzas). ### Cask Token Details @@ -151,7 +151,7 @@ If a token conflicts with an already-existing Cask, authors should manually make If possible, avoid creating tokens which differ only by the placement of hyphens. -To generate a token manually, or to learn about exceptions for unusual cases, see [token_reference.md](https://docs.brew.sh/Cask-Cookbook.md#token-reference). +To generate a token manually, or to learn about exceptions for unusual cases, see [token_reference.md](https://docs.brew.sh/Cask-Cookbook#token-reference). ### Archives With Subfolders diff --git a/doc/reporting_bugs/source_is_not_there_error.md b/doc/reporting_bugs/source_is_not_there_error.md index d05d79e54c7..c70abef4daf 100644 --- a/doc/reporting_bugs/source_is_not_there_error.md +++ b/doc/reporting_bugs/source_is_not_there_error.md @@ -1,4 +1,4 @@ -First, you need to identify which artifact is not being handled correctly anymore. It’s explicit in the error message: if it says `It seems the App source…'` the problem is [`app`](https://docs.brew.sh/Cask-Cookbook.md#stanza-app). The pattern is the same across [all artifacts](https://docs.brew.sh/Cask-Cookbook.md#at-least-one-artifact-stanza-is-also-required). +First, you need to identify which artifact is not being handled correctly anymore. It’s explicit in the error message: if it says `It seems the App source…'` the problem is [`app`](https://docs.brew.sh/Cask-Cookbook#stanza-app). The pattern is the same across [all artifacts](https://docs.brew.sh/Cask-Cookbook#at-least-one-artifact-stanza-is-also-required). Fixing this error is typically easy, and requires only a bit of time on your part. Start by downloading the package for the cask: `brew fetch `. The last line of output will inform you of the location of the download. Navigate there and manually unpack it. As an example, lets say the structure inside the archive is as follows: @@ -19,6 +19,6 @@ app "SomeApp.app" The cask was expecting `SomeApp.app` to be in the top directory of the archive (see how it says simply `SomeApp.app`) but the developer changed it to inside a `Files` directory. All we have to do is update that line of the cask to follow the new structure: `app 'Files/SomeApp.app'`. -Note that occasionally the app’s name changes completely (from `SomeApp.app` to `OtherApp.app`, let's say). In these instances, the filename of the cask itself, as well as its token, must also change. Consult the [`token reference`](https://docs.brew.sh/Cask-Cookbook.md#token-reference) for complete instructions on the new name. +Note that occasionally the app’s name changes completely (from `SomeApp.app` to `OtherApp.app`, let's say). In these instances, the filename of the cask itself, as well as its token, must also change. Consult the [`token reference`](https://docs.brew.sh/Cask-Cookbook#token-reference) for complete instructions on the new name. Help us by [submitting a fix](https://github.com/Homebrew/homebrew-cask/blob/HEAD/CONTRIBUTING.md#updating-a-cask). If you get stumped, [open an issue](https://github.com/Homebrew/homebrew-cask/issues/new?template=01_bug_report.md) explaining your steps so far and where you’re having trouble.