Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

doc: update CASK_NAMING_REFERENCE.md #7643

Merged
merged 1 commit into from
Nov 28, 2014
Merged

doc: update CASK_NAMING_REFERENCE.md #7643

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
125 changes: 93 additions & 32 deletions doc/CASK_NAMING_REFERENCE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,44 +4,104 @@ This document describes the algorithm implemented in the `cask_namer`
script, and covers detailed rules and exceptions which are not needed in
most cases.

* [Find the Canonical Name of the Developer's Distribution](#find-the-canonical-name-of-the-developers-distribution)
* [Purpose](#purpose)
* [Finding the Canonical Name of the Developer's Distribution](#finding-the-canonical-name-of-the-developers-distribution)
* [Cask Name](#cask-name)
* [Cask Naming Examples](#cask-naming-examples)

## Find the Canonical Name of the Developer's Distribution
## Purpose

The purpose of these stringent conventions is to

* unambiguously boil down the name of the software into a unique token
suitable for use as a filename
* minimize renaming events
* prevent duplicate submissions

Details of various names and brands will inevitably be lost in the
conversion to a Cask name. To capture the vendor's full name for a
distribution, use [`tags :name`](CASK_LANGUAGE_REFERENCE.md#tags-stanza-details) within a Cask.

## Finding the Canonical Name of the Developer's Distribution

### Canonical Names of Apps

* Start with the exact name of the Application bundle as it appears on disk,
such as `Google Chrome.app`
* Translate the name into English if necessary
* Remove `.app` from the end
* Remove the term "app" from the end, if the developer styles the name like
"Software App.app". Exception: if the term "app" describes functionality,
as in [rcdefaultapp.rb](../Casks/rcdefaultapp.rb).
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.

* Remove from the end: the string "app", if the developer styles the name
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).

* 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
differentiator for a different product from a different vendor: [pgadmin3.rb](../Casks/pgadmin3.rb).
differentiator for a different product from a different vendor, as in [pgadmin3.rb](../Casks/pgadmin3.rb).

* 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).
* Remove from the end: "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, but "Mac" is an inseparable part of the name, without which the
name would not make sense, for example [PlayForMac.app](../Casks/playformac.rb).

* 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).

* Remove from the end: hardware designations such as "for x86", "32-bit", "ppc".
* 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).

* 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).

* Remove from the end: localization strings such as "en-US"

* Pay attention to details, for example: `"Git Hub" != "git_hub" != "GitHub"`
* If the result of that process is something unhelpful, such as `Macintosh Installer`,
then just create the best name you can, based on the developer's web page.

* 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
developer's web page.

* If the result conflicts with the name of an existing Cask, make yours unique
by prepending the name of the vendor or developer, followed by a separator.
by prepending the name of the vendor or developer, followed by a hyphen.
Example: [unison.rb](../Casks/unison.rb) and [panic-unison.rb](../Casks/panic-unison.rb).

* Inevitably, there are a small number of exceptions not covered by the rules.
Don't hesitate to [contact the maintainers](../../../issues) if you have a problem.
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.

* As a last resort, translate the name of the app bundle.

### Canonical Names of `pkg`-based Installers

Expand All @@ -57,13 +117,14 @@ most cases.
homebrew-cask. Just create the best name you can, based on the filename
on disk or the developer's web page. Watch out for duplicates.

Non-app Cask names should become more standardized in the future.

## Cask Name

The "Cask name" is the primary identifier for a package in our project. It's
the string people will use to interact with the Cask on their system.
the token users will refer to when operating on the Cask.

To get from the App's canonical name to the Cask name:
To convert the App's canonical name (above) to a Cask name:

* convert all letters to lower case
* expand the `+` symbol into a separated English word: `-plus-`
Expand All @@ -73,24 +134,24 @@ To get from the App's canonical name to the Cask name:
* delete any character which is not alphanumeric or hyphen
* collapse a series of multiple hyphens into one hyphen
* delete a leading hyphen
* a leading digit gets spelled out into English: `1password` becomes `onepassword`
* a leading number gets spelled out into English: `1password` becomes `onepassword`

Casks are stored in a Ruby file matching their name. If possible, avoid creating
Cask files which differ only by the placement of hyphens.
Casks are stored in a Ruby file matching their name. If possible, avoid
creating Cask files which differ only by the placement of hyphens.


## Cask Naming Examples

These illustrate most of the naming rules:

App Name on Disk | Canonical App Name | Cask Name | Cask File
-----------------------|--------------------|--------------------|----------------------
`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`
`1Password.app` | 1Password | `onepassword` | `onepassword.rb`
App Name on Disk | Canonical App Name | Cask Name | Cask File
-----------------------|--------------------|------------------|----------------------
`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`
`1Password.app` | 1Password | onepassword | `onepassword.rb`


# <3 THANK YOU TO ALL CONTRIBUTORS! <3