DSL doc: uninstall now available for all Casks

But required for `pkg`-based Casks.  Also contains some general
cleanup in section "Uninstall Stanza Details", which still needs
work.

CONTRIBUTING.md

@@ -124,7 +124,7 @@ Fill in the following stanzas for your Cask:
 | __artifact info__  | information about artifacts inside the Cask (can be specified multiple times)
 | `link`             | relative path to a file that should be linked into the `Applications` folder on installation (see also [Link Stanza Details](doc/CASK_LANGUAGE_REFERENCE.md#link-stanza-details))
 | `pkg`              | relative path to a `.pkg` file containing the distribution (see also [Pkg Stanza Details](doc/CASK_LANGUAGE_REFERENCE.md#pkg-stanza-details))
-| `uninstall`        | indicates what commands/scripts must be run to uninstall a pkg-based application (see also [Uninstall Stanza Details](doc/CASK_LANGUAGE_REFERENCE.md#uninstall-stanza-details))
+| `uninstall`        | procedures to uninstall a Cask. Optional unless the `pkg` stanza is used. (see also [Uninstall Stanza Details](doc/CASK_LANGUAGE_REFERENCE.md#uninstall-stanza-details))
 
 Additional stanzas you might need for special use-cases:
 

doc/CASK_LANGUAGE_REFERENCE.md

@@ -91,7 +91,7 @@ Each Cask must declare one or more *artifacts* (i.e. something to install)
 
 | name                   | multiple occurrences allowed? | value       |
 | ---------------------- |------------------------------ | ----------- |
-| `uninstall`            | yes                           | indicates what commands/scripts must be run to uninstall a pkg-based application (see also [Uninstall Stanza Details](#uninstall-stanza-details))
+| `uninstall`            | yes                           | procedures to uninstall a Cask. Optional unless the `pkg` stanza is used. (see also [Uninstall Stanza Details](#uninstall-stanza-details))
 | `nested_container`     | yes                           | relative path to an inner container that must be extracted before moving on with the installation; this allows us to support dmg inside tar, zip inside dmg, etc.
 | `depends_on_formula`   | yes                           | a list of Homebrew Formulae upon which this Cask depends
 | `caveats`              | yes                           | a string or Ruby block providing the user with Cask-specific information at install time (see also [Caveats Details](#caveats-details))
@@ -362,12 +362,19 @@ IF YOU CANNOT DESIGN A WORKING `UNINSTALL` STANZA, PLEASE SUBMIT YOUR
 CASK ANYWAY.  The maintainers will help you write an `uninstall` stanza:
 just ask!
 
-A Cask which uses the `pkg` stanza will **not** know how to uninstall
-correctly unless an `uninstall` stanza is given.
+### `uninstall` Is Required for Casks That Install a `pkg`
 
-So, while the `uninstall` stanza is technically optional in the Cask
-language, it is much better for end-users if every `pkg` has a
-corresponding `uninstall`.
+For most Casks, uninstall actions are determined automatically, and an
+explicit `uninstall` stanza is not needed.  However, a Cask which uses
+the `pkg` stanza 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` 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`.
 
 Since `pkg` installers can do arbitrary things, different techniques are
 needed to uninstall in each case.  You may need to specify one, or several,