This guide goes through the various style issues related to creating a bundle.
If you are going to contribute the bundle to the shared repository of bundles, please read through this entire style guide.
Comments are welcomed!
If the bundle is intended to add support for a specific programming language, it should be named after this language.
If it provides support for a framework or similar used with a specific programming language, the bundle should use the name of the programming language first, and then the name of the framework.
By prefixing the bundle with the name of the language for which the framework is for, the bundle will be close to the language in the Bundles menu, and users who are not familiar with the language or framework, will have a better idea about what it is.
A bundle item which will prompt the user for input or confirmation (normally by opening a dialog) must end with an ellipsis (…). This character is typed using ⌥; (on a US keymap).
A bundle item (command) which works on the selection or a fallback unit should indicate this by using “«unit» / Selection” in the title, for example: “Paste Line / Selection Online…”. When the user is browsing the menu, TextMate will remove the part that does not apply.
Bundle item titles should be title cased as described in Apple’s human interface guidelines:
> Title style means that you capitalize every word > except: > > * Articles (a, an, the) > * Coordinating conjunctions (and, or) > * Prepositions of three or fewer letters, except > when the preposition is part of a verb phrase, > as in “Starting Up the Computer.” > > In title style, always capitalize the first and last > word, even if it is an article, a conjunction, or a > preposition of three or fewer letters.
Keep bundle item titles short but do not sacrifice understandability. We prefer a long title where the user understands what selecting the item will lead to, over something short which requires reading the help file for the bundle.
When finding a key for an action be sure to adhere to the conventions established in other bundles, some of these are listed below.
When you are introducing functionality unparalleled by other bundle’s items, then you may need to find a new key equivalent. Use ⌃⇧ as modifiers, though be aware that the following key equivalents are globally unavailable:
If there is no key available with ⌃⇧ then use ⌃⇧⌘.
Tab triggers should be easy for the user to guess, that means either use the first word of what is inserted (which would often be a language keyword like
while, or similar) or devise a consistent convention, for example just the first 3 letters of what is inserted, if many of the language keywords are too long.
Not having an easy to guess or consistent scheme means that users will generally not be able to use the tab triggers.
All items in a bundle MUST be scoped so that they are only available for the language the bundle caters for.
Even items without a key equivalent or tab trigger should generally be scoped to the language the bundle represents, as the items will otherwise clutter the Select Bundle Item… menu (brought up on ⌃⌘T).
The language grammar should use the first letter of the bundle name with ⌃⌥⇧ as modifiers for its key equivalent. For example Java is ⌃⌥⇧J.
The scope names used in the language grammar MUST conform to the naming conventions mentioned in the manual.
To make it a bit easier, there is a
validate_bundle.rb script in
Support/bin. This is called with a bundle as argument, and will tell you if any of the scope names are not conforming, for example:
cd ~/Library/Application\ Support/TextMate/Bundles ../Support/bin/validate_bundle.rb Java.tmbundle
Any environment variables should be prefixed by
TM_«bundle_name». This is to prevent collisions with other applications or bundles.
bundle_name should be the name of the bundle lowercased with spaces replaced by underscores (_). If the bundle name is exceptionally long a shorter token may be used, but should be used for the entire bundle.
Be sure to edit the menu structure of the bundle. This is done by opening the bundle editor and selecting the bundle itself.
See the Designing the Elements of Menus section of AHIG for tips about how to design menus.
Some general rules of thumb:
Bundles that require setup or where features are not clear from the item titles should contain a help file. Make a command in the bundle called Help without a key equivalent or tab trigger, but still give it a scope selector so that ⌃⌘T + entering
help will show just that item, in the Select Bundle Item… window.
Generally we use Markdown for help files and have them converted on-the-fly using the HTML output option.
If your help is divided into sections, you can use the
$TM_SUPPORT_PATH/lib/markdown_to_help.rb script to have a table of contents generated and sections enumerated. See e.g. LaTeX → Help for an example.
If there is an item for setting the preferences for the bundle it should be named "Preferences…" with a key equivalent of
If you have various files that act to test the grammar/etc they should be located in a directory named "Tests" in the top level of the bundle.
Each bundle needs to contain a contact name / address and a short description.
Currently there is no way to edit (nor view) this from inside TextMate. The info is kept in the bundle’s
info.plist using the following keys:
contactName — The full name of the contact for this bundle.
contactEmailRot13 — A ROT13 encoded email address for the bundle contact (we obfuscate it to avoid spammers from picking up the files, seeing how bundles will often be available via anonymous svn over http).
Hint: TextMate has a ROT13 encryption function in the Mail bundle.
description — A short description for the bundle. Do link to more info about the language (or whatever) the bundle is about. The format is HTML, but do not style the content, only use it for links.
The description will generally be placed inside a
<p>…</p> or it will be shown as plain text, with all tags stripped.
This is from
<key>contactEmailRot13</key> <string>firstname.lastname@example.org</string> <key>contactName</key> <string>Ryan McCuaig</string> <key>description</key> <string><a href="http://www.nemetschek.net/support/custom/vscript/">VectorScript</a> is the scripting language used by the <a href="http://www.nemetschek.net/vectorworks/">VectorWorks</a> CAD software.</string>