Using the Glossary

This section describes BBEdit's powerful Glossary command. The Glossary provides an easy way to store and access frequently used text of any sort, whether sections of program code, HTML markup, or just about anything else. The Glossary's language-sensitive set selection and its ability to perform keyword substitution, combined with an option to run scripts and insert their results, further extends its flexibility and usefulness.

The Glossary Command

Choosing the Glossary command from the Palettes submenu of the Window menu opens the Glossary palette, shown below. This window lists the contents of the active glossary set, plus the contents of the Universal Items glossary set and any glossary items contained directly within the Glossary folder (that is, which do not belong to a set). Names that are too long to fit within the width of the window are truncated with ellipses (...).

"Hovering" the mouse over such a truncated name displays a tool tip showing the full name. If you hold down the Option key, the tool tip will appear instantly, with no hovering delay. Names that fit entirely within the window without truncation do not display a tool tip.

To create a glossary item, type or paste the desired text, or text and keywords, into a BBEdit document window and then save the text into an appropriate place within the Glossary folder.

The standard location of the Glossary folder is "~/Library/Application Support/BBEdit/Glossary/". You can create multiple levels of subfolders inside the Glossary folder, to better organize different types of content. The first level of such subfolders appear in the Set pop-up menu of the Glossary window, allowing you to reveal only the group of glossary items you wish to work with at a given time. (Any glossary items that are not placed in a subfolder are always shown in the Glossary window, as are the contents of the Universal Items set.)

Language Sensitivity of the Glossary

If you have selected the Glossary Is Language Sensitive option in the Glossary preference panel, BBEdit will select a glossary set to use with the current document according to the following rules:

These selection rules are intended to provide maximum flexibility while automatically doing the right thing as often as possible.

Manually Sorting the Glossary

By default, the Set pop-up menu displays glossary sets in alphabetical order. However, you can force them to appear in any desired order by including any two characters followed by a right parenthesis at the beginning of their name: for example "00)Web template" would sort before "01)HTML Template". The first three characters of such names are not displayed in the menu. You can also insert a divider by including an empty folder whose name ends with the string "-***". (You can use anything you want for the rest of the name, to make it appear where you want it in the menu.) These conventions are the same as those used by the utilities FinderPop and OtherMenu.

Inserting Glossary Items

Double-clicking an item's name in the Glossary window inserts its contents at the insertion point or in place of the current selection. Alternatively, you can click the item's name once to select it and then click the Insert button, or drag the item directly to the desired location in the document window.

Note

If you hold down the Option key, the Insert button changes to Edit, allowing you to open the file corresponding to the selected item so you can edit it; you can also do the same thing by Option-double-clicking the item directly.

The Insert Glossary Entry command in the Edit menu brings up a dialog window in which you can select a glossary item and insert it at the insertion point (or in place of the current selection) with the Insert button. You can move quickly to an item in this window by typing its first few letters from the keyboard, or by using Tab and Shift-Tab to navigate forward and backward through the list.

Another way to insert a glossary item is with the Auto-Complete Glossary command in the Edit menu. If there is a current selection, BBEdit will look for and insert a glossary item whose name begins with the selected text. (If there is more than one such item, BBEdit will display the Insert Glossary Entry dialog to allow you to choose one; if there are no matching glossary items, it will beep to signal an error.) If no text is currently selected, BBEdit will scan backward from the insertion point to the nearest non-alphanumeric character and match that text in the same manner. This allows you to quickly insert a glossary item "on the fly" by typing the first few letters of its name and choosing Auto-Complete Glossary from the menu.

IMPORTANT

To make the most of "Insert Glossary Entry" and "Auto-Complete Glossary", we recommend that you assign key equivalents to these commands by using the Set Menu Keys command on the BBEdit menu.

Assigning Key Equivalents to Glossary Items

The Set Key button in the Glossary window lets you assign key equivalents for easy access to frequently used glossary items. To assign a key to a glossary item:

  1. Select the item in the Glossary window.
  2. Click the Set Key button to display the Set Key dialog.
  3. Type the key equivalent.
  4. You can use any combination of the Command, Shift, Option, and Control keys in the key equivalent, provided that it must use at least the Command or Control key to be valid. You can also use function keys, with or without additional modifiers.

  5. Click OK.
Note

If you try to assign a key equivalent that is already used elsewhere, BBEdit warns you that there is a conflict and asks you whether you want to reassign that key equivalent to the new item.

To remove a key equivalent from a glossary item:

  1. Select the item in the Glossary window.
  2. Click the Set Key button to display the Set Key dialog.
  3. Click Reset, then OK.

