unify and recast "Cask name" and "title" as "token"

[rolandwalker]

In numerous conversations such as #7606, b994bd7#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 conceptual 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 and methods similar to cask_name or cask have been recast here as cask_token, token, etc, resolving a long-standing ambiguity in which symbols named cask might refer to 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
• doc: 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

[szhu]

Just wondering, what's the rationally for using the term "token" instead of something like "title" or "id[entifier]"? I feel like token doesn't as effectively convey the fact that it's a way to (for lack of better words) name/identify a cask as much as those terms do.

[alebcay]

As @szhu mentioned, I think identifier would be a better term than token. When I see the word token, I generally imagine a string of letters and numbers that is not usually human-readable.

[claui]

@rolandwalker Whoa. This is the mother of all commits!

@alebcay @szhu As a relatively new contributor, I would personally be perfectly fine with either identifier or token. Having said that, I do suggest that we focus on user-facing text as much as possible when making a decision – given that users obviously outnumber contributors by orders of magnitude.

I admit that I have no idea as to which wording is going to work best. However to support decision-making, here is a list of six sentences from this PR which I believe that of all user-facing text that contains token, most (first-time) users are actually going to come across:

Examples for text that faces first-time users

1. From exceptions.rb:

   Error: This command requires a Cask token

   From USAGE.md:

2. The brew cask search command accepts a series of substring arguments, and returns tokens representing matching Casks.

3. The command brew cask install accepts a Cask token as returned by brew cask search.

4. You may also specify a fully-qualified Cask token (which includes the Tap) for any brew cask command.

   From brew-cask.1.md:

5. Install Cask identified by .

6. Perform a substring search of known Cask tokens for .

[tapeinosyne]

On the tangent of this PR, I would like to propose the addition of a top-level name stanza. As we enforce stricter rules for tokenization, we should also provide a venue for human-friendly names.

@rolandwalker emphasized elsewhere that it is desirable to adopt a maximally predictable approach to Cask identifiers for internal usage. The “Cask name” (as intended prior to this PR) is overloaded in such a way that our needs cannot be reconciled with those of vendors and users alike.

“Proper names” should be moved out of tags, which is accessory to search, and into a standalone stanza serving the wider purpose of human interfaces. Ideally, the user should not be concerned with our internal tokenization process, and be able to interact with the brew-cask CLI through the brand name with which they are familiar.

Nonetheless, the user will still need our internal token as a reference point (e.g. in debugging, scripting, or simply install), and thus good terminology is beneficial. In this regard, @claui's suggestion is very pertinent, as inexperienced users are the most susceptible to vocabulary. From their perspective, “token” may be too generic, and less clear than the more conventional “identifier” or similia.

[rolandwalker]

“Proper names” should be moved out of tags

@ndr-qef per our IRC discussion, I agree that's a good idea. tags :name can and should become a toplevel stanza name. It is not too late to do so for DSL 1.0, because tags :name has been used in few Casks. I also think the name should go near the top in Casks, and be a required stanza.

@claui yes the commit is annoyingly huge. My personal guideline for commit granularity is always "what is a good future boundary for git bisect?", since I use that tool often. On that grounds, I couldn't convince myself to split it. (Other times I have zillions of small commits like #6609).

I am glad to see general agreement that moving away from "Cask Name" is a step toward clarity. As to the choice of word, that is an interesting topic. Since @szhu asked what is the rationale:

There are all sorts of neat words for "the thingy", and the desire for variety didn't begin with software. Consider: "name", "token", "identifier", "argument", "parameter", "option", "key", "value", "term", "noun", "object", "subject", "element", "item", "article", "particle", "point", "bit", "tag", "descriptor" – and one could go on. Each denotes "that one particular thingy", but there is superb richness in the connotation: what type of thingy may fit, what is happening to the thingy, whether we speak of the thingy directly or a referent, etc.

"identifier" is certainly reasonable, but I chose "token" because it is more abstract. As @szhu said, "token" doesn't convey that it is a way to name the Cask. Exactly. The token is just a dependable way to refer to the Cask. We make it reasonably mnemonic because we are nice, but the proper name is going elsewhere — and I do want to display those full names by default in the UI.

Because I love the names, and the upstream branding. The name stanza is a great way for us to say enthusiastic "yes!" to any upstream/user requests. It is just no fun saying "no" as in b994bd7#commitcomment-8762316.

[szhu]

Thanks for your response @rolandwalker! Just to clarify – are you suggesting that a token may not be a unique way to refer to a Cask (as in, a Cask might be able to be referred to with different tokens)?

[rolandwalker]

Good point. To keep growing, we need to lock down the internal organization around this rigid "token", which has to be unique. But to be user-friendly, we should try to open up the UI.

At the very least, we should offer a "did you mean" suggestion when someone matches into the proper name. Simply accepting the proper name in place of the token might be a bad idea, because then scripts could break if names changed, and then names would have to become as rigid and conservative as tokens.

But I don't like "no", I like "yes". A "yes" way to think about it would be that we are adding the missing pieces someone would need to write a GUI to drive our CLI.

[szhu]

Suggestion:

Use token to mean some way to refer to a cask – and this can be any way, and there can be multiple ways. Think of it as a search query. Use identifier to refer to the internal, well, identifier, for a cask (and this means there is necessarily one for each cask).

In the beginning, there might be only one valid token for each cask, and it might be equal to the Cask's identifier. But the above terminology can still mean the same thing when, for example, we might have multiple tokens that refer to the same cask, or if we start using integers/UUIDs as identifiers instead of something normal users might put as a search query.

[rolandwalker]

@szhu yes, we might end up doing something like that. Internally (in the code) I already wanted to say "descriptor" for the larger case, because the argument can also be a URL instead of a token.

All: I would prefer to wait several days and have more discussion on this user-facing change. However, this large patch touches so many pieces of code, it is mergeblocking areas that both @claui and I want to work on.

I am fairly certain that "Cask name" brought problems that were holding us back. "Token" may not be perfect, but I am satisfied that it is Good Enough. Based on the above discussion, CONTRIBUTING.md and cask_token_reference.md were amended to clarify that the token is meant to be mnemonic.

Merging now (with some reservations about the pace).