Homebrew · reitermarkus · Aug 11, 2020 · Aug 9, 2020 · Aug 9, 2020 · Aug 9, 2020
diff --git a/Casks/alfred.rb b/Casks/alfred.rb
@@ -5,6 +5,7 @@
   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
@@ -7,6 +7,7 @@
   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
diff --git a/doc/cask_language_reference/readme.md b/doc/cask_language_reference/readme.md
@@ -5,16 +5,17 @@
 Each Cask is a Ruby block, beginning with a special header line. The Cask definition itself is always enclosed in a `do … end` block. Example:
 
 ```ruby
-cask 'alfred' do
-  version '2.7.1_387'
-  sha256 'a3738d0513d736918a6d71535ef3d85dd184af267c05698e49ac4c6b48f38e17'
+cask "alfred" do
+  version "2.7.1_387"
+  sha256 "a3738d0513d736918a6d71535ef3d85dd184af267c05698e49ac4c6b48f38e17"
 
   url "https://cachefly.alfredapp.com/Alfred_#{version}.zip"
-  name 'Alfred'
-  homepage 'https://www.alfredapp.com/'
+  name "Alfred"
+  desc "Application launcher and productivity software"
+  homepage "https://www.alfredapp.com/"
 
-  app 'Alfred 2.app'
-  app 'Alfred 2.app/Contents/Preferences/Alfred Preferences.app'
+  app "Alfred 2.app"
+  app "Alfred 2.app/Contents/Preferences/Alfred Preferences.app"
 end
 ```
 
