caskroom/homebrew-cask — pull request #7673 by rolandwalker (2014-11-28 20:50:37+00:00)
Title: unify and recast "Cask name" and "title" as "token"

In numerous conversations such as #7606, https://github.com/caskroom/homebrew-cask/commit/b994bd7d6118d3b093461a77f4f326b0b55bd397#commitcomment-8762316, and IRC, I have given the same explanation that what we call "Cask name" should not be considered the "name", and functions more like a UID or token.

So, it would save time and reduce confusion if we simply renamed it the "token" as in this PR. This makes even more sense now that `tags :name` is live.

The basename of the the filename containing the Cask has always been ridiculously constrained, will continue to be constrained, and can never fully represent product branding.

This solution also resolves the conflict between "Cask name" and `tags :name`. (We purposefully didn't use `tags :alternate_name`.)

There was also an alternate term "title" which appeared in a few places, particularly as a method used for interpolations in Casks. "title" is also needlessly confusing. Now that we have gotten rid of Cask class names (at least as is visible to the user), there is only one descriptor for a Cask, and we need only one term for it.

This PR covers quite a bit of code as well as docs. Many backend variables similar to `cask_name` or `cask` have been standardized here to `cask_token`, `token`, etc, resolving a long-standing ambiguity in which variables named `cask` might contain a Cask instance or a string token. This improves clarity and is a step toward a much needed refactor: using a Cask::Descriptor class instead of pushing around strings.

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.

Backward-compatibility methods for `title` were sprinkled in a few places to support existing usage in Casks.

* doc file `CASK_NAMING_REFERENCE.md` renamed to `cask_token_reference.md`
* "Canonical App Name" becomes "Simplified App Name"
* devscript `cask_namer` renamed to `generate_cask_token`
* 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 in both code and doc