Document the new desc stanza for Casks

Also adjust existing documentation where appropriate,
and add descriptions to two formulas as a demonstration.

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

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"

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 <file>`. Can be suppressed by using the special value `:no_check`.<br />See [Checksum Stanza Details](stanzas/sha256.md) for more information.
 | `url`      | no                            | URL to the `.dmg`/`.zip`/`.tgz`/`.tbz2` file that contains the application.<br />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.<br />See [URL Stanza Details](stanzas/url.md) for more information.
 | `name`     | yes                           | String providing the full and proper name defined by the vendor.<br />See [Name Stanza Details](stanzas/name.md) for more information.
+| `desc`     | no                            | One-line description of the Cask. Shows when running `brew info`.<br />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

doc/cask_language_reference/readme.md

@@ -125,6 +125,7 @@ language
 url
 appcast
 name
+desc
 homepage
 
 auto_updates

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).

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.

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.