The Alpha Manual
Alpha
Version:9.2.3 - "Suhail"
Last update:2021-05-21 14:43:28



This is the main user's guide for the Alpha text editor. This manual is always being updated, and is (always) about 90% finished! In case of doubt, don't hesitate to ask questions on the Alpha's Mailing Lists. For a more basic overview, see the file Quick Start
Many more specialized topics have their own help pages: see Alpha Help Topics. All the Alpha packages and extensions also have a documentation of their own, accessible through the Help menu of the application.

Introduction

Alpha is a very powerful, multi-purpose text editor.
Here are a few concepts you should be aware of: For help on mode-specific issues, consult the mode help file --- pressing ⌃-Help opens the help file for the active mode, alternatively you may use the Help ↣ Modes Help submenu. Selecting the menu item Alpha ↣ Mode Setup ↣ Describe Mode will provide more technical information regarding the mode.

How to navigate the documentation

This document contains a lot of hyperlinks to facilitate the navigation or the understanding of the concepts. Some links will let you quickly jump between different sections of the manual. Others will trigger actions in Alpha itself (like displaying dialogs, opening files, etc.)
For instance, hyperlinks of the form "See the Appearance Preferences panel" will open the corresponding preference dialog directly in Alpha (try it!).
This manual is divided into four major sections. The first one deals primarily with Alpha's Menus, Basic Editing, and other text manipulation issues. The second addresses some User interface details more specific to Alpha, such as file marking, window management, and information providers like Shift-Command-Double-Clicking. The third section introduces Modes and Packages, including some of the Menus and Features that are available in the AlphaTcl library. These are the items that set Alpha apart from most text editors available --- many of these features are addressed in greater detail in other Help files/windows. Information on The Command Line is also presented. The final section contains information on changing or extending Alpha's behavior.

Differences between 'Alpha' and 'AlphaTcl'