Glossary Substitutions

When you insert a glossary item containing a placeholder into an editing window, BBEdit replaces the placeholder with appropriate substitution text. This is similar to the operation of BBEdit's HTML Templates and Update features. The following table shows the placeholders you can use in a glossary item:

Placeholder

Replaced by...

#BASENAME#

The name of the file stripped of its rightmost period-delimited portion. For example, if the file is named "test.html", the base name is "test", while if the file is named "test.foo.html", the base name is "test.foo".

#CLIPBOARD#

Contents of the current clipboard

#DATE#

Current date, formatted according to your Format settings in the International panel of the System Preferences

#FILE#

File name of the document into which the item is inserted

#FILE_EXTENSION#

The filename extension for the file (determined as the rightmost period-delimited portion of the filename, without the period). For example, whether the file is named "test.html" or "test.foo.html", the filename extension is "html".

#FUNCTION#

If the item is being inserted into a source file, the name of the current function

#GMTIME XXX#

The current GMT time formatted according to the parameters XXX (see "Time Formats" below)

#INDENT#

When used in a glossary item with multiple lines, causes every line after the first to be indented to the same whitespace level as the line in which the item was inserted (see the supplied WML glossary for examples)

#INLINE#

Strips all trailing vertical white space from the item before insertion (see also the Glossary preference panel)

#INSERTION#

Marks the place where BBEdit will place the insertion point after inserting the item; if multiple #INSERTION# placeholders are used, the second and subsequent occurrences are replaced with a placeholder "<##>", which can be used with Go to Next/Previous Placeholder in the Search menu

#LOCALTIME XXX#

The current local time formatted according to the parameters XXX (see "Time Formats" below)

#NAME#

The Short Name of the active user account

#SCRIPT filename#

Result of running the specified AppleScript

#SELECT#

Selected text

#SELSTART#

and

#SELEND#

Mark a range within the inserted material to be selected after the insertion

#TIME#

Current time, formatted according to your Format settings in the International panel of the System Preferences

#UUID#

A 128-bit UUID (universally unique identifier), formed by combining a value unique to the computer on which it was generated (usually the Ethernet hardware address) with a value representing the number of 100-nanosecond intervals since October 15, 1582

Placeholders are not case-sensitive. If you want to include a literal placeholder in a glossary item, escape the first # with a backslash, as in \#DATE#.

Selection and Insertion Placeholders

In BBEdit 8, you can use multiple #SELSTART#/#SELEND# pairs together with any number of #insertion# placeholders.

Example:

Suppose you have defined the following glossary item:

typedef struct #SELECT#

{

#INSERTION#

} #SELECT#, *#SELECT#Ptr, **#SELECT#Handle;

If the selected text in your editing window is "MyStruct" and you insert this glossary item, BBEdit will insert the following in the editing window:

typedef struct MyStruct

{

|

} MyStruct, * MyStruct Ptr, ** MyStruct Handle;

(where the vertical bar marks the point at which the blinking insertion point will be placed).

Temporary Placeholder Formats

In previous versions of BBEdit, the Glossary would generate temporary placeholders of the form "#·#" for items containing multiple instances of #INSERTION#. However, since the bullet character cannot be represented in all character encodings, BBEdit now generates temporary placeholders of the form "<##>".

If you have created glossary items which directly employ the old temporary placeholder format , you will need to modify them to use #INSERTION# instead.

Time Formats

The #GMTIME XXX# and #LOCALTIME XXX# placeholders offer you the option to insert the specified time value with flexible formatting.

In order to use these placeholders, you must substitute a time format using the same expansion options offered by the `strftime' routine (see `man strftime' for further details).

Examples:

#LOCALTIME %r %z on %A# produces: 06:50:13 PM -0400 on Monday

#GMTIME %r %z# produces: 10:50:13 PM +0000

Using Scripts with the Glossary

The placeholder #script filename# provides a powerful means to insert variable or conditional content by allowing access to any compiled AppleScript, or Unix shell script, from within a glossary item.

The script itself can either be located in the same folder as the glossary item that invokes it (in which case you need only specify its name, such as "MyDateScript") or you can supply a full pathname to a script on any mounted volume (such as "Hard Drive:My Project:Scripts:MyDateScript"). An instance of a placeholder referencing the latter would be

#script Hard Drive:My Project:Scripts:MyDateScript#

The script must return a text string (or a value that can be coerced to a string). This result string can itself contain additional glossary placeholders, which will be interpreted before the item is inserted in the current document.

WARNING

Note that this makes it possible for one script to invoke another. Take care not to create a script execution loop, which would hang your system!