@@ -54,7 +55,6 @@ The available symbols for macOS versions are: `:yosemite`, `:el_capitan`, `:sier
 
 Note that in the official Homebrew Cask repositories only the symbolic names are allowed. The numeric comparison may only be used for third-party taps.
 
-
 ### Always Fall Through to the Newest Case
 
 Conditionals should be constructed so that the default is the newest OS version. When using an `if` statement, test for older versions, and then let the `else` statement hold the latest and greatest. This makes it more likely that the Cask will work without alteration when a new OS is released. Example (from [coconutbattery.rb](https://github.com/Homebrew/homebrew-cask/blob/2c801af44be29fff7f3cb2996455fce5dd95d1cc/Casks/coconutbattery.rb)):
@@ -73,7 +73,6 @@ end
 
 If a cask is available in multiple languages, you can use the `language` stanza to switch between languages or regions based on the system locale.
 
-
 ## Arbitrary Ruby Methods
 
 In the exceptional case that the Cask DSL is insufficient, it is possible to define arbitrary Ruby variables and methods inside the Cask by creating a `Utils` namespace. Example:
@@ -113,7 +112,6 @@ enclosed in single quotes.
 
 There are currently some arbitrary limitations on Cask tokens which are in the process of being removed. The Travis bot will catch any errors during the transition.
 
-
 ## Stanza order
 
 Having a common order for stanzas makes Casks easier to update and parse. Below is the complete stanza sequence (no Cask will have all stanzas). The empty lines shown here are also important, as they help to visually delineate information.
@@ -127,6 +125,7 @@ language
 url
 appcast
 name
+desc
 homepage
 
 auto_updates
@@ -139,6 +138,7 @@ app
 pkg
 installer
 binary
+manpage
 colorpicker
 dictionary
 font

diff --git a/doc/cask_language_reference/stanzas/desc.md 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
@@ -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/cask_language_reference/stanzas/pkg.md b/doc/cask_language_reference/stanzas/pkg.md
@@ -36,7 +36,7 @@ will output an XML which you can use to extract the `choices:` values, as well a
 
 See [this pull request for wireshark-chmodbpf](https://github.com/Homebrew/homebrew-cask/pull/26997) and [this one for wine-staging](https://github.com/Homebrew/homebrew-cask/pull/27937) for some examples of the procedure.
 
-Example ([wireshark-chmodbpf.rb](https://github.com/Homebrew/homebrew-cask/blob/f95b8a8306b91fe9da7908b842f4a5fa80f7afe0/Casks/wireshark-chmodbpf.rb#L9#L26)):
+Example ([wireshark-chmodbpf.rb](https://github.com/Homebrew/homebrew-cask/blob/f95b8a8306b91fe9da7908b842f4a5fa80f7afe0/Casks/wireshark-chmodbpf.rb#L9-L26)):
 ```ruby
 pkg "Wireshark #{version} Intel 64.pkg",
     choices: [
@@ -58,7 +58,7 @@ pkg "Wireshark #{version} Intel 64.pkg",
              ]
 ```
 
-Example ([wine-staging.rb](https://github.com/Homebrew/homebrew-cask/blob/51b65f6a5a25a7f79af4d372e1a0bf1dc3849251/Casks/wine-staging.rb#L11#L18)):
+Example ([wine-staging.rb](https://github.com/Homebrew/homebrew-cask/blob/51b65f6a5a25a7f79af4d372e1a0bf1dc3849251/Casks/wine-staging.rb#L11-L18)):
 ```ruby
 pkg "winehq-staging-#{version}.pkg",
     choices: [

diff --git a/doc/cask_language_reference/stanzas/uninstall.md b/doc/cask_language_reference/stanzas/uninstall.md
@@ -10,7 +10,7 @@ IF YOU CANNOT DESIGN A WORKING `UNINSTALL` STANZA, PLEASE SUBMIT YOUR CASK ANYWA
 
 For most Casks, uninstall actions are determined automatically, and an explicit `uninstall` stanza is not needed. However, a Cask which uses the `pkg` or `installer manual:` stanzas will **not** know how to uninstall correctly unless an `uninstall` stanza is given.
 
-So, while the Cask language does not enforce the requirement, it is much better for end-users if every `pkg` and `installer manual:` has a corresponding `uninstall`.
+So, while the [Cask DSL](../readme.md) does not enforce the requirement, it is much better for end-users if every `pkg` and `installer manual:` has a corresponding `uninstall`.
 
 The `uninstall` stanza is available for non-`pkg` Casks, and is useful for a few corner cases. However, the documentation below concerns the typical case of using `uninstall` to define procedures for a `pkg`.
 

diff --git a/doc/cask_language_reference/stanzas/url.md b/doc/cask_language_reference/stanzas/url.md
@@ -17,7 +17,7 @@ When a plain URL string is insufficient to fetch a file, additional information
 | `user_agent:`      | a string holding the user agent to set for the download request. Can also be set to the symbol `:fake`, which will use a generic Browser-like user agent string. We prefer `:fake` when the server does not require a specific user agent.
 | `data:`            | a hash of parameters to be set in the POST request
 
-Example of using `cookies:`: [java.rb](https://github.com/Homebrew/homebrew-cask/blob/472930df191d66747a57d5c96c0d00511d56e21b/Casks/java.rb#L5#L8)
+Example of using `cookies:`: [java.rb](https://github.com/Homebrew/homebrew-cask/blob/472930df191d66747a57d5c96c0d00511d56e21b/Casks/java.rb#L5-L8)
 
 Example of using `referer:`: [rrootage.rb](https://github.com/Homebrew/homebrew-cask/blob/312ae841f1f1b2ec07f4d88b7dfdd7fbdf8d4f94/Casks/rrootage.rb#L5)
 

diff --git a/doc/development/adding_a_cask.md b/doc/development/adding_a_cask.md
@@ -6,7 +6,6 @@
 [open pull requests]: https://github.com/Homebrew/homebrew-cask/pulls
 [already refused]: https://github.com/Homebrew/homebrew-cask/search?q=is%3Aclosed&type=Issues
 
-
 ## Adding a Cask
 
 Making a new Cask is easy. Follow the directions in [Getting Set Up To Contribute](../../CONTRIBUTING.md#getting-set-up-to-contribute) to begin.
@@ -155,7 +154,6 @@ Example:
   app 'TexmakerMacosxLion/texmaker.app'
   ```
 
-
 ## Testing Your New Cask
 
 Give it a shot with:
@@ -268,19 +266,19 @@ $ git checkout -b my-new-cask-branch
 Switched to a new branch 'my-new-cask-branch'
 ```
 
-Stage your Cask with: 
+Stage your Cask with:
 
 ```bash
 $ git add Casks/my-new-cask.rb
-``` 
+```
 
-You can view the changes that are to be committed with: 
+You can view the changes that are to be committed with:
 
 ```bash
 $ git diff --cached
 ```
 
-Commit your changes with: 
+Commit your changes with:
 
 ```bash
 $ git commit -v
@@ -329,21 +327,19 @@ If you are using [GitHub two-factor authentication](https://help.github.com/arti
 The `git push` command prints a suggestion to create a pull request:
 
 ```
-remote: Create a pull request for 'new-cask-cask' on GitHub by visiting:                                          
+remote: Create a pull request for 'new-cask-cask' on GitHub by visiting:
 remote:      https://github.com/{{my-github-username}}/homebrew-cask/pull/new/my-new-cask-branch
 ```
 
 #### b) use suggestion at Github website
 
-Now go to the [`homebrew-cask` GitHub repository](https://github.com/Homebrew/homebrew-cask). GitHub will often show your `my-new-cask-branch` branch with a handy button to `Compare & pull request`. 
-
+Now go to the [`homebrew-cask` GitHub repository](https://github.com/Homebrew/homebrew-cask). GitHub will often show your `my-new-cask-branch` branch with a handy button to `Compare & pull request`.
 
 #### c) manually create a pull request at Github website
 
 Otherwise, click the `New pull request` button and choose to `compare across forks`. The base fork should be `Homebrew/homebrew-cask @ master`, and the head fork should be `my-github-username/homebrew-cask @ my-new-cask-branch`. You can also add any further comments to your pull request at this stage.
 
-
-#### Congratulations! 
+#### Congratulations!
 
 You are done now, and your Cask should be pulled in or otherwise noticed in a while. If a maintainer suggests some changes, just make them on the `my-new-cask-branch` branch locally and [push](#pushing).
 

diff --git 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.