2014-11-29 03:36:16 +08:00
|
|
|
# Cask Token Reference
|
2014-01-18 00:23:31 +08:00
|
|
|
|
2014-11-29 03:36:16 +08:00
|
|
|
This document describes the algorithm implemented in the `generate_cask_token`
|
2014-01-18 00:23:31 +08:00
|
|
|
script, and covers detailed rules and exceptions which are not needed in
|
|
|
|
most cases.
|
|
|
|
|
2014-11-27 02:01:02 +08:00
|
|
|
* [Purpose](#purpose)
|
2014-11-29 03:36:16 +08:00
|
|
|
* [Finding the Simplified Name of the Vendor's Distribution](#finding-the-simplified-name-of-the-vendors-distribution)
|
|
|
|
* [Converting the Simplified Name To a Token](#converting-the-simplified-name-to-a-token)
|
|
|
|
* [Cask Filenames](#cask-filenames)
|
|
|
|
* [Cask Headers](#cask-headers)
|
|
|
|
* [Cask Token Examples](#cask-token-examples)
|
2014-01-18 00:23:31 +08:00
|
|
|
|
2014-11-27 02:01:02 +08:00
|
|
|
## Purpose
|
|
|
|
|
|
|
|
The purpose of these stringent conventions is to
|
|
|
|
|
2014-11-29 03:36:16 +08:00
|
|
|
* unambiguously boil down the name of the software into a unique identifier
|
2014-11-27 02:01:02 +08:00
|
|
|
* minimize renaming events
|
|
|
|
* prevent duplicate submissions
|
|
|
|
|
2014-11-29 03:36:16 +08:00
|
|
|
The token itself should be
|
|
|
|
|
|
|
|
* suitable for use as a filename
|
|
|
|
* mnemonic
|
|
|
|
|
|
|
|
Details of software names and brands will inevitably be lost in the
|
|
|
|
conversion to a minimal token. To capture the vendor's full name for a
|
2014-12-05 06:56:43 +08:00
|
|
|
distribution, use the [`name`](CASK_LANGUAGE_REFERENCE.md#name-stanza-details) within a Cask.
|
|
|
|
`name` accepts an unrestricted UTF-8 string.
|
2014-11-27 02:01:02 +08:00
|
|
|
|
2014-11-29 03:36:16 +08:00
|
|
|
## Finding the Simplified Name of the Vendor's Distribution
|
2014-01-18 00:23:31 +08:00
|
|
|
|
2014-11-29 03:36:16 +08:00
|
|
|
### Simplified Names of Apps
|
2014-01-18 00:23:31 +08:00
|
|
|
|
|
|
|
* Start with the exact name of the Application bundle as it appears on disk,
|
2014-11-27 02:01:02 +08:00
|
|
|
such as `Google Chrome.app`.
|
|
|
|
|
|
|
|
* If the name uses letters outside A-Z, convert it to ASCII as described in
|
|
|
|
[Converting to ASCII](#converting-to-ascii).
|
|
|
|
|
|
|
|
* Remove `.app` from the end.
|
|
|
|
|
2014-11-29 03:36:16 +08:00
|
|
|
* Remove from the end: the string "app", if the vendor styles the name
|
2014-11-27 02:01:02 +08:00
|
|
|
like "Software App.app". Exception: when "app" is an inseparable part of the
|
|
|
|
name, without which the name would be inherently nonsensical, as in [rcdefaultapp.rb](../Casks/rcdefaultapp.rb).
|
|
|
|
|
2014-01-18 00:23:31 +08:00
|
|
|
* Remove from the end: version numbers or incremental release designations such
|
|
|
|
as "alpha", "beta", or "release candidate". Strings which distinguish different
|
|
|
|
capabilities or codebases such as "Community Edition" are currently accepted.
|
|
|
|
Exception: when a number is not an incremental release counter, but a
|
2014-11-27 02:01:02 +08:00
|
|
|
differentiator for a different product from a different vendor, as in [pgadmin3.rb](../Casks/pgadmin3.rb).
|
|
|
|
|
2014-01-18 00:23:31 +08:00
|
|
|
* If the version number is arranged to occur in the middle of the App name,
|
|
|
|
it should also be removed. Example: [IntelliJ IDEA 13 CE.app](../Casks/intellij-idea-ce.rb).
|
2014-11-27 02:01:02 +08:00
|
|
|
|
2015-01-29 21:54:06 +08:00
|
|
|
* Remove from the end: "Launcher", "Quick Launcher".
|
|
|
|
|
2014-11-27 02:01:02 +08:00
|
|
|
* Remove from the end: strings such as "Mac", "for Mac", "for OS X".
|
|
|
|
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](../Casks/playonmac.rb).
|
|
|
|
|
2014-01-18 00:23:31 +08:00
|
|
|
* Remove from the end: hardware designations such as "for x86", "32-bit", "ppc".
|
2014-11-27 02:01:02 +08:00
|
|
|
|
|
|
|
* Remove from the end: software framework names such as "Cocoa", "Qt",
|
|
|
|
"Gtk", "Wx", "Java", "Oracle JVM", etc. Exception: the framework is the
|
|
|
|
product being Casked: [java.rb](../Casks/java.rb).
|
|
|
|
|
2014-01-18 00:23:31 +08:00
|
|
|
* Remove from the end: localization strings such as "en-US"
|
2014-11-27 02:01:02 +08:00
|
|
|
|
|
|
|
* If the result of that process is a generic term, such as "Macintosh Installer",
|
|
|
|
try prepending the name of the vendor or developer, followed by a hyphen.
|
|
|
|
If that doesn't work, then just create the best name you can, based on the
|
2014-11-29 03:36:16 +08:00
|
|
|
vendor's web page.
|
2014-11-27 02:01:02 +08:00
|
|
|
|
2014-01-18 00:23:31 +08:00
|
|
|
* If the result conflicts with the name of an existing Cask, make yours unique
|
2014-11-27 02:01:02 +08:00
|
|
|
by prepending the name of the vendor or developer, followed by a hyphen.
|
2014-01-18 00:23:31 +08:00
|
|
|
Example: [unison.rb](../Casks/unison.rb) and [panic-unison.rb](../Casks/panic-unison.rb).
|
2014-11-27 02:01:02 +08:00
|
|
|
|
2014-01-18 00:23:31 +08:00
|
|
|
* Inevitably, there are a small number of exceptions not covered by the rules.
|
2014-11-27 02:01:02 +08:00
|
|
|
Don't hesitate to [contact the maintainers](../../../issues) if you have a
|
|
|
|
problem.
|
|
|
|
|
|
|
|
### Converting to ASCII
|
|
|
|
|
|
|
|
* If the vendor provides an English localization string, that is preferred.
|
|
|
|
Here are the places it may be found, in order of preference:
|
|
|
|
|
|
|
|
* `CFBundleDisplayName` in the main `Info.plist` file of the app
|
|
|
|
bundle
|
|
|
|
|
|
|
|
* `CFBundleName` in the main `Info.plist` file of the app bundle
|
|
|
|
|
|
|
|
* `CFBundleDisplayName` in `InfoPlist.strings` of an `en.lproj`
|
|
|
|
localization directory
|
|
|
|
|
|
|
|
* `CFBundleName` in `InfoPlist.strings` of an `en.lproj` localization
|
|
|
|
directory
|
|
|
|
|
|
|
|
* `CFBundleDisplayName` in `InfoPlist.strings` of an `English.lproj`
|
|
|
|
localization directory
|
|
|
|
|
|
|
|
* `CFBundleName` in `InfoPlist.strings` of an `English.lproj`
|
|
|
|
localization directory
|
|
|
|
|
|
|
|
* When there is no vendor localization string, romanize the name by
|
|
|
|
transliteration or decomposition.
|
|
|
|
|
2014-11-29 03:36:16 +08:00
|
|
|
* As a last resort, translate the name of the app bundle into English.
|
2014-01-18 00:23:31 +08:00
|
|
|
|
2014-11-29 03:36:16 +08:00
|
|
|
### Simplified Names of `pkg`-based Installers
|
2014-01-18 00:23:31 +08:00
|
|
|
|
2014-11-29 03:36:16 +08:00
|
|
|
* The Simplified Name of a `pkg` may be more tricky to determine than that
|
2014-01-18 00:23:31 +08:00
|
|
|
of an App. If a `pkg` installs an App, then use that App name with the
|
|
|
|
rules above. If not, just create the best name you can, based on the
|
2014-11-29 03:36:16 +08:00
|
|
|
vendor's web page.
|
2014-01-18 00:23:31 +08:00
|
|
|
|
2014-11-29 03:36:16 +08:00
|
|
|
### Simplified Names of non-App Software
|
2014-01-18 00:23:31 +08:00
|
|
|
|
2014-11-29 03:36:16 +08:00
|
|
|
* Currently, rules for generating a token are not well-defined for
|
|
|
|
Preference Panes, QuickLook plugins, and several other types of software
|
|
|
|
installable by homebrew-cask. Just create the best name you can, based
|
|
|
|
on the filename on disk or the vendor's web page. Watch out for
|
|
|
|
duplicates.
|
2014-01-18 00:23:31 +08:00
|
|
|
|
2014-11-29 03:36:16 +08:00
|
|
|
Non-app tokens should become more standardized in the future.
|
2014-01-18 00:23:31 +08:00
|
|
|
|
2014-11-29 03:36:16 +08:00
|
|
|
## Converting the Simplified Name To a Token
|
2014-01-18 00:23:31 +08:00
|
|
|
|
2014-11-29 03:36:16 +08:00
|
|
|
The token is the primary identifier for a package in our project. It's
|
|
|
|
the unique string users refer to when operating on the Cask.
|
2014-01-18 00:23:31 +08:00
|
|
|
|
2014-11-29 03:36:16 +08:00
|
|
|
To convert the App's Simplified Name (above) to a token:
|
2014-01-18 00:23:31 +08:00
|
|
|
|
|
|
|
* convert all letters to lower case
|
2014-05-09 21:32:47 +08:00
|
|
|
* expand the `+` symbol into a separated English word: `-plus-`
|
2014-12-29 22:41:47 +08:00
|
|
|
* expand the `@` symbol into a separated English word: `-at-`
|
2014-01-18 00:23:31 +08:00
|
|
|
* spaces become hyphens
|
2014-12-06 00:40:52 +08:00
|
|
|
* hyphens stay hyphens
|
2014-01-18 00:23:31 +08:00
|
|
|
* digits stay digits
|
|
|
|
* delete any character which is not alphanumeric or hyphen
|
|
|
|
* collapse a series of multiple hyphens into one hyphen
|
2014-12-06 00:40:52 +08:00
|
|
|
* delete a leading or trailing hyphen
|
2014-01-18 00:23:31 +08:00
|
|
|
|
2014-11-29 03:36:16 +08:00
|
|
|
We avoid defining Cask tokens in the repository which differ only by the
|
|
|
|
placement of hyphens. Prepend the vendor name if needed to disambiguate
|
|
|
|
the token.
|
|
|
|
|
|
|
|
## Cask Filenames
|
|
|
|
|
|
|
|
Casks are stored in a Ruby file named after the token, with the file
|
|
|
|
extension `.rb`.
|
|
|
|
|
|
|
|
## Cask Headers
|
2014-01-18 00:23:31 +08:00
|
|
|
|
2014-11-29 03:36:16 +08:00
|
|
|
The token is also given in the header line for each Cask.
|
2014-01-18 00:23:31 +08:00
|
|
|
|
2014-11-29 03:36:16 +08:00
|
|
|
## Cask Token Examples
|
2014-01-18 00:23:31 +08:00
|
|
|
|
2014-11-29 03:36:16 +08:00
|
|
|
These illustrate most of the rules for generating a token:
|
2014-01-18 00:23:31 +08:00
|
|
|
|
2014-11-29 03:36:16 +08:00
|
|
|
App Name on Disk | Simplified App Name | Cask Token | Filename
|
|
|
|
-----------------------|---------------------|------------------|----------------------
|
|
|
|
`Audio Hijack Pro.app` | Audio Hijack Pro | audio-hijack-pro | `audio-hijack-pro.rb`
|
|
|
|
`VLC.app` | VLC | vlc | `vlc.rb`
|
|
|
|
`BetterTouchTool.app` | BetterTouchTool | bettertouchtool | `bettertouchtool.rb`
|
|
|
|
`LPK25 Editor.app` | LPK25 Editor | lpk25-editor | `lpk25-editor.rb`
|
|
|
|
`Sublime Text 2.app` | Sublime Text | sublime-text | `sublime-text.rb`
|
2014-01-18 00:23:31 +08:00
|
|
|
|
|
|
|
|
|
|
|
# <3 THANK YOU TO ALL CONTRIBUTORS! <3
|