What is the canonical way for aliasing a cask and/or making it more searchable/discoverable?

[0xdevalias]

Output of brew config

N/A

Output of brew doctor

N/A

Description of issue

I was looking to add a new cask for Razer macOS today, as it didn't show up while I was searching; but then by some sheer luck, I stumbled upon the fact that the cask is actually called 1kc-razer:

• https://github.com/1kc/razer-macos

  • Color effects manager for Razer devices for macOS. Supports High Sierra (10.13) to Monterey (12.0). Made by the community, based on openrazer.

⇒ brew search razer-macos
Error: No formulae or casks found for "razer-macos".

⇒ brew search "Razer macOS"
Error: No formulae or casks found for "Razer macOS".

⇒ brew search Razer macOS
Error: No formulae or casks found for "Razer macOS".

⇒ brew search razer
==> Formulae
ranger

==> Casks
1kc-razer                                                                        raze

Some history of this formula:

• https://github.com/homebrew/homebrew-cask-drivers/commits/master/Casks/1kc-razer.rb
  • added: Add Razer macOS homebrew-cask-drivers#2032
    • Originally named razer-macos by @sgulls
    • Renamed to razer-macos-unofficial by @sgulls
    • Renamed to 1kc-razer by @vitorgalvao
  • removed: Delete unpopular casks. homebrew-cask-drivers#3443
    • Was removed due to 'low usage' (potentially because of the hard to discover name?)
  • migrated: 1kc-razer: add to tap-migrations homebrew-cask-drivers#3450
    • Migrated from cask drivers to main cask repo
• https://github.com/Homebrew/homebrew-cask/commits/master/Casks/1kc-razer.rb
  • migrated: 1kc-razer: migrate from cask-drivers homebrew-cask#146687
    • Migrated from cask drivers to main cask repo
    • Moved into sharded subdirectories
• https://github.com/Homebrew/homebrew-cask/commits/master/Casks/1/1kc-razer.rb
  • current cask: https://github.com/Homebrew/homebrew-cask/blob/master/Casks/1/1kc-razer.rb

Given the name/homepage/etc in the cask, I would have expected at least some of my searches above to have turned it up for keywords razer-macos or Razer macOS:

# ..snip..

  url "https://github.com/1kc/razer-macos/releases/download/v#{version}/Razer.macOS-#{version}-universal.dmg"
  name "Razer macOS"
  desc "Open source color effects manager for Razer devices"
  homepage "https://github.com/1kc/razer-macos"

# ..snip..

These issues were asking about how best to support aliases for casks/etc:

• Support aliases for cask names homebrew-cask#64503
  • This is explored further below
• How to add alias for formula ? brew#469
  • This suggests creating a symlink in the Aliases directory, but that only seems to exist for homebrew-core, not homebrew-cask:
    • https://github.com/Homebrew/homebrew-core/tree/master/Aliases
  • Docs for this: https://docs.brew.sh/Formula-Cookbook#a-quick-word-on-naming

    • Add aliases by creating symlinks in an Aliases directory in the tap root.

• Add cargo alias for the rust formula homebrew-core#36560
  • This suggests using missing_formula.rb

---

One of the suggestions there was the missing_formula.rb script:

• https://github.com/Homebrew/brew/blob/master/Library/Homebrew/missing_formula.rb

---

Another was using multiple name stanzas, but given searching by the already existing name didn't show up the cask anyway, this doesn't seem like a good solution here (or search is broken and needs to be fixed)

• https://docs.brew.sh/Cask-Cookbook#stanza-name

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

  • The name stanza can be repeated multiple times if there are useful alternative names.

• https://docs.brew.sh/Cask-Cookbook#stanza-desc

  • desc accepts a single-line UTF-8 string containing a short description of the software. It’s used to help with searchability and disambiguation, thus it must concisely describe what the software does (or what you can accomplish with it).

I'm not really familiar with the brew codebase, but from a quick search, this seems to be (at least some of) the code related to searching:

• https://github.com/Homebrew/brew/blob/master/Library/Homebrew/search.rb
  • Some methods of note:
    • search_descriptions: seems like it should work for both Formulae and Casks
    • search_formulae: seems to have support for aliases? (aliases = Formula.alias_full_names, results = search(Formula.full_names + aliases, string_or_regex).sort). Also uses Formula.fuzzy_search
    • search_casks: doesn't look like it has support for aliases, but does do some stuff related to finding all the cask tokens (cask_tokens = Tap.flat_map(&:cask_tokens).map, Homebrew::API::Cask.all_casks.keys, cask_tokens |= Homebrew::API::Cask.all_casks.keys, results = search(cask_tokens, string_or_regex)), and also seems to have some 'did you mean' suggestions ( results += DidYouMean::SpellChecker.new(dictionary: cask_tokens).correct(string_or_regex)))
    • search_names: this function exists, and seems like it should work for both Formulae and Casks, but at least as far as I can tell, it doesn't seem to be called anywhere in this file. It is however called from the following:
      • https://github.com/Homebrew/brew/blob/master/Library/Homebrew/cmd/search.rb#L85
        • This seems to suggest that descriptions and names are only searched when the --desc flag is passed:
          • https://github.com/Homebrew/brew/blob/master/Library/Homebrew/cmd/search.rb#L39-L41

            • --desc: Search for formulae with a description matching text and casks with a name or description matching text.

        • Which then also apparently needs --eval-all to be passed as well for it to be usable at all:

          • Error: Invalid usage: `brew search --desc` needs `--eval-all` passed or `HOMEBREW_EVAL_ALL` set!

          • https://github.com/Homebrew/brew/blob/master/Library/Homebrew/cmd/search.rb#L42-L45

            • --eval-all (depends_on: "--desc"): Evaluate all available formulae and casks, whether installed or not, to search their descriptions. Implied if HOMEBREW_EVAL_ALL is set.

      • https://github.com/Homebrew/brew/blob/master/Library/Homebrew/cmd/install.rb#L381

So combining all of the intricacies of the above custom search params, I can actually find the cask with my 'more canonical' search terms. Though I suspect that most standard users aren't going to think/know to do that:

⇒ brew search --cask --desc --eval-all razer-macos
==> Casks
1kc-razer: (Razer macOS, razer-macos) Open source color effects manager for Razer devices

⇒ brew search --cask --desc --eval-all "Razer macOS"
==> Casks
1kc-razer: (Razer macOS, razer-macos) Open source color effects manager for Razer devices

⇒ brew search --cask --desc --eval-all Razer macOS
==> Casks
1kc-razer: (Razer macOS, razer-macos) Open source color effects manager for Razer devices

Interesting also, searching with those flags gives me less suggestions than searching without (note the raze cask in the 2nd command output that is missing from the first):

⇒ brew search --cask --desc --eval-all razer
==> Casks
1kc-razer: (Razer macOS, razer-macos) Open source color effects manager for Razer devices

⇒ brew search --cask razer
==> Casks
1kc-razer                                                                        raze

Which would seem to suggest that this method of searching isn't ideal as a 'default replacement' either.

I also stumbled across the --pull-requests flag for searching, which provides some more insight:

