diff --git a/Casks/alfred.rb b/Casks/alfred.rb index 88e9e326d6..925f9cd501 100644 --- a/Casks/alfred.rb +++ b/Casks/alfred.rb @@ -5,6 +5,7 @@ cask "alfred" do url "https://cachefly.alfredapp.com/Alfred_#{version}.dmg" appcast "https://www.alfredapp.com/app/update#{version.major}/general.xml" name "Alfred" + desc "Application launcher and productivity software" homepage "https://www.alfredapp.com/" auto_updates true diff --git a/Casks/fontforge.rb b/Casks/fontforge.rb index 54ea9fc257..feccf3fef9 100644 --- a/Casks/fontforge.rb +++ b/Casks/fontforge.rb @@ -7,6 +7,7 @@ cask "fontforge" do appcast "https://github.com/fontforge/fontforge/releases.atom", must_contain: version.major_minor_patch.dots_to_hyphens name "FontForge" + desc "Font editor and converter for outline and bitmap fonts" homepage "https://fontforge.github.io/en-US/" depends_on macos: ">= :yosemite" diff --git a/doc/cask_language_reference/all_stanzas.md b/doc/cask_language_reference/all_stanzas.md index bfb6273f06..89fd1990a0 100644 --- a/doc/cask_language_reference/all_stanzas.md +++ b/doc/cask_language_reference/all_stanzas.md @@ -10,6 +10,7 @@ Each of the following stanzas is required for every Cask. | `sha256` | no | 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 [Checksum Stanza Details](stanzas/sha256.md) for more information. | `url` | no | URL to the `.dmg`/`.zip`/`.tgz`/`.tbz2` file that contains the application.
A [comment](stanzas/url.md#when-url-and-homepage-hostnames-differ-add-a-comment) should be added if the hostnames in the `url` and `homepage` stanzas differ. Block syntax should be used for URLs that change on every visit.
See [URL Stanza Details](stanzas/url.md) for more information. | `name` | yes | String providing the full and proper name defined by the vendor.
See [Name Stanza Details](stanzas/name.md) for more information. +| `desc` | no | One-line description of the Cask. Shows when running `brew info`.
See [Desc Stanza Details](stanzas/desc.md) for more information. | `homepage` | no | Application homepage; used for the `brew cask home` command. ## At Least One Artifact Stanza Is Also Required diff --git a/doc/cask_language_reference/readme.md b/doc/cask_language_reference/readme.md index 6fb578e7ed..a2fcd92b88 100644 --- a/doc/cask_language_reference/readme.md +++ b/doc/cask_language_reference/readme.md @@ -125,6 +125,7 @@ language url appcast name +desc homepage auto_updates diff --git a/doc/cask_language_reference/stanzas/desc.md b/doc/cask_language_reference/stanzas/desc.md new file mode 100644 index 0000000000..330bf88550 --- /dev/null +++ b/doc/cask_language_reference/stanzas/desc.md @@ -0,0 +1,5 @@ +# desc + +`desc` accepts a single-line UTF-8 string (max. 80 characters) containing a short description of the software, and is used to help with searchability and disambiguation. + +It should start with a capital letter, and avoid including the Cask [name](name.md). The full list of rules is described [here](https://github.com/homebrew/brew/blob/master/Library/Homebrew/rubocops/shared/desc_helper.rb). diff --git a/doc/cask_language_reference/stanzas/name.md b/doc/cask_language_reference/stanzas/name.md index 81b50aed7d..2fd86473ad 100644 --- a/doc/cask_language_reference/stanzas/name.md +++ b/doc/cask_language_reference/stanzas/name.md @@ -1,7 +1,9 @@ # name -`name` accepts a UTF-8 string defining the full name of the software, and is used to help with searchability and disambiguation. It can be repeated multiple times if there are useful alternative names. +`name` accepts a UTF-8 string defining the name of the software, including capitalization and punctuation. It is used to help with searchability and disambiguation. -Its first instance should use the latin alphabet, include the software vendor’s name, and be as verbose as possible while still making sense. +Unlike the [token](https://github.com/Homebrew/homebrew-cask/blob/master/doc/cask_language_reference/token_reference.md), which is simplified and reduced to a limited set of characters, the `name` stanza can include the proper capitalization, spacing and punctuation to match the official name of the software. For disambiguation purposes, it is recommended to spell out the name of the application, and including the vendor name if necessary. A good example is [`pycharm-ce`](https://github.com/Homebrew/homebrew-cask/blob/fc05c0353aebb28e40db72faba04b82ca832d11a/Casks/pycharm-ce.rb#L6-L7), whose name is spelled out as `Jetbrains PyCharm Community Edition` makes sense even though it is likely never referenced as such anywhere. -A good example is [`pycharm-ce`](https://github.com/Homebrew/homebrew-cask/blob/fc05c0353aebb28e40db72faba04b82ca832d11a/Casks/pycharm-ce.rb#L6#L7). `Jetbrains PyCharm Community Edition` makes sense even though it is likely never referenced as such anywhere, but `Jetbrains PyCharm Community Edition CE` doesn’t, hence why it has a second line. Another example are casks whose original names do not use the latin alphabet, like [`cave-story`](https://github.com/Homebrew/homebrew-cask/blob/0fe48607f5656e4f1de58c6884945378b7e6f960/Casks/cave-story.rb#L7#L9). +Additional details about the software can be provided in the [desc](desc.md) stanza. + +The `name` stanza can be repeated multiple times if there are useful alternative names. The first instance should use the Latin alphabet. For example, see the [`cave-story`](https://github.com/Homebrew/homebrew-cask/blob/0fe48607f5656e4f1de58c6884945378b7e6f960/Casks/cave-story.rb#L7-L9) cask, whose original name does not use the Latin alphabet. diff --git a/doc/faq/not_a_discoverability_service.md b/doc/faq/not_a_discoverability_service.md index 75b92bf698..2f35e20af6 100644 --- a/doc/faq/not_a_discoverability_service.md +++ b/doc/faq/not_a_discoverability_service.md @@ -1,13 +1,8 @@ # Homebrew Cask is not a discoverability service -From the inception of Homebrew Cask, various requests fell under the umbrella of this reply. Though a somewhat popular request, after careful consideration on multiple occasions we’ve always come back to the same conclusion: we’re not a discoverability service and our users are expected to have reasonable knowledge about the apps they’re installing through us before doing so. +From the inception of Homebrew Cask, various requests fell under the umbrella of this reply. Though a somewhat popular request, after careful consideration on multiple occasions we’ve always come back to the same conclusion: we’re not a discoverability service and our users are expected to have reasonable knowledge about the apps they’re installing through us before doing so. For example, [grouping casks by categories](https://github.com/Homebrew/homebrew-cask/issues/5425) is not within the scope of the project. -Examples of requests under this same theme: - -+ [Separate by categories](https://github.com/Homebrew/homebrew-cask/issues/5425). -+ [Add descriptions](https://github.com/Homebrew/homebrew-cask/issues/16089). - -Amongst other things, the logistics of such requests are unsustainable for Homebrew Cask. Before making a request of this nature, you must read through those issues, as well as any other issues they link to, to get a full understanding of why that is the case, and why “but project *x* does *y*” arguments aren’t applicable, and not every package manager is the same. +Amongst other things, the logistics of such requests are unsustainable for Homebrew Cask. Before making a request of this nature, you must read through previous related issues, as well as any other issues they link to, to get a full understanding of why that is the case, and why “but project *x* does *y*” arguments aren’t applicable, and not every package manager is the same. You should also be able to present clear actionable fixes to those concerns. Simply asking for it without solutions will get your issue closed.