The program Alpha has two parts: one compiled binary part and a big library of scripts written in the scripting language Tcl (Dr. John Ousterhout's Tool Command Language). The binary part (aka the core) handles windows, mouse movements, text drawing and all such, and then it has a built-in Tcl interpreter which drives the second part (aka the AlphaTcl library), the vast library of Tcl scripts that provide most of Alpha's functionality. Most editing functions, actions taken when a menu item is selected or a key combination is pressed, and all of Alpha's packages and extensions are implemented in Tcl. With this design it is easy to configure and extend Alpha --- anybody can tweak Alpha's behavior by modifying Tcl functions, or extend Alpha by writing a new package!
Alpha's source code, including the AlphaTcl library, is open source and available on sourceforge.net. It is known as the AlphaCocoa project because the core is built on Apple's Cocoa framework.
Of course, you don't have to learn Tcl to use Alpha --- Alpha is designed to be operated through a graphical user interface, and in normal operation you will never be confronted with Tcl. But if you want to become a real power user, you should consider taking a look at Tcl --- it is one of the easiest scripting languages to learn. Then the possibilities of customizing Alpha are unlimited.

Alpha's Menus

This section is an explanation of Alpha's main menus, from Alpha to Windows (menu with the windows icon):
Alpha main menus
The menu items listed here are the ones available when no additional features have been turned on by using the menu item Alpha ↣ Global Setup ↣ Features. Some of these features add new menu items or new submenus to Alpha's main menus. See the Features Preferences dialog.
Alpha's has dynamic menus, which means that the menu items displayed may change when a modifier key is held down while selecting the menu. The alternate items are always variants of the item they substitute: for example, in the File menu, the item Close becomes Close All when the option key (⌥) is held down.

Alpha Menu

About Alpha
Displays some info about the software
Preferences
Set global preferences.
Global Preferences
The first item is used to set specific global preferences.
Package Preferences
This item opens a multi-paned dialog which contains preferences for different packages that you have already activated. Other package might add additional submenus in this section as well.
Edit Prefs File
Put your own arbitrary startup code here. Loaded after all standard Tcl code.
Color Definitions
Redefine basic colors.
Electric Expansions
View, add, edit, remove global expansions.
Electric Completions
View, add, edit, remove global completions.
Identities
Handle identities.
View Saved Setting…
Any variables or flags that you modify during the course of a session are saved to files in the system preferences folder when Alpha quits. This function shows all such saved variables.
Remove Saved Setting…
This function allows settings to be removed.
Search For Setting…
Query a specific setting
Show Prefs Folder
Reveal the Prefs folder in the Finder
Show User Packages
Alpha also allows you to create a new folder in which you can add additional packages.
Show Support Folder…
Reveal a support folder in the Finder
Rebuild Caches…
The Alpha's index of all installed packages.
Global Setup
Set global environment options.
Menus…
Change global menus.
Features…
Change global features.
Helper Applications…
Set the signature/path of applications with which Alpha interacts.
Setup Assistant…
Opens the series of dialogs that appeared when you launched Alpha for the first time, allowing to adjust your global settings.
File Mappings…
Displays and allows editing of suffixes (really filename patterns) for all existing modes.
Preferred Mapping…
Select the preferred mode associated with a suffix (when a suffix is claimed by different modes)
Arrange Menus…
Change the order of globally activated menus that appear in the menu bar
Keyboard Shortcuts
Special Keys…
Set keyboard shortcuts for electric features.
Describe Shortcut…
Wait for a keystroke, then display the AlphaTcl procedure bound to the shortcut.
Menu Shortcuts…
Open the preferences Menu Shortcuts Preferences panel panel.
List Global Shortcuts
List all current global keyboard shortcuts.
List Mode Shortcuts
List all current shortcuts for the current mode.
List All Shortcuts
List all current keyboard shortcuts.
Update AlphaTcl
User Update
One-time update of the AlphaTcl Library from the subversion repository.
Developer Checkout
Checkout (in the sense of Subversion) of the AlphaTcl Library. See Update Alpha Tcl Help.
Developer Update
Update (in the sense of Subversion) the AlphaTcl Library.
Browse AlphaTcl Repository
Browse the Library on the internet.
AlphaTcl Repository Info
Display some technical info about the repository.
AlphaTcl Update Help
Open a Help document.
Create New Mode…
Opens a series of dialogs to create a new mode that will be permanently saved.
Mode Setup
Set preferences for current mode. This item really is named something like XXX Mode Setup where XXX is the name of the current mode. If no document window is opened, the menu item is dimmed.
Menus…
Change current mode's menus and features.
Features…
Change current mode's menus and features.
Preferences…
Change options for current mode.
Edit Prefs File
Edit mode-specific preferences. Loaded after mode entered for the first time.
Load Prefs File
Load current mode's preferences.
Mode Help
Get help about the current mode.
Describe mode
Describe current mode's variable settings and keyboard shortcuts.
Edit Tutorial
Open a Tutorial for editing in this mode.
Services
The standard OSX Services menu.
Hide Alpha
Hide all Alpha windows.
Hide Others
Hide the windows of all other applications.
Show All
Show the windows that were previously hidden.
Quit Alpha
Quit the application.

File Menu

New
New file.
Open…
Open file.
Open Via Fileset… (with ⌥ key)
Open a file via a fileset.
Open Remote… (with ⌃ key)
Open a file from a remote filesystem.
Close
Close file.
Close All (with ⌥ key)
Close all files.
Close Palette
Close the most recently opened floating palette.
Close All Palettes (with ⌥ key)
Close all open floating palettes.
Save
Save file.
Save All (with ⌥ key)
Save all files.
Save Unmodified (with ⌃ key)
Save file without changing the modification date.
Save As…
Prompt for name to same file under.
Rename To… (with ⌥ key)
Rename file.
Save A Copy As…
Save a copy of the open window.
Revert To Saved…
Revert to last saved version, throw away undo history.
File Utilities
File Remove…
Remove a file.
Hex Dump…
Display the data of a selected file in hexadecimal and ASCII format.
File Info…
Display/edit info about a file.
Convert Eols…
Convert end-of-line characters for a selected folder into Mac, Windows, or Unix formats.
Show in Finder
Select the front window in the Finder.
Text to Alpha…
Set creator of text files in a folder to Alpha.
View Macroman Translation…
Attempt to translate current file from other encoding into MacRoman. Will open translation in a new untitled window.
Page Setup…
Set print options.
Print…
Print window.
Print All (with ⌥ key)
Print all windows.

Edit Menu

Undo
Undo last action.
Redo
Redo last undone action.
Cut
Cut selection to Clipboard.
Copy
Copy selection to Clipboard.
Paste
Paste from Clipboard.
Delete
Delete selection.
Zap Non Printables
Delete all chars in file with ASCII code < 32, except for LF, TAB and CR.
Select All
Select entire file.
Select Paragraph (with ⌥ key)
Select current paragraph.
Balance
Select text out to the next set of matching braces.
Tab Conversions
All Tabs To Spaces
Converts all tabs to space runs.
All Spaces To Tabs
Converts all space strings to tabs.
Leading Tabs To Spaces
Converts leading tabs to space runs.
Leading Spaces To Tabs
Converts leading space strings to tabs.
Indent
Indent the current line or selection.
Shift Left
Shift selection left one tab.
Shift Left Space (with ⌥ key)
Shift selection left one space.
Shift Right
Shift selection right one tab.
Shift Right Space (with ⌥ key)
Shift selection right one space.
Spelling
See help for the package Spellcheck .
Speech
See help for the package Speech .
Special Characters
See help for the package Special Characters .

Text Menu

Fill Paragraph
"Fill" paragraph that contains the cursor.
Wrap Paragraph (with ⌥ key)
Break lines longer than 'fillColumn' in paragraph containing the cursor.
Sentence Paragraph
Inserts a line break at the end of each sentence in the current paragraph
Line To Paragraph
Convert a line to a paragraph.
Paragraph to Line (with ⌥ key)
Convert a paragraph to single line.
Sort Lines
Sort selected lines.
Reverse Sort (with ⌥ key)
Sort selected lines backwards.
Twiddle
Exchange characters bracketing the selection point.
Twiddle Words (with ⌥ key)
Exchange words bracketing the selection point.
Upcase Region
Upcase all chars in region.
Downcase Region (with ⌥ key)
Downcase all chars in region.
Comment Line
Comment out line, considering mode.
Uncomment Line (with ⌥ key)
Un-comment line, considering mode.
Comment Box
Create a comment box around selected text.
Uncomment Box (with ⌥ key)
Remove such a comment box.
Comment Paragraph
Comment out a paragraph.
Uncomment Paragraph
Uncomment a paragraph. See the package Comments for more information.

Text Options Submenu

This submenu lets you enable/disable automatic text checking options for the current window. The options you enable in this menu apply to the current document only while it is opened. In order to set these options at the application's level, see the Document Preferences panel and the Text Preferences panel. Note that the actions resulting from text checking are undoable.
The available options are:
Coloring
Continuous Spell Checking
Dash Substitution
Data Detection
Grammar Checking
Link Detection
Quote Substitution
Smart Insert Delete
Spelling Correction
Text Replacement
The menu item Check Document can be used to force an immediate check of the entire document (for the enabled options). This should normally not be necessary as Alpha triggers a document checking automatically when an option is enabled.

Search Menu

Find…
Present a search dialog.
Find Again
Search forward again with same settings.
Find Again Backward (with ⌥ key)
Search backward again with same settings.
Find in Next File
Restart multiple-file search in next file after stopping at a match.
Enter Search String
Use the current selection as the search text.
Enter Replace String (with ⌥ key)
Use the current selection as replace text.
Replace
Replace the selection.
Replace and Find Again
Replace the selection and search again forward.
Replace All
Replace all of occurrences of the search string in the rest of the file.
Quick Find
Incremental search forward (grep, match words off, ignore case on). Type chars to define string, control-w adds the current word to the search string, control-s/r search for the same string again.
Quick Find Regexp (with ⌥ key)
Same as Quick Find but lets you use a regular expression.
Reverse Quick Find
Same thing in reverse.
Matching Lines
Find all lines that match a regular expression and summarize in new window.
Next Match
Jump to the original text specified by the next line in a Batch Find or Matching Lines window.
Previous Match
Jump to the original text specified by the previous line in a Batch Find or Matching Lines window.
Place Bookmark
Set a book mark at the current position, pushing it onto a stack.
Return to Bookmark
Pop last bookmark from stack and go to it.
The Pin
Set Pin…
Set the Window Pin to the cursor location.
Exchange Point And Pin
Move the cursor to the Pin location, setting the Pin to the previous cursor location.
Hilite To Pin
If no selection, highlight the region between the cursor and the Pin, otherwise set the Pin to the end of the selection and move the cursor to the beginning of the selection.
Hilite To Previous
If no selection, highlight the region between the current position of the cursor and the previous position it occupied.
Go To Line
Go to specific line number.
Go To Column
Go to position within the line.
Go To Window Mark
The same as selection an item in the Marks menu (the one with the paperclip icon at the right top of the window's sidebar.)
Go To Window Func
The same as selecting an item in the Funcs menu (the one with two curly braces at the right top of the window's sidebar.)

Tools Menu

Compare
Windows
Compare top two windows, displaying differences in a third window. Navigate with arrow keys in the third window to see the differing lines in the original windows
Windows Word By Word
(When pressing the option key) As above but comparing words instead of lines.
Selections
Same as above, but compares only selections.
Selections Word By Word
(When pressing the option key) Same as previous item, but comparing words instead of lines.
Files…
Same as above, but prompts for files.
Folders…
As above, but works for entire folders.
Diff Prefs…
Direct access to Diff mode preferences.
Diff Help…
Opens the Help file for Diff mode.
Window Utilities
Show In Finder
Show the file of the current window in the Finder
Insert Path Name…
Prompt for a file and insert complete pathname in window.
Insert File…
Insert the text of another file.
Word Count
Count lines, words, chars in window.
Find Repeated Words
Search the active window for all repeated repeated words. If repeated words were found, a new "Browser" window is opened with the results. Click here findRepeatedWords for an example.
TIP: Once the "* Repeated Words *" browser window has been opened, you can select Search ↣ Next Match to highlight the line containing the next set of repeated words.
Codes Etc
Get Char Codes
Display the various codes associated with the character to right of the current cursor position. The information is displayed in a popover window attached to the character. Double-click in the popover or press Return to copy the info to the pasteboard.
Insert Unicode…
Prompt for a unicode code-point and insert the corresponding character. For instance, if you specify the code-point 03AB, the character Ϋ is inserted (GREEK CAPITAL LETTER UPSILON WITH DIALYTIKA).
Key Ascii…
Wait for key press and insert a modifier/charcode string suitable for creating a new keyboard shortcut (see the [binding] command). For instance, if you type the Ctrl-Opt-Cmd K combo, the string zoc 107 is inserted (107 is the ascii code of letter k).
Key Code…
Same as above, but inserts a modifier/keycode string. For instance, if you type the Ctrl-Opt-Cmd K combo, the string zoc 40 is inserted (40 is the code of letter k's key).
Tcl Shell
Start up command-line shell that interprets Tcl commands. The shell has a few csh-type features, such as ls, rm, etc. commands, as well as file completion with the TAB key.
Calculator
See the Calculator Help file.
Command Double Click
See the Shift-Command-Double-Clicking section below.

Window Menu (an icon with two windows)

Minimize
Minimize the active window and bring the next forward, or (if all windows are minimized) un-minimize the active window.
Minimize All (with ⌥ key)
Minimize all windows.
Zoom
Zoom windows in and out.
Default Size (with ⌥ key)
Resize window to default size.
Choose A Window…
Choose window to select from list
Shrink Window
Change the dimensions of the current window. In the submenu the choices are Default, Full, Top, Bottom, Left, Right.
Arrange Windows
Change the dimensions of the current window and the most recent window, i.e. side by side, top and bottom, etc.
Fonts
Change the font and size of the text of the current window.
Tabs
Handle window tabs (available on Mac OS X 10.12 or greater).
Set Font And Size
Show the standard OS X Font chooser palette.
Set Tab Size…
Change the tab size for current window.
Show/Hide Status Bar
Control the visibility of the status bar.
Next Pane
Switch to the next pane of a split window.
Previous Pane (with ⌥ key)
Switch to the previous pane of a split window.
Open Duplicate…
Open another copy of the active window.
Change Mode…
Manually change the mode of the active window.
Toggle Tool Bar
Toggle the display of tool bar of the active window
Choose A Window
Present a listpick to choose from among the open windows.
The Window Menu is appended with the names of all open document windows. If available, keyboard shortcuts from ⌘1 to ⌘9 are attached to some windows.

Basic editing

The very basics for editing text with Alpha is the same as in any other Mac application, but Alpha has a number of keyboard shortcuts to speed up your work, and numerous features not found in similar applications. See the help file Keyboard Shortcuts for an extended discussion.
Emacs user will also be happy to know that many of the basic keyboard shortcuts used in Emacs are supported by Alpha. However, this requires you to switch on the Emacs package. Read more in the file Emacs Help.
The following is a list of some of the most commonly used keyboard shortcuts in Alpha's default setup. Note that some of them may not be listed in any menus.

Help

Helpopen the Alpha Manual help file
⌃-Helpopen any available help for the mode of the active window.

Moving the Cursor

Left-Arrowbackward character
Right-Arrowforward character
⌘-Leftbeginning of line
⌘-Rightend of line
⌥-Leftbackward one word
⌥-Rightforward one word
Up-Arrowprevious-line
Down-Arrownext-line
⌘-Up or Homebeginning of window
⌘-Down or Endend of window
⌥-Up or Pageupmove one page backward
⌥-Down or Pagedownmove one page forward
⌃-Upscroll window up one line
⌃-Downscroll window down one line

Selecting Text

⇧-Leftextend selection one char left
⇧-Rightextend selection one char right
⇧-Upextend selection one line up
⇧-Downextend selection one line down
⌥⇧-Leftextend selection one word left
⌥⇧-Rightextend selection one word right
⌃Hselect next word
⇧⌘-Leftselect to beginning of line
⇧⌘-Rightselect to end of line
⌘Bselect smallest set of parentheses, braces,
(Balance in Text menu)brackets that encloses the current selection
Double-Clickingselect a word
Triple-Clickingselect a line
Double-Clicking on any type of parentheses or bracket selects the text from the parentheses or bracket to its mate.

Deleting Text

Del or ⌃Ddelete forward char
Deletedelete backward char
⌥Ddelete forward word
⌥H or ⌥-Deletedelete backward word
⌃Kdelete to end of line
Note that ⌃D, ⌥D, ⌥H, ⌥-Delete and ⌃K are only available after the package Emacs has been turned on.

Twiddle, Shifting Text

The following commands are found in the Text Menu. The keyboard shortcuts may not be displayed in the menu, because they are dependent on your keyboard layout (see International Preferences panel preferences).
Note also that the characters affected by Twiddle are determined by the global preference for Twiddle Adjusts (see the Text Preferences panel preferences).
TwiddleExchange characters surrounding cursor.
Twiddle WordsExchange words surrounding cursor
Shift LeftShift selection left one tab.
Shift Left SpaceShift selection left one space.
Shift RightShift selection right one tab.
Shift Right SpaceShift selection right one space.

The Numeric Keypad

Alpha is able to use the numeric keypad (if any) as a navigation tool. Press ⇧-Clear (or ⇧-Numlock) to turn on this feature or use the Num Lock preference in the General panel of the Global Preferences. You can also click on this hyperlink toggleNumLock to toggle the behavior of the keypad.
See the The Numeric Keypad section in the Keyboard Shortcuts help file for more information about some of the navigation tools available.

Drag and Drop editing

Alpha supports drag and drop cut, copy, clear, and paste. To use this feature, select some text, then move the cursor over the selected text. Mouse down (the cursor should then turn into an arrow), and move the cursor to the place you wish to paste the text. When the mouse is released, the highlighted text is moved to the new location.
Option-mouse dragging and dropping (that is to say holding down the option key ⌥) will always copy the dropped text, leaving the original in place. You can also drag selections between windows and to and from other applications, including the Finder. Dragging and dropping between windows will always copy rather than moving (in analogy with dragging a file from one volume to another in the Finder). Text dragged to the Finder is saved in a text clip file. Text can be deleted by dragging it to the trash can.
You can also drag any text file to an Alpha window to insert the content of the file in the window.

Multiple Selections

Alpha supports multiple selections, that is to say selections made of non contiguous parts. To make a multiple selection you must hold the Command key (⌘) down while you select different portions of text. Each portion is hilited. The Copy, Cut and Paste commands know how to handle multiple selections.

Rectangular Editing

If the Option key (⌥) is pressed while the mouse is dragged, a rectangular section of text is selected instead of the normal selection. This rectangular selection may extend over multiple lines, but contains only text between the column of the drag start and the column of the drag end. The drag cannot end on a column or row less than the start. This selection can be extended by option-shift-mouse, but not dragged further.
The rectangular selection can be deleted, copied, and pasted. This is very useful for tables and arrays, such as in LaTeX. Usually, the operation will be intuitive. However, if you use proportional fonts the selection may appear ragged. If some of the lines contain tabs, the result may not be what you want. Converting tabs to spaces in the desired region before attempting rectangular selection usually fixes the problems.
Alpha knows how to paste a rectangular selection stored in the pasteboard over another rectangular selection made in the text.
Not that a multiple selection (as explained in the previous section), even if it has elements of the same length, is not considered as a rectangular selection, and in particular it will not replace a rectangular selection. The pasting policy is different for multiple or rectangular selections.

Fill Routines

The fill and wrap routines reformat text to specified line lengths. This is useful in two cases. First, word processors such as Microsoft Word only insert carriage returns at the end of paragraphs. Secondly, while typing and inserting text into pre-existing paragraphs, the line lengths become unequal.
The wrap routine handles word processor documents quickly by merely inserting carriage returns as necessary to ensure all lines in the selected region are shorter than specified by the preference Fill Column. Alpha asks the user if wrapping should be done whenever the user opens files that have long lines. This can be defeated by including the word (nolinebreak) (with the parentheses) anywhere on the first line. You can also disable this feature if you turn on the Files preference named Never Break On Open. See the Files Preferences panel.
Important: beware that this kind of wrapping is known in Alpha as line breaking (or sometimes also hard wrapping) and is not to be confused with true wrapping (aka soft wrapping) which just wraps lines that reach the right edge of the window without inserting carriage returns. For more information, see the Line Breaking and Text Wrapping section.
The fill routine goes further. Not only does it break lines, but it also coalesces lines to eliminate short lines. The routine works by stripping the relevant text of white space, then re-inserting white space and carriage returns so that no line extends past Fill Column characters in length and begins with Left Fill Column spaces characters.
The preferences Fill Column, and Left Fill Column can all be set in the Document global preferences dialog. See the Document Preferences panel. Some mode may set them to different values.

Fill Paragraph

If there's a selection, then Alpha fills all paragraphs in that selection. If not then Alpha fills the paragraph surrounding the cursor. The definition of a paragraph may be mode dependent, but in Text mode it is the text between the closest empty lines.
Fill Paragraph also uses an extra preference Double Spaces, which determines if an extra space should be placed after the punctuation mark at the end of each sentence, i.e., after '.', '?', or '!'. Note that this also applies when the punctuation mark appears before a closing parenthesis, bracket, single or double quote, or two single quotes, according the English typographic usage.
Here is an example when the Double Spaces preference is turned on: 
This a simple sentence.  "The rule applies also for a sentence enclosed
between double quotes."  'As well for single quotes.'  ''Or doubled single
quotes.''  [When it is enclosed between brackets!]  (Or between
parenthesis?)  ("But it does not apply in this case!") As you can see.

See the Text Preferences panel.

Wrap Paragraph

Wrap the paragraph surrounding the cursor.

Word Breaking

Alpha allows you to redefine its internal notion of what a word is, through the preference Word Break. Word Break is set to a regular expression that defines a word to you.
The value of Word Break is mode dependent, as what is meant by a word may be different for different types of text or different computer languages. For example, in Text mode the default definition of Word Break is \w+. This matches any contiguous sequence of contiguous alphanumeric characters.

Keyboard Shortcuts

Many of Alpha's menu items are bound to specific keys. In general, keyboard shortcut icons are given to the right of any menu command. You can change most of Alpha's menu shortcuts by selecting Alpha ↣ Global Setup ↣ Keyboard Shortcuts ↣ Menu Shortcuts.
See the Menu-Shortcuts Preferences panel.
Alpha includes many keyboard shortcuts that go beyond those found in most software applications. Many of them are bound to specific menu items, and are displayed next to the item's name. Modifier keys include command (⌘), option (⌥), control (⌃), and shift (⇧).
Alpha allows you to customize the keystrokes you use to invoke editor functions. Any Tcl command (or accented characters) can be bound to any single keystroke. See the Keyboard Shortcuts help page for more information.

International Users

Since Alpha is intimately linked with Tcl (and is a programming editor) its user interface is based on English. It is unlikely that localization to other languages will appear concerning all the elements defined in the AlphaTcl library, but the core of Alpha, which is written in Objective-C, is localizable: it currently has no other localization than English though.
The most basic keyboard shortcuts in Alpha are designed to work on most keyboard layouts, but some of the shortcuts are centric to US/English keyboards. You can configure Alpha to set up an alternative slate of shortcuts specifically adapted to your keyboard: see the International Menus Help page for more information.

Undo + Redo

Alpha supports unlimited undo and redo. This means that most changes can be undone, and then redone, at will. Bear in mind that once you create new modifications, all changes that you have undone but not redone are lost.
Another point to bear in mind is that, by default, saving a document to disk flushes the undo buffer. This behaviour is controlled by the preference Clear Undo Stack On Save found in the Document Preferences panel of the Global Preferences dialog.

Line Breaking and Text Wrapping

Line breaking

Line breaking refers to Alpha automatically inserting line breaks as you type. The Alpha ↣ Mode Setup lets you modify several mode-specific flags, including the default Line Break setting. Each mode decides what the default line-breaking regime should be, but you can change this for any given window using the Info popup menu locatd in the status bar of document windows. (A window specific setting will remain in effect until that window is closed; the next time that file is opened it will again assume the mode's default setting.)
The possible values for the Line Break preference (found in the Text Preferences panel of the Global Preferences dialog) are No Line Breaking or Automatic Line Breaking.
When Line Break is set to Automatic Line Breaking, Alpha automatically inserts a Return when a line becomes too long, respecting the value for the current Fill Column preference. The global value for Fill Column can be changed in the Text global preferences dialog pane. Many modes have their own values which over-ride this global one. See the Text Preferences panel and the Mode Preferences panel.
Note: when the package Auto Wrap Comments is turned on, text that is typed in a commented line will be automatically wrapped even if the current Line Wrap setting is None. If you don't like this behavior, you can turn off Auto Wrap Comments globally See the Electrics Preferences panel. or for any given mode the Mode Features Preferences.

Text wrapping

Line breaking defined in the previous section is an as-you-type feature and modifies the contents of your document because it inserts end of line characters. On the contrary, line wrapping is a display property which tells the layout manager to wrap long lines so that they do not go beyond the right margin of the window. This is just a visual appearance and no end-fo-line character is inserted to provide this feature.

Remark about the terminology

Line breaking is sometimes referred to, in some programs, as hard wrapping whereas line wrapping is referred to as soft wrapping. This terminology is misleading and should be avoided because it conveys the impression that there is an exclusive choice between hard wrapping, soft wrapping and no wrapping at all. This is not the case as they concern different tasks (typing and displaying).
The Info popup of document windows clearly separates them and exposes two different items called Text Wrapping (which may be on or off) and Automatic Line Breaking (which may also be on or off). A check mark (√) in front of these items indicates that they are turned on. Select these items to alternatively set them on or off.

Indentation

Alpha can automatically indent the text for you to make it easier to read. Text can be indented using the Edit ↣ Indent menu command. In addition, many modes have an Indent On Return preference that can be turned on and off. When it is turned on, pressing Return will automatically indent the new line that is created. See the Mode Preferences panel.
Independently of this preference, pressing ⌘-Return will always indent the new line, while ⌃-Return will always insert a new line without indentation.
How the text is indented is mode dependent. In programming modes, Alpha will indent blocks of code, like e.g. an if-else statement in C / C++ / Java / JavaScript etc. like this: 
if (a == 5) {
    b = 5;
} else {
    b = 17;
}
How many positions the code is indented is determined by the preference Indentation Amount, set in the Electrics Preferences panel. By default the code is indented 4 positions for each level of indentation. By '4 positions' here, we mean the code is visually indented by an amount of whitespace equal to that achieved by pressing the spacebar four times.
Whether the code will actually be indented by spaces or tabs is dependent on the tab size, set in the Appearance Preferences panel. By default the tab size is 8. Thus with the default setting clearly your code can't be indented using tabs alone. 'Odd' indents will require a number of tabs plus 4 spaces, and 'Even' indents will be ok with just tabs.
If you want the code to be indented with spaces only, turn on the pref for Indent Using Spaces Only in the Electrics Preferences panel.

User interface details

This next section deals with Alpha-specific behavior which may be unfamiliar to new users. Alpha's interface has several non-standard features, which are described here.

Dynamic menus

Alpha uses dynamic menus. This means that some menu items are changed if you hold down any of the modifier keys. Usually the Option key (⌥) is the one which reveals the hidden menu items, but there are also a few items which are revealed by holding down the Control (⌃) or Shift (⇧) keys. Try this out by pulling down the File Menu and holding down one of the option (⌥), control (⌃), or shift (⇧) keys.
There is an option called Use Dynamic Menus to enable or disable the use of dynamic menus. By default, this option is set to display menus dynamically. If it is not set, then all menu items are displayed all of the time no matter what modifier key is pressed: this makes menus less compact. See the Menus Preferences dialog.

Status bars

Alpha has two types of status bars: a global one which by default is found just below the menu bar, and a local one for each window, placed just below the horizontal scroll bar at the bottom of the window. Both serve to give feedback from operations, depending on whether the info is of global nature or specific to the window. (Some functions, even if they might be considered as applying only to the topmost window, prefer to write info in the global status bar, though.)

Global status bar

The global status bar displays informative messages but can also be used to prompt for input. This is the case for instance when you type a composite binding: after you pressed the first part of the binding, the status bar displays it and waits for the remaining part. Another example is the use of the global status bar to perform Incremental Searches.

Status bar command line

Pressing Escape-X turns the global status bar into a command line as shown on the following image:
Status bar command line
You can then enter any AlphaTcl command or instruction for immediate evaluation (upon pressing Return). This allows expert users to perform almost any action, and is in particular very useful in debugging situations. When the command is executed, the status bar returns to its normal appearance and displays the result of the command.
Here is an example: if you want to know the current position (in characters) of the insertion cursor in the current window, press Escape-X, type getPos in the status bar command line, then press Return. The status bar will display the position.
You can press Escape or click anywhere (out of the input field) if you want to exit this command line without evaluating any command.

Visibility and position

You can hide or show the global status bar using the Window ↣ Show/Hide Status Bar menu items.
There is also a preference called Status Bar Visible to control and record this visibility property between sessions.
The preference called Status Bar Location lets you decide whether the status bas should be at the top or the bottom of the screen. The latter is possible only if the Dock is not already accupying the bottom of the screen.
Finally there is a preference called Status Bar Font Size which lets you choose a different font size for the messages displayed there. The hieght of the status bar is automatically adapted to the chosen font size.
These preferences are found in the Appearance Preferences panel. They are recorded as user defaults by the application.

Window status bar

The window-specific status bar (aka window's message bar) serves also to accomodate the line and column number indicators. Clicking on these brings up a dialog allowing to jump directly to a specified position in the active window.
Finally there is the Command-Clover (⌘) decoration of the window. This is input to the short-term memory of your brain to allow keyboard access (e.g. ⌘7) to direct switching to the window associated with a number (in this example: 7).

Toolbar

Each document window comes with a tool bar at its top. Its configuration is customizable and you can reorganize the layout of the tool bar as you wish: control-click on the toolbar and select Customize Toolbar in the contextual menu to see the other elements (Search field, Help button, Prefs button, etc.). Drag and drop the elements you want onto the toolbar.
You can alternatively show or hide the Tool bar using the Windows ↣ Toggle Toolbar menu item.

Row-column indicators

To the very bottom left part of every document window, the current line and column are displayed. Clicking on the number field opens a dialog that allows a specific line or column to be found. This is the same as using the Search ↣ Go To ↣ Go To Line and Search ↣ Go To ↣ Go To Column menu items respectively.

Control bar

The horizontal bar located just below the toolbar is known as the control bar. It contains several useful items:
Most items are popup menus known as the Document Popups.
The control bar also contains a path control displaying the full path of the file corresponding to the document window (if there is such a file). It looks like this for instance: Docwin path control

Option-Clicking Title Bar

Option-Clicking in the title bar (including the toolbar) displays a popover window which usually contains files or items related to the current window. The precise content of this menu is mode dependent, and not all modes will define the contents. If no mode-specific behaviour is defined, then the popover will contain a list of all files and folders in the open window's folder. Selecting a file in the popover will open it. Selecting a folder will open the containing folder in the Finder.
Recall that command-clicking on the window title in Alpha pulls down a popup menu showing all containing folders of the window's file. See the title section for more information.

Split-window menu

As explained above the split-pane popup button (represented by the Docwin split button icon) lets you split the current window horizontally or vertically, and each pane can in turn be split. Either pane can be edited, any changes appear in all panes if they show the same text. You can also drag and drop selections from one pane to the other.
Move from one pane to the other by clicking in the pane or by selecting the Previous Pane or Next Pane commands in the Split popup. To remove a pane, select it and use the Close Current Pane command.

Iconified (minimized) windows

You can minimize any open Alpha window to the Dock using the Window ↣ Minimize menu command or its equivalent keyboard shortcut ⌘M. If all windows are minimized then the most recent window is made visible once again.
Turning on the Iconify On Switch preference (in the Window Preferences panel) make Alpha do the following: (Yes, we know that this should be renamed Minimize On Switch ...

Contextual Menu

Alpha provides sophisticated contextual menu support, obtained by pressing the mouse and the Control key simultaneously (or, if your mouse supports it, by using the right mouse button). This support is based on the context of the mode of the current window as well as any text surrounding the click position. You can customize the menus/items that are presented in the CM, and have a different set of options for each given mode. See the Contextual Menu help has more information.
Note that in split pane windows you cannot use the selection in one pane to manipulate the text in the other. Invoking the CM in the alternative (i.e. non-active) pane should only use the selection/position information that is found in that pane beneath the current mouse location.

Dialogs

A few notes on Alpha's dialogs. It is conventional in dialogs that Tab moves to the next field or dialog element, that Return presses the default button (typically OK) in the dialog, and that Escape cancels the dialog.
The first two of these can pose problems if you wish to enter a real Tab or Return character into a text field in a dialog. To avoid this problem, Alpha specially recognizes '⌥-Tab' and '⌥-Return' and inserts a Tab or Return as appropriate.
In dialog boxes with checkboxes, a checkbox can be toggled by pressing ⌘-«Letter», where «Letter» is the first character of the name of the box that you want to change.
In dialogs without an editable text field, typing the first letter of the name of a button is equivalent to pressing the button. For example, you can press D for Discard Changes when you try to close a window with unsaved changes.

Tiling windows

Alpha provides many different ways to move windows around the screen, most of which are accessible via the windows menu, i.e the menu with the window icons: Window menu icon.
The first four items of the Windows ↣ Arrange menu move windows around a virtual box on the screen, defined by the Tiling preferences. See the Tiling Preferences panel.

Vertically

Tiles Num Wins To Tile number of windows vertically. Variables which affects the tiling:
Tile Top
The position of the upper edge of the top window.
Def Width
The width of the windows. (Def Width is set in the Window Preferences panel preferences.)
Tile Margin
Controls the gap between the windows.
Tile Height
Determines the height of the windows by the formula 
         (Tile Height + (Tile Margin -1))
height = ________________________________
                Num Wins To Tile

Horizontally

Tiles Num Wins To Tile number of windows horizontally. Preferences which affects the tiling:
Tile Height
The height of the windows.
Tile Left
The position of the left edge of the left window.
Hor Margin
Controls the gap between the windows.
Tile Width
Determines the width of the windows by the formula 
         (Tile Width + (Hor Margin -1))
width = ________________________________
                Num Wins To Tile

Unequal Vert and Unequal Hor

Tile two windows by splitting the space between them, with the proportion assigned to the first controlled by the Tile Proportion preference.

File formats

Alpha can read and write files stored with different line ending formats and with data in different encodings. In the dialog for the menu item File ↣ Save As, you can specify in which format a file should be written. At the bottom of the Save As dialog, you find the following accessory view:
SaveAs accessory view
The items of this view are explained in the next sections.

Record State

The Record State checkbox let you record some information about the current state of the window. Currently the following properties are recorded: More properties may be added in future versions of Alpha. These informations are not kept in the file itself but rather as extended attributes in the file system's database.
The value of the Record State property may be modified at any moment for a document window via its Info popup: you just have to select/unselect the Record State menu item.
Note that if you are going to be sharing files with other operating systems, the extended attributes will be ignored, so leaving the Record State property unset is a reasonable option.

Line Terminations

This popup menu specifies the way Alpha terminates lines. This to make it easier to share files with other platforms as lines are terminated differently on different platforms.
Unix (LF)Lines end with linefeed (aka LF).
Mac Classic (CR)Lines end with a carriage return (aka CR).
Windows (CRLF)Lines end with both carriage return and linefeed (aka CRLF).
On Mac OS X, the default choice is Unix. The Mac Classic line endings are a legacy from the old Macintosh systems (pre-OSX). Alpha will automatically read and write all three of these formats. If you are not sharing files with other platforms, you don't have to worry about the format and simply you use the default OSX format which is LF.
The line ending format for a file can be changed through the Info popup menu of the document windows by selecting one of the top three items: Unix, Macintosh, Windows.

File encodings

Alpha can edit text files in almost any encoding. The factory setting for the default input and output encodings is Unicode UTF8. This means that when Alpha first opens a file, it attempts to read the data using this default input encoding. If it fails to do so, it then prompts the user to specify another encoding (see the Secondary Input Encodings preference below).
The Open File dialog also has an Encoding popup in which you can directly specify which encoding to use to open the file. The global preference Input Encoding (found in the Encodings Preferences panel) lets you specify the default input encoding, that is to say the encoding which is proposed by default by the Open File dialog or which is used by default when you drag and drop a file on Alpha's icon in the Finder Dock. For instance, if you find yourself editing a lot of files encoded in MacRoman, you might want to set the default encoding to MacRoman in order not to be asked each time.
Similarly, there is a global preference Output Encoding (found in the Encodings Preferences panel) which lets you specify the default choice proposed by the Save As dialog.
In normal circumstances, you do not have to worry about the output encoding. If a file was opened using some encoding, then by default it will be saved using that same encoding. If you explicitely want to use another encoding to save the file, then you must use the Save As dialog's Encoding popup.
The Secondary Input Encoding global preference (also found in the Encodings Preferences panel) allows you to specify an encoding that will be offered as default encoding if Alpha fails to open a file using the Input Encoding : in this case, a dialog offers to try again and the secondary input encoding will be the default choice in the list of encodings.
The global preference Preferred Encodings (also found in the Encodings Preferences panel) lets you specify which encodings you want to be displayed at the top of the popup menu, to make them more easily accessible. The default setting is to propose UTF8, MacRoman, ISOLatin1 as first choices.
Click here to display the list of all the encodings currently supported by Alpha.
As a reminder, the encoding used to open a file is indicated by a dimmed item in the Info popup of document windows.

Open file dialog

Alpha's Open File dialog is similar to the dialog in any other Mac application but additionally you find, at the bottom of the dialog, the following accessory view:
OpenFile accessory view
The use of the Encoding popup has been explained in the previous section.
The Read Only checkbox may be used to open the file as read only. That a file is read-only file is indicated by a lock icon in the upper right corner of the window. Read-only status can be toggled by command-clicking on the icon. Alternatively, you can use the Lock/Unlock File item in the Info popup.
The default action for space and backspace when a file is read-only is to page forward (closing at the bottom of the file) or backward.

Paragraph format

Word processors such as Microsoft Word, or many mail programs only put carriage returns at the end of paragraphs, so that they can wrap the paragraphs on the fly. This is what is referred to as Paragraph Format. Alpha does not automatically convert to and from this format because there are valid reasons why someone might want to edit a paragraph formatted file while not in paragraph mode.
Therefore, when Alpha opens a paragraph-mode file, it asks the user whether or not to remap it. Alpha assumes a file to be in paragraph mode if it contains any line longer than the value of the Fill Column preference, which can be set in the Document preference pane. Files can be mapped back to paragraph mode by selecting Text ↣ Paragraph to Line.
If you turn on the Files preference named Never Wrap On Open, then you will never be asked about remapping the file. See the Files Preferences panel.

Helper Applications

Alpha uses many helper applications to perform some tasks, e.g. a web browser or an ftp client or a PDF viewer. Using by the menu item Alpha ↣ Global Setup ↣ Helper Applications, you can choose which helpers to use or change for all kinds of services. See the Helper Applications Preferences panel.
Now, in some cases a dialog is opened with a popup menu with some popular apps of the appropriate type. Either choose one from the popup menu, or select Locate manually and click OK to locate the app on your disk.
In some cases a file dialog is directly opened to let you locate the helper application.

Unix Tools

Some helper applications may be unix command line applications, and Alpha does its best to locate them automatically on your machine because locating them through standard open dialogs in OS X may be difficult. It makes use of the PATH environment variable.
Finding the right location to invoke these programs can sometimes be problematic since Alpha, as a GUI application, (subordinate to the Login Window process) has a different PATH setting than you might typically have in your unix configuration files .profile, .bashrc, or equivalents.
Alpha tries to acquire a usable PATH from these configuration files, but in some rare cases it is necessary to indicate extra paths by hand. This can be done in the Exec Search Path preference in the Helper Applications dialog. To figure out which paths to add, it can be helpful to go to the command line in the Terminal and execute which appname, for example which latex. This will tell you the full path of that application. You may then add the path to Alpha's Exec Search Path. When in trouble, ask on Alpha's Mailing Lists.

Spell Checking

For detailed informations regarding the spell checking support in Alpha, see the Spellcheck Help page. on title

Command-Clicking on title

Command-Clicking on the title of a document window causes Alpha to display a menu-like window. If the document is associated with a file on disk, this window contains the elements of the path in reverse order from top to bottom. For instance, if the current window corresponds to the file /Applications/Alpha.app/Contents/Resources/Alpha.sdef, then Command-Clicking on its title displays the following menu:
Window Title Menu
If you select the topmost item, the full path is copied in the pasteboard. Selecting another item (corresponding to a subfolder in the path), brings an Open File dialog pointing by default to this subfolder. Selecting an item in the menu while holding down the Shift key (⇧) opens the folder in the Finder instead of putting up a file dialog.

Shift-Command-Double-Clicking

Shift-Command-Double-Clicking in the text area triggers smart actions.
If the insertion cursor is inside an URL (not necessarily selected), Shift-Command-Double-Clicking causes Alpha to send the entire URL to its View URL service which passes it to the right helper application. If no helper application has been selected yet, Alpha will ask you to locate one (see the Helper Applications section).
Otherwise Shift-Command-Double-Clicking on a word activates a mode specific function which uses the word you clicked on as input. For instance, in several programming modes, Alpha tries to find the definition of the word you clicked on.
Some examples: Since the behaviour is mode-specific, consult the documentation for the mode in question to see if there is some special routine associated with Shift-Command-Double-Click.
The menu item Tools ↣ Command Double Click is equivalent to Shift-Command-Double-Clicking : if there is a selection, it applies to the selected text, otherwise it applies to the word which is at or around the current position of the insertion cursor. The keyboard shortcut for this item is F6.

Search and Replace

Alpha has a full repertoire of searching commands.
Consult the Searching section of the Quick Start document or the help page of the Supersearch package which implements Alpha's Find dialog, as well as several other items in the Search menu. It allows single / multi-file / regexp / batch / word-match / search / replace / replace-all / in-selection operations from the same dialog box.

Incremental Searches

Incremental searches bypass the normal search dialog and search for the current text after each keystroke. The result is often much faster and less intrusive. The Search ↣ Quick Find and Search ↣ Reverse Quick Find menu items are the forward and backward incremental searches respectively. More help can be found in the package Incremental Search help page.

Browser Windows

Browser windows are used to list the result of batch searches, as well as other similar lists. Each line in the browser window refers to a certain line in a file, in the case of batch searches the lines where what you searched for have been found. Navigate the windows using the up and down arrows, and jump to the match - i.e. the line in the file referred to by the line in the browser window - by hitting Return. See help for the package Brws for more information.

Modes

Alpha is made for editing text of many different kinds. Therefore Alpha can switch between many different modes. When Alpha switches between the modes some of Alpha's functionality changes to better help you to write the particular kind of text you are editing. For example C++ mode is used to edit code in the C++ programming language, and HTML mode is used for editing web pages. Alpha comes with more than 70 modes, most of them being modes for different programming languages. The default mode is called Text mode and is used for editing plain text. Alpha also switches to Text mode when you open a new untitled window. See the Help ↣ Installed Packages command for a complete list of them and for links for help for each of them. This section is only a general discussion about modes.
Simple examples of functionality which changes between the modes are: It is important to know that Alpha has both global menus and functionality, which are always there regardless of the mode, and mode specific menus and functionality, which are only there when Alpha is in a specific mode. For instance, the Alpha menu, the menus from File to Tools and the Window menu (the one with the two windows icon) are global menus.

Initial Mode Selection

When you open a file, Alpha chooses a mode for it, according to the following criteria (in this order):

File Creator

In some cases Alpha can choose the mode depending on which application has created the file. For example, files created by MacPerl (with the McPl creator code) are opened in Perl mode, while those created by Ramses (RAMS) open in M2 mode. Click here to see the current Creator Code -> Mode mappings. Although this is still the first criterion, nowadays very few files have a creator code associated. It should be considered a legacy from the Mac Classic operating system.

Unix executable lines

If the first non-empty line reads something like #!/dir/subdir/command ... then Alpha tries to find a mode corresponding to command. This kind of line (aka a shebang) is used in unix files. For example, files that start with 
#!/bin/bash
will open in bash mode. Click here to see the current Unix Executable -> Mode mappings.
A few other first-line patterns are recognized: for example documents starting with something like %&latex will open in TeX mode, and those with <?xml will open in xml mode.

Smart first line

If the first non-empty line contains a string 
-*-Mode: «mode»-*-
or 
-*-«mode»-*-
(usually preceded by comment characters) then Alpha switches to the mode «mode». For example, if the first non-empty line contains 
<!-- -*-HTML-*- -->
then Alpha opens this file in HTML mode.

Smart win attribute initialisations

If the first non-empty line contains strings of the form 
(key:value)
or 
([no]key)
like for example 
(tabsize:12) (myvar:important) (readOnly) (nowrap)
then, when the file is opened, these (key:value) pairs are put into the win attribute array (as can be queried by the [win::getInfo]). For standard variables like fontsize, tabsize, wordbreak..., the effect is that the window will open with these attributes, overriding any defaults or resource fork info. In any case, the (key:value) pair will be put into the win attribute array, where mode-specific or user-defined procs can access them. (The given example, (myvar:important) will be put into the win attribute array but will not have any effect until some user writes the code to read and make use of the win attribute myvar.)
In the case of a boolean, it is not necessary to use a colon and specify a value (0 or 1). If only the key is specified, then it is set to 1, like (readOnly) in our example, which is synonym of (readOnly:1). By convention, if the key is prefixed with 'no', the boolean is set to 0, like (nowrap) in our example, which is synonym of (wrap:0).
One can also specify a mode for the document window, like for instance (mode:Tcl). This is an alternatve to the syntax explained above in the Smart first line section.
As explained above, any (key:value) pair may be specified, but here is the list of the keys that are currently supported and understood by Alpha:
NameTypeDescription
coloringbooleanenable/disable syntax coloring
continuousSpellCheckingbooleanenable/disable continuous spell checking
dashSubstitutionbooleanenable/disable automatic dash substitution
dataDetectionbooleanenable/disable automatic data detection
dirtybooleandirty state of the window
fontstringwindow's font (see Font specification)
grammarCheckingbooleanenable/disable grammar checking
incrementalSearchingbooleanenable/disable incremental searching in FindBar
lineNumbersbooleandisplay the left margin with line numbers
linebreakbooleanapply line breaking (see Line Breaking and Text Wrapping)
linkDetectionbooleanenable/disable automatic detection of hyperlinks
modestringset the window's mode
quoteSubstitutionbooleanenable/disable automatic quotation mark substitution
readOnlybooleanenable/disable the window in read-only mode
recordStatebooleanremember the window's state
shellbooleanenable/disable the window of kind shell
showInvisiblesbooleandisplay invisible characters
smartInsertDeletebooleansmart insertion of space around words
spellingCorrectionbooleanenable/disable spelling correction
tabsizeintegersize of tabulations
textReplacementbooleanenable/disable automatic text replacement
wordbreakstringword breaking regular expression
wrapbooleanapply soft wrapping (Line Breaking and Text Wrapping)
Here are some examples of magic first line: 
# -*-Tcl-*- (tabsize:8) (nolinebreak) (font:name "Monaco" size 10)

# (mode:Tcl) (tabsize:4) (linebreak) (font:name "Monaco" size 10)

<!-- -*-HTML-*- (wrap) (linkDetection) (nolineNumbers) -->

// -*-Objc-*- (readOnly) (recordState)

File Mappings

The suffix in the file name is the last item checked if none of the above tests determined a mode for the file. For example, file.py is opened in Python mode because of the .py suffix, file.html is opened in HTML mode because of the .html suffix.
You can view and edit the suffix mapping via the menu item Alpha ↣ Global Setup ↣ File Mappings. In this dialog the suffixes for each mode are specified as a list of glob-style file patterns. For example, the wildcard '*' matches any string of characters, while '?' matches any single character. As an example, for Perl mode the default patterns are: *.pl *.ph *.pm meaning that any file with a name ending by .pl, .ph, or .pm will be opened in Perl mode. Uppercase equivalent suffixes are automatically recognized too, so it is not necessary (or recommended) to specify these separately. (The precise rule is that case sensitive matches take precedence over case-insensitive ones, so it is possible for example to map *.c to C mode and *.C to C++ mode, as it is custom on certain unix systems.) (Note that despite the name 'suffix mapping', in fact any glob pattern is respected. For example, one could map *htm* to HTML mode, thus matching also files like test.html.bak5.)
See the File-Mappings Preferences panel.
If all of these tests fail, the window will open, as a last resort, in standard Text mode.

Preferred Mapping

Some file extensions are claimed by different modes. For instance a file with the .m extension could be an Objective-C source file or a Matlab script or an Octave script. Alpha has a notion of preferred mapping which helps decide if such a file should be opened in ObjC, Matlab or Octave mode.
If you happen to be working on an Objective C project, you would be annoyed if each time Alpha opened your file in Matlab mode, forcing you to manually switch to ObjC mode. Fortunately, the preferred mapping can be modified via the Alpha ↣ Global Setup ↣ Preferred Mapping menu item. In the first dialog displayed by this command, select the mapping you are interested in (*.m in the present example), then a second dialog displays the list of corresponding modes for you to choose the preferred one.

Changing Active Window Modes

Once a mode has been selected for a window (either by Alpha or by you), it is remembered when you switch amongst your active windows. You can change the mode for a window manually in two ways:
  1. by selecting one in the Modes popup menu, near the left of the toolbar.
  2. by selecting the menu item Window ↣ Change Mode in the Window menu.
When you change the mode of an active window manually, it is remembered so long as the window remains open. When you close it and re-open it, the default mode will again be determined using the methods described above.

Alpha's Preferences

Alpha stores most preferences in files named defs.tcl and arrdefs.tcl, located in an application specific Preferences Folder. These files contain Tcl code so that Alpha evaluates them with its Tcl interpreter when it needs to restore saved preferences during startup. Among many settings, they record in particular which features or menus are activated.
Note that most preferences are saved to disk at the end of a session when you quit the application. If Alpha quits accidentally or if you forced it to quit for some reason (using the Force Quit dialog), some changes may not be recorded.
There are several possible locations for the Preferences Folder as explained in the next sections. Each one has its pros and cons, and the choice depends on your working habits.

Default Prefs Folder

By default, the preferences folder is named Alpha-v9.0 for versions 9.0.x of your Alpha binary, and will be named Alpha-v9.1, Alpha-v9.2 etc. for future versions.
Alpha creates this preferences folder as ~/Library/Preferences/Alpha-v9.0/, that is to say inside the user's Preferences folder. Different users on the same machine may thus have their own set of preferences.

User-Defined Prefs Folder

If you create a folder named AlphaPrefs and place it at the same level as the Alpha application, this folder will be used preferentially (and folders like Alpha-v9.0 as explained in the previous section will be ignored). As a consequence, there will not be different preferences folders for different versions of Alpha, meaning that you do not have to recreate your environment each time you upgrade Alpha.
This mechanism will also allow you to maintain two or more separate versions of Alpha without rebuilding indices each time that you switch back and forth amongst them.
If you do maintain multiple AlphaPrefs folders for multiple versions of Alpha located in different folders, note that saved preferences will not be shared amongst your Alpha applications. Each one will read the contents of the AlphaPrefs located at the same level.

Incompatibilities

It may happen that a new version of Alpha inadvertently introduces incompatibilities regarding some preferences. Usually the greatest care is taken to ensure a smooth transition, but errors do happen... Unless you know the internal guts of the application very well, your best bet in that case is to quit Alpha, remove its preferences folder, restart Alpha (which will create a fresh new one) and patiently rebuild your working environment.

Global and mode preferences

Alpha has two types of preferences, global and mode preferences. There is also another way of customizing Alpha than setting preferences in these dialogs. That is using preferences files where you add your own Tcl code. There is both a global preferences file, which can be opened / created using Alpha ↣ Preferences ↣ Edit Prefs File and a mode specific one created using Alpha ↣ Mode Setup ↣ Edit Prefs File (one for each mode). Their use is explained in the User defined preference files section of the Alpha Preferences help file.
To learn about writing your own Tcl code for Alpha, see the section below on Changing Alpha's behavior.

Coloring preferences

Alpha supports automatic coloring of the text. The way Alpha colors the text depends on the current mode. See the package Color Prefs for more information. Most modes expose preferences in order to specify different colors for keywords, comments, strings, etc. See the documentation of each mode to know what is available or just inspect the mode's preferences. The corresponding preferences are allways named something like Keywords Color , Comments Color, Strings Color, etc.

Packages

Alpha has a very flexible mechanism for adding extra functionality. Much of Alpha's functionality has been bundled into a number of so called packages. This has two main advantages. First, the user can choose to activate only those packages he or she wants and totally ignore the other ones. Second, anybody can write and distribute new packages for Alpha.
Alpha comes with a large number of packages. The remainder of this section describes some of them, but you can also see the Help ↣ Installed Packages command for a complete list which includes links for package specific help files.
The menu item Help ↣ Basic Help ↣ Read Help For A Package will also give information about specific packages. To learn how to install new packages see the section below on Installing New Packages.
The packages come in three flavors:
Modes
As has been discussed above in the Modes section, a mode gives Alpha some functionality useful for editing text for a particular purpose, for example writing code in various programming languages.
Menus
A menu is a package which attaches an extra menu to the menu bar.
Features
A feature gives you some more functionality without attaching a menu to the menu bar. However, some features add a new submenu or jsut some new menu items to an existing menu.
In practice, the only difference between menus and features is that menus have their own menus in the menu bar.
Menus and features can be activated and deactivated either globally using the menu items through the Alpha ↣ Global Setup ↣ Menus and Alpha ↣ Global Setup ↣ Features menu items. See the Menus Preferences dialog and the Features Preferences dialog.
They can be adjusted only for the mode of the current window using through the Alpha ↣ Mode Setup ↣ Menus and Alpha ↣ Mode Setup ↣ Features menu items. See the Mode Menus Preferences and the Mode Features Preferences.
Some packages are also enabled through some panels of the Alpha ↣ Preferences ↣ Global Preferences dialog, although in this case they will just look like a normal checkbox preference. (This distinction really doesn't matter much for most users ...)
To turn off a globally active preference for a specific mode, use the menu item Alpha ↣ Mode Setup ↣ Features dialog. (See the dialog pane for "Turn Items Off".)

Menus and Features

Activating a menu or feature makes the functionality provided by the menu or feature available until it is deactivated. Alpha remembers which ones are active next time you run the application. Once a menu or feature is deactivated, it should not affect Alpha's behavior in any way; the program should behave as if the package had never been turned on.
The Alpha ↣ Global Setup ↣ Menus dialog is divided into two sections, the first reserved for menus designed to be turned on globally, the second supporting functions for specific modes. See the Menus Preferences dialog.
You can adjust the order in which these global menus are presented by selecting Alpha ↣ Global Setup ↣ Arrange Menus. See the Menu-Order Preferences panel.
Normally it is a good idea to only choose among the options presented in the "General Menus" section. Although it is possible to activate the other menus globally, they are usually of no use outside the mode or modes they are designed for. You can turn menus on and off for specific modes by selecting Alpha ↣ Mode Setup ↣ Menus. See the Mode Menus Preferences.
The Alpha ↣ Global Setup ↣ Features dialog is similarly divided into two sections; General Features are designed to be turned on globally, while Mode Features are designed to be used in a specific mode or modes. See the Features Preferences dialog.
Again, it usually only makes sense to choose among the General Features options; features can also be turned on/off for specific modes. See the Mode Features Preferences.
See the Help ↣ Installed Packages command for the current list of available global and mode-specific menus and features.

Electrics - automatic typing by Alpha

The term electric is used in the sense of automatic, power assisted behavior, which is intended to save time, keystrokes, and brainpower. All the electric features are features (in the sense explained in the Menus and Features section), which makes Alpha do automatic typing for you. The exact behavior is mode dependent.

Electric completions

Enabling the Elec Completions feature gives you a set of features to save you key strokes. When you invoke it Alpha tries to expand what you have just typed to give the rest of what you want. Electric completion is invoked by the Complete key specified in the Alpha ↣ Global Setup ↣ Keyboard Shortcuts ↣ Special Keys dialog: by default, it is Control-Tab (⌃-Tab).
See the Electrics Help file for more information about completions. If you want to modify the completion key, see the Special Keys Preferences panel to set the completion key

Electric expansions

Enabling the Elec Expansions feature provides you with a special kind of word completion. When you find yourself typing a lot of variable and function names over and over, and these names are word-combinations where the name is formed by either capitalizing each word or separating them with an underscore, just type the initial letter of each word and invoke electric expansion instead. This is often shorter and more natural than typing a few letters and using electric completions to make a word completion. Electric expansion is invoked by typing command-space (⌘-Space).
See help for the package Elec Expansions for more information.

Electric stops

Many completion or text editing routines insert in your document a template which has to be filled by you. This is the case for instance if you want to create a tabular environment in a TeX file. These templates contain bullet symbols (•) known as electric stops or template stops. The idea is that they represent positions where you are supposed to enter some text: the beauty about this mechanism is that you can jump from a tab stop to the next one using the tabulation key. Each time you reach a tab stop, the bullet symbol disappears and is replaced by the insertion cursor, waiting for you to type something if you wish.
For instance, if you are in TeX mode and ask Alpha to insert a matrix with two rows and three columns, it inserts the following template: 
\begin{pmatrix}
    | & • & • \\
    • & • & •
\end{pmatrix}•
Here the vertical bar simply designates the initial position of the insertion cursor. All you have to do is to enter the coefficients of your matrix one by one, jumping to the next one by simply pressing the Tabulation key.

Special keys dialog

The dialog Alpha ↣ Global Setup ↣ Keyboard Shortcuts ↣ Special Keys is used to define the keys which activate the electric completion and expansion functions and which let you jump between the template stops. Set your preferences in the Special Keys Preferences panel if you want to change the keyboard shortcuts for your various electric operations. These shortcuts are saved between editing sessions.

Regular Expressions

Many packages use Regular Expressions in their procedures. While it isn't necessary to know anything about Regular Expressions (commonly referred to as regexps) in order to use Alpha, they provide a very powerful method for searching for any number of textual variations within a document. See the Regular Expressions help file for more information. Regular Expression searching is available in the Find dialog.

File Patterns

Some functions require that you give a file pattern which specifies a set of file names, e.g. if you want to change the file mappings you must give a pattern specifying which files should be opened in a certain mode, and as another example if you want to create a fileset you must give a pattern specifying which files should belong in the fileset.
File patterns are sometimes also referred to as glob patterns.
A file pattern is given as a string including special characters, which allow automatic substitution of characters in file names. 
    ?           Matches any single character.
    
    *           Matches any sequence of zero or more characters.
    
    [chars]     Matches any single character in chars. If chars contains a 
                sequence of the form a-b then any character between a and b 
                (inclusive) will match. To match '-' give it as the first 
                character between the brackets.
    
    \x          Matches the character x. This is useful if you want to 
                match any of the special characters, e.g to matching '*' is 
                done by the pattern '\*'.
    
    {a,b,...}   Matches any of the strings a, b, etc.
Some examples of how to use file patterns: A technical point to raise here is that the {a,b,...} style patterns are only supported where glob style matching is used. In many cases, for example the File Mappings dialog, standard string matching is used, in which case the {a,b,...} style patterns are not supported. See the File-Mappings Preferences panel.
This is typically because in such cases you are allowed to enter a list of patterns, which can be used to achieve the same aim.

Marks

Alpha allows the user to use marks to remember positions in files. Marks float. That is, if a mark is initially at position 312 and then five characters are inserted at location 297, the mark's new value will be 317.
There are several different types of marks available in Alpha, see the help of the Marks package for more information about named marks, temporary marks, the window pin, bookmarks, and the Parse Functions Docwin parse button popup menu.

File Comparison

With Alpha you can compare files and display the differences in them. Among other things, this allows you to easily pinpoint what has changed between two different versions of the same file. The Tools ↣ Compare menu items allow you to either compare the two topmost windows, a selection in each of the two topmost windows, or two arbitrary files or two entire folders. In the case of two folders, each pair of files with identical names in the two folders are compared. It is also indicated which files are only found in one of the folders and not in the other. It is also possible to perform word-by-word comparisons (in contrast to the standard comparison which is line based).
Alpha comes with a version of unix diff embedded in the application bundle, called DiffBOA (BOA stands for Background Only Application). This version has been tweaked to deal better with Mac files and is therefore the default Diff service for Alpha, but some other options are offered, like for example the unix diff tool that comes with OSX.
Alpha opens the two files in windows at the top of the screen with the diff results window at the bottom. You can navigate between individual differences in the diff window by using the Up and Down arrows. The section of the files which differ are then selected in the two files.
This section has only been a short introduction to the use of file comparison with Alpha. Read more in the file Diff Help.

Backups

Alpha can automatically make a backup copy for you of the old version of a file whenever you save changes. This is done if you turn on Backup in the Backups Preferences panel. See the help for the Backup package for more information.

Auto saving

Alpha can automatically save the documents for you after a certain number of changes. This is done if you check Auto Save in the Backups Preferences panel. Alpha then saves the documents every Changes Lim changes. Changes Lim can be set in the same preferences dialog. Note that untitled windows (and more generally windows which do not correspond to a file on disk) are not autosaved.

Tags

Alpha supports the use of tags to find declarations of functions. See the help window for the Tags package for more information. You will need to activate this package to make use of this functionality (like the tools ctags and etags if you are familiar with them). See the Tags Preferences panel.

Calculator

Alpha has its own calculator. This is just a simple RPN (Reverse Polish Notation) stack calculator, which works on both signed and unsigned decimals, hex integers, and floating point. See the Calculator Help file for more information.

The Command Line

For interaction with unix programs, it is important to be able to use the command-line to ask Alpha to edit files, or to be able to pipe information to or from Alpha. This section of the manual presents Alpha's support for the command-line.
The package Alpha Server enables command line interaction via pipes: there is a script alphac (located in Resources directory, inside the application bundle), typically at /Applications/Alpha.app/Contents/Resources/alphac, which accepts three basic commands for use in the Terminal to ask Alpha to edit a file. For example: 
> alphac my_file.txt
will open the given file inside Alpha. You must make sure that alphac has executable permissions, of course, and also make sure the script is in your PATH.
The way this works is that alphac communicates with Alpha and sends it the relevant information so that the file is opened for editing. For more details, type alphac in the Terminal to see the usage message: 
Usage is one of the following:
  - edit file(s):
    alphac file [file+]
  - edit file, select text from line1, col1 to line2, col2:
    alphac [+line1[.col1][,line2[.col2]]] file
  - create new window, with initial contents from string(s):
    alphac -c window [string+]
  - create new window, read initial contents from standard input:
    alphac -c window [-]
  - edit file(s), even with names like "-c", "+2.3,4.9", or "--":
    alphac -- file [file+]
  - edit file(s)/create window and wait until they are closed:
    alphac -wait <argument list>
Click here to reveal the alphac script in the Finder.

Using Alpha as a Helper Application

Alpha can be used as a helper application for other programs. For example, Interarchy and Fetch can use Alpha as their ftp-editor, allowing you to choose files from their listing windows, open and edit them with Alpha, and then save them back to their remote location. See the help window for the package Odb Editor for more information.

AppleScripting Alpha

Under OSX (as in Mac OS9) the standard way of communicating between applications is through AppleScripts. Alpha is highly Apple scriptable: in addition to a couple of required classes and commands, Alpha sports only one AppleScript command (quite a minimal set, indeed): 
DoScript
This command allows for the execution of any Tcl script or command. Hence every existing or imaginable command in Alpha, including all menu items, keystrokes, event hooks, advanced searches and filter actions, preference settings, can be executed via an AppleScript. This makes Alpha one of the most Apple scriptable of all applications, and this design is very flexible and powerful. No need to update a dictionary each time a command is added; user-defined Alpha commands are immediately callable through AppleScripts too. However, it means that in order to applescript Alpha, you need to know the AlphaTcl commands corresponding to the desired action, and you can not get this information by looking in an AppleScript dictionary. Please see the help files Alpha Commands and Extending Alpha to get started with AlphaTcl.
Here are just three simple examples of commands which can be exectuted from the AppleScript Editor as illustration:
  1. To get the path of the frontmost window: 
    tell application "Alpha"
    DoScript "win::Current"
end tell
  2. To get the line number of the insertion point (in the frontmost window): 
    tell application "Alpha"
    DoScript "return [lindex [posToRowCol [getPos]] 0]"
end tell
  3. To go to line number 12 in the frontmost window: 
    tell application "Alpha"
    DoScript "file::gotoLine [win::Current] 12"
end tell

Installing New Packages

This last major section of the Alpha Manual concerns upgrading or otherwise enhancing Alpha, either by installing new packages written by various Alpha users and developers, or by writing your own packages.

What is already installed?

It is obviously a waste of time to install something which is already installed or - worse - to install an old package replacing a more recent version. The Help ↣ Installed Packages command lists all packages which are installed. The list contains the package names, versions, and maintainers. This file can be updated at any time with the Alpha ↣ List Packages menu item.
This file lists the version number for every installed package. Make sure the version number of the package you intend to install is higher than the one for the currently installed package.

Installing a package

New packages should be installed in the Application Support folders of the application or in the Alpha Preferences folder.
For more information about the Application Support folders for Alpha, see the Application Support Help.
These three locations have the following characteristics: Inside any of these three folders, there is an AlphaTcl subfolder with exactly the same structure as the main AlphaTcl library contained in the application's bundle: 
    --- AlphaTcl
       |--- Examples
       |--- Help
       |--- Tcl
           |--- Completions
           |--- Menus
           |--- Modes
           |--- Packages
           |--- SystemCode
In particular the subfolders called Menus, Modes, Packages are meant to receive the new menus, modes or features you want to install. If the new package comes with help files, they must be installed in the Help folder in order to be found by the Help menu of the application. Similarly, example files must be installed in the Examples folder.
If you write your own packages or if you found a third package on the World Wide Web, this is where they must be installed, and not inside the application bundle itself.
Some third party packages may provide an automated script to execute the installation.

Rebuilding the indices

Once a new package is installed, you should quit Alpha and restart it. Alpha will automatically detect that a new package is present and will start rebuilding some indices files which are caches where it stores information for its packages management.
If for some reason Alpha fails to rebuild the indices, you can force it to do so by selecting the Alpha ↣ Preferences ↣ Rebuild Caches… menu item. Executing these commands won't do any harm.

User Defined Keyboard Shortcuts

Alpha allows you to customize the keystrokes you use to invoke editor functions. Any Tcl command can be bound to any single keystroke. Keyboard shortcuts can be stored in a global prefs.tcl file, or if they are mode specific, in a <mode>Prefs.tcl file. The first item is available under the menu item Alpha ↣ Preferences ↣ Edit Prefs File. This file will be sourced upon every restart of Alpha. The second type of prefs file, for individual modes, can be created/opened for the mode of the current window using the Alpha ↣ Mode Setup ↣ Edit Prefs File. This file is sourced _after_ the mode has been initialized, so any code contained in such a file will over-ride what is supplied in AlphaTcl.
Please see the Keyboard Shortcuts help for more information.

Changing Alpha's behavior

The rest of the manual points you in the right direction to customize Alpha even more, by writing some of your own Tcl code.
First of all, where do you put your own Tcl code so that Alpha can find it? Alpha has a set of preferences files for this purpose: For more information, see the User defined preference files.
These preferences files are intended for code for personal use. It is also possible to write a completely new package for Alpha, which others can also use. To learn about all of these topics, read the file Extending Alpha.

Alpha mailing list

Please use the Alpha developers mailing lists to discuss problems, suggestions etc with this release. See the subscription options available at https://sourceforge.net/p/alphacocoa/mailman/
There are a number of known bugs which will hopefully be corrected in a future release. See the Alpha's Bug Tracker to have an overview of the currently opened bugs. Please read the Bug Reporting help file for how to give an informative bug report, without which it is unlikely any bug you found can be fixed. The Debugging Help file may also be useful.
Creating a new bug report can easily be done starting from the Help ↣ Bug Reports ↣ Create New Ticket menu item.

Updating AlphaTcl from SVN

As explained above, most of Alpha's functionality is implemented in the AlphaTcl library. This library is open source and is hosted at a Subversion repository with SourceForge, to which the AlphaTcl developers daily commit their improvements and bug fixes -- and occasionally introduce a new bug, which is then hopefully detected quickly and fixed before the next release.
These intermediate versions are also known as beta testing development versions.
An expert Alpha user might wish to upgrade to the latest version of this library, to get access to the latest developments and help beta testing new features. To upgrade your AlphaTcl library to the latest, cutting-edge development version select the Alpha ↣ Global Setup ↣ Update AlphaTcl menu item or just click on this updateAlphaTcl hyperlink.
The core of the application is also periodically improved and very expert users may also grab the latest changes and recompile the core.
Further information is found the following documents: IMPORTANT: By upgrading in this way, you are implicitly accepting a higher risk of running into bugs, and you are morally obliged to report any anomalies or shortcomings you might encounter! It is recommended to turn on the AlphaDevelopers Menu (in the Alpha ↣ Global Setup ↣ Menus dialog), which provides easy access to several test facilities. Please read also the help document Debugging Help for more information.
If you want to revert to the previous state of the application, you may simply reinstall the latest public (stable) Alpha release.

Acknowledgments

The binary part of Alpha was originally written by Pete Keleher, and it is being maintained and developed by the Alpha Community, a small group of Alpha users who took over when Pete stopped his Alpha activity. The AlphaTcl library is also originally based on work of Pete.
Here is Pete's original acknowledgements (dating from the early 90's):
Alpha contains source from many places, but in particular I'm grateful to Ray Johnson and Tim Endres for their working on porting Tcl to the mac, and to Tom Scavo and Tom Pollard for their Tcl code contributions. The following people have also provided considerable code and/or help debugging the one or two bugs Alpha has had: Masatsugu Nagata, Karl J. Smith, Eric Sink, David C. Black, Richard T. Austin, Henry Spencer, Vince Darley, Johan Linde, Tom Fetherston, Jon Guyer and Jerry Fowler.
Alpha for Mac OS X has now been entirely rewritten based on Apple's Cocoa framework. This is known as the Alpha Cocoa Project started in 2012 and maintained by the Alpha Community as an Open Source project hosted and distributed on the SourceForge Open Projects platform:
See the credits in the About Box of the application.
The most recent release is available in the Alpha Download Area.

Copyright, Credits

This manual has been updated / revised by many helpful users and developers over the years, as noted above.