* always coerce `:macos` value to array; simplify code
* remove warning comments about unset values
* doc explicitly that requirements are covered as well as dependencies
* doc that `depends_on` is not consulted until `install` time
* in docs and code, say "release" instead of "version" for the :macos release
* todo: provide our own variable styled "release" to use in Casks, instead of Homebrew's `MacOS.Version`
* doc that symbols are preferred for `:macos` over strings in Casks (interally, all are converted to idential `Gem::Version` objects)
* doc: remove `os_version_only` from `cask_language_deltas.md`
* doc: improve internal links
* doc: recast OS X release symbol list as table
* doc: (incidental) regularize orthography of Formula and Cask
* Fill in the functionality for the `depends_on :macos` stub
* de-document `caveats` method `os_version_only`
* clean up some related docs re: version strings
* add `depends_on_test.rb`
* clarify some related `depends_on :formula` doc, tests, and code
* formatting in test Casks
* "Canonical App Name" becomes "Simplified App Name"
* devscript `cask_namer` renamed to `generate_cask_token`
* doc file `CASK_NAMING_REFERENCE.md` renamed to `cask_token_reference.md`
* DSL uses `"#{token}"` for interpolation instead of `"#{title}"`
* documentation text
* backend code (variables, method, class names)
* error message text
* tests
* code comments
* Cask comments
* emphasize `tags :name`
* doc: use "vendor" consistently instead of "developer"
* doc: many man page argument descriptions were incorrect
* incidental clarifications
Many backend variables similar to `cask_name` or `cask` have
been standardized to `cask_token`, `token`, etc, resolving a long-
standing ambiguity in which variables named `cask` might contain
a Cask instance or a string token.
In many places the docs could be shortened from "Cask name" to
simply "token", which is desirable because we use the term "Cask"
in too many contexts.
`caskroom_only` was never documented. Its original purpose was
obsoleted in #4865, and its use has been recently been reduced to
two Casks.
This PR
* continues the rationalization of naming by changing `caskroom_only`
to `stage_only`. "stage" is the verb for "make a copy under the
caskroom directory"
* documents `stage_only`
* adds tests for `stage_only`
* validates the argument to `stage_only`
* gives sensible output in `brew cask info` for `stage_only` Casks
* enforces that `stage_only` cannot coexist with any activatable
artifacts
`caskroom_only` is still supported for backward compatibility,
but should be removed before 0.50.0.
* part of DSL 1.0 review
* `destination_path` was always a bit vague (it refers to
Cask-specific, version-specific location under
`/opt/homebrew-cask/Caskroom`)
* here renamed `staged_path` to match upcoming command verb
`brew cask stage`
* rename also intended to reduce confusion when we implement
copying as a configurable alternative to symlinking
* transitional `destination_path` methods to remain while
Casks are converted (this was documented as a part of the
DSL, and used by 39 Casks in main repo)
* unrelated variables containing "stage" recast for clarity
* was already done, but inconsistently
* this style follows homebrew Formula
* covers user-facing messages, test titles, comments
* some related minor orthography is included, such
as the consistent spelling of our project name as
"homebrew-cask"
* grammar nits
Keeping the `link` stanza in the DSL is a mistake: it will be
confusing when combined with the ability to install by copying.
This PR retires `link` completely, and adds a generic artifact
stanza called `artifact`. (`link` is removed from the docs, but
will still work for compatibility during transition.)
This only affects one current Cask (dwarf-fortress.rb), and that
Cask may be changed to use `suite` in the future.
Roland Walker