⇒ brew search --pull-request razer macos
==> Closed pull requests
1kc-razer: migrate from cask-drivers (https://github.com/Homebrew/homebrew-cask/pull/146687)
📦 Add Razer macOS (https://github.com/Homebrew/homebrew-cask/pull/105414)
Add Razer macOS (https://github.com/Homebrew/homebrew-cask-drivers/pull/2032)
razer-synapse: Update website URL (https://github.com/Homebrew/homebrew-cask-drivers/pull/1435)

This shows the razer-synapse cask that used to exist on homebrew-cask-drivers, and this cask existing is possibly the reason that the 1kc- prefix was originally added to this cask:

• https://github.com/Homebrew/homebrew-cask-drivers/commits/master/Casks/razer-synapse.rb
  • migrated to homebrew-cask-drivers: Migrate 11 Casks to drivers homebrew-cask-drivers#41
    • Casks for migration to caskroom/drivers. homebrew-cask#31782
    • Migrate 11 Casks to drivers homebrew-cask#33303
  • removed: Delete unpopular casks. homebrew-cask-drivers#3443

Looking at the last version of this Cask before it was removed:

• https://github.com/Homebrew/homebrew-cask-drivers/blob/8c493bc0778ad36853e4fbc45a373caa58f1c71b/Casks/razer-synapse.rb

We can see that it links through to the Razer website, and only supports Mac OS X 10.10 - 10.14, so it no longer supports modern macs (and is probably why it was never migrated back to homebrew-cask:

• https://www.razer.com/synapse-2

Given that this conflict was probably the original reasoning for the 1kc- prefix on the main Cask, I wonder if it can now be renamed back to something like razer-macos or razer-macos-unofficial.

---

Reference was also made to the token reference used for naming casks:

• https://docs.brew.sh/Cask-Cookbook#token-reference

By my read of those rules, I think razer-macos would be an ok name, as the app isn't really 'ported' as much as being it's own standalone thing:

Remove from the end: strings such as “Mac”, “for Mac”, “for OS X”, “macOS”, “for macOS”. These terms are generally added to ported software such as “MAME OS X.app”. Exception: when the software is not a port, and “Mac” is an inseparable part of the name, without which the name would be inherently nonsensical, as in PlayOnMac.app.

Even if the -macos suffix isn't ok based on the above rule, then it would become razer, which would then move to the 'special affixes' rules for a 'potentially misleading name':

• https://docs.brew.sh/Cask-Cookbook#special-affixes
• https://docs.brew.sh/Cask-Cookbook#potentially-misleading-name

  • If the token for a piece of unofficial software that interacts with a popular service would make it look official and the vendor is not authorised to use the name, a prefix must be added for disambiguation.

  In cases where the prefix is ambiguous and would make the app appear official, the -unofficial suffix may be used.

Looking at the more specific rules for prefixes:

• https://docs.brew.sh/Acceptable-Casks#forks-and-apps-with-conflicting-names

It sounds like maybe this part was applied in prefixing it with 1kc-:

Forks must have the vendor’s name as a prefix on the cask’s filename and token. If the original software is discontinued, forks still need to follow this rule so as to not be surprising to the user.

But to my knowledge, this isn't a fork, and so it's confusing having it prefixed by the vendor.

While the following docs are for Formula rather than Casks, I figured I'd include it here as the current cask doesn't feel like it is named 'like the project markets the product':

• https://docs.brew.sh/Formula-Cookbook#a-quick-word-on-naming

  • Name the formula like the project markets the product. So it’s pkg-config, not pkgconfig; sdl_mixer, not sdl-mixer or sdlmixer.

---

I also noticed that homebrew-cask has a cask_renames.json, and while it might violate the rules for that usage, I wonder if adding it there would serve as an 'alias':

• https://github.com/Homebrew/homebrew-cask/blob/master/cask_renames.json

---

This PR is very loosely tangentially related, but including here as a reference in case it's helpful:

• Better support renames during tap migrations brew#16252

[0xdevalias]

For historical context, a PR was opened based on this discussion, a bunch of back and forth discussion was had there, and the PR was ultimately closed:

• 1kc-razer: rename to razer-unofficial homebrew-cask#162185

While there was some back and forth on the specifics of cask naming rules, this part about the search/etc aspects was particularly relevant:

I would suggest that the correct solution here is not changing the token but that brew search returns correct results including the name stanza.

According to brew search --help a casks name is only included in the search if you pass the --desc flag. So there is potentially room for improvement here. There is an existing issue in Homebrew/brew discussing handling searching of descriptions better, so noting this there could be helpful.

• upon testing this last thought, it does seem to be functioning incorrectly, which is still a separate issue to this PR.

Originally posted by @bevanjkay in Homebrew/homebrew-cask#162185 (comment)

Regarding the issue in Homebrew/brew that could be somewhat related - Homebrew/brew#16237
Parsing the name text (and desc text, as plain text) may help in this situation. But I would suggest that perhaps consideration could be given to including the name by default in brew search or adding a separate flag, as requiring the use of --desc to search the name is not immediately apparent.

Originally posted by @bevanjkay in Homebrew/homebrew-cask#162185 (comment)

[0xdevalias]

The following comments are relevant for some of the current ambiguities in the docs around naming, that could likely be improved one way or the other depending on what the actual intent of them is:

---

The standard here is that we would use the vendor prefix, unless that doesn't achieve any less ambiguity.

So I still believe that token should remain 1kc-razer.

docs.brew.sh/Acceptable-Casks#forks-and-apps-with-conflicting-names

@bevanjkay It may just be that the way those docs are written is a little ambiguous, but it seems to be 2 different cases, merged into one (which is what I was trying to say earlier about it not being a fork (Ref)):

1. Forks must have the vendor’s name as a prefix...

2. For unrelated apps that share a name, the most popular one (usually the one already present) stays unprefixed. Since this can be subjective, if you disagree with a decision, open an issue and make your case to the maintainers.

As for my suggestion of keeping the -macOS suffix (Ref), it was based on the 'exception to the rule' in this part:

• https://docs.brew.sh/Cask-Cookbook#finding-the-simplified-name-of-the-vendors-distribution

  • Remove from the end: strings such as “Mac”, “for Mac”, “for OS X”, “macOS”, “for macOS”. These terms are generally added to ported software such as “MAME OS X.app”. Exception: when the software is not a port, and “Mac” is an inseparable part of the name, without which the name would be inherently nonsensical, as in PlayOnMac.app.

And that the project specifically markets itself as 'Razer macOS', which matches user expectations in looking for it:

• https://github.com/1kc/razer-macos

The "macOS" suffix seems as much a part of it's name as anything else; it's not describing a port/etc; which is why I believe the exception (described above) is relevant.

That said; I would also be happy to accept razer-unofficial; and if the search stuff worked properly and matched on the name, then I probably would never have had a problem/thought to bring up renaming (or read so deeply into the specifics of the renaming rules) in the first place; so that would probably also make it a 'non-issue' for me.

Originally posted by @0xdevalias in Homebrew/homebrew-cask#162185 (comment)

---

It may just be that the way those docs are written is a little ambiguous, but it seems to be 2 different cases, merged into one (which is what I was trying to say earlier about it not being a fork (Ref)):

I think the issue here is more to do with the way the docs link back to the information about "forks".

The cask cookbook is a bit more direct;

https://docs.brew.sh/Cask-Cookbook#potentially-misleading-name

If the token for a piece of unofficial software that interacts with a popular service would make it look official and the vendor is not authorised to use the name, a prefix must be added for disambiguation.
In cases where the prefix is ambiguous and would make the app appear official, the -unofficial suffix may be used.

Therefore the vendor prefix is used first, then if it's still ambiguous the -unofficial suffix can be considered.

Originally posted by @bevanjkay in Homebrew/homebrew-cask#162185 (comment)

---

@bevanjkay For context; I originally started at the cask cookbook, and followed through to that other page in deciding that the name I was suggesting (Ref) seemed correct.

Therefore the vendor prefix is used first

If that is what the below docs are intending to suggest:

a prefix must be added for disambiguation

Then they could definitely do with a refactor to make that clearer. As currently to me, that reads more like:

If the token for a piece of unofficial software that interacts with a popular service would make it look official and the vendor is not authorised to use the name, go read this for rules about how to disambiguate it.

Phrased differently, as currently written, it comes across that the word "prefix" in the docs seems more of an arbitrary choice of word, and that the canonical rules are defined by the page it links to.

Originally posted by @0xdevalias in Homebrew/homebrew-cask#162185 (comment)

[bevanjkay]

I would suggest that when looking for a cask for an application, that using the shortest identifying word in the application's name would be the way to go.
In this case, searching for razer would yield the result that you are looking for.

Also, just to add some more context to the discussion, it is worth noting that Homebrew Cask does not try to be a "discovery service" - https://docs.brew.sh/Acceptable-Casks#homebrew-cask-is-not-a-discoverability-service
However, it is expected that knowing the name of an application that you would be able to find it's token using brew search.

[0xdevalias]

I would suggest that when looking for a cask for an application, that using the shortest identifying word in the application's name would be the way to go.

Generally that is my approach as well, but I was originally searching for razer-macos in this case, since that is the official brand of the app; to which no results showed up. You can see the specifics of what I tried/the order of in my original post (Ref)

it is worth noting that Homebrew Cask does not try to be a "discovery service"

nods, noted. But not specifically relevant to the issue I had here. My reason for asking about aliasing/renaming/etc was because the existing cask doesn't show up using 'normal' means of finding it, when searching by it's canonical brand name.

However, it is expected that knowing the name of an application that you would be able to find it's token using brew search

Agreed.