
        Copyright © 1990-1998 Pete Keleher. All Rights Reserved
        The Tcl code is copyright its respective authors
        
		Please note: The manual is currently being updated. This
		document is about 90% finished. Other parts of the documentation
		still need a major overhaul.
		
Legal notice
The Author(s) of this product are in no way liable for any direct or 
indirect damage caused by the product.

You may freely copy and distribute Alpha, but please bear in mind that 
Alpha is Shareware.  If you decide to keep it, please register your copy 
by selecting 'Register' from the 'AboutÉ' dialog.

        Introduction

Alpha is a very powerful, multi-purpose text editor.

Alpha is multi-modal, which means it switches between different modes
depending on which type of document you are editing. Everybody who has used
Emacs knows about this concept. The idea with different modes is to change
Alpha's behavior depending on which kind of text you're editing. For
example if you're programming in C++ or editing a LaTeX document you want
different features.

Alpha is very customizable. Much of Alpha's functionality is implemented in
'packages' or 'extensions'. The 'Config->Preferences->Menus And Features'
and 'Config->Mode Prefs->Menus and Features' menu items let you see which
items are installed, and lets you turn them on and off.

Alpha uses Dr. Ousterhout's Tool Command Language (Tcl) as an extension
language. Many of the functions bound to keystrokes, as well as many of the
functions in the menus, are written in Tcl. All the 'packages' or 
'extensions' just mentioned are all written in Tcl. Anybody who wants can 
write new packages for Alpha! 

Of course, you don't have to learn Tcl to use Alpha. You can have lots of
use of Alpha without knowing anything about Tcl. But if you want to become
a real power user, you should consider trying it out. Then the
possibilities of customizing Alpha are unlimited.

How to navigate the documention?

You can quickly jump between different sections of the manual by using the
menu you find under the M icon at the right top of this window.

Also, Alpha supports a limited form of hypertext. Clicking on green
underlined text executes a command associated with the underlined text,
usually taking you to other documentation. Control-<period> will bring you
back.

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.


        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 key shortcuts to speed up your 
work, and a couple of features not found in similar applications.
Emacs user will also be happy to know that many of the basic keybindings 
used in Emacs are supported by Alpha. However, this requires that you 
switch on the Emacs package. Read more in the file Emacs Help.

Moving the Cursor
left-arrow                      backward character
right-arrow                     forward character
up-arrow                        previous-line
down-arrow                      next-line

option-left-arrow               backward one word
option-right-arrow              forward one word

command-left-arrow              beginning of line
command-right-arrow             end of line
command-up-arrow  or  'home'    beginning of window
command-down-arrow  or  'end'   end of window

'Page up'                       move one page backward
'Page down'                     move one page forward

Selecting Text
shift-left-arrow                extend selection one char left
shift-right-arrow               extend selection one char right

shift-up-arrow                  extend selection one line up
shift-down-arrow                extend selection one line down

shift-option-left-arrow         extend selection one word left
shift-option-right-arrow        extend selection one word right

control-h                       select next word

shift-command-left-arrow        select to beginning of line
shift-command-right-arrow       select to end of line

command-B                       select smallest set of parentheses, braces, or 
(Balance in Text menu)          brackets that encloses the current selection

double-clicking                 select a word
triple-clicking                 select a line

Control-double-clicking on any type of parentheses or bracket selects from 
the parentheses or bracket to its mate. Without the control key held down, 
only the intervening text is selected.

Twiddle, Shifting Text
The following functions are found in the Text menu.
Twiddle (command-`)                  Exchange characters bracketing 
                                     the selection point.
Twiddle Words (command-option-`)     Exchange words bracketing the 
                                     selection point.

Shift Left (command-[)               Shift selection left one tab.
Shift Left Space (command-option-[)  Shift selection left one space.
Shift Right (command-])              Shift selection right one tab.
Shift Right Space (command-option-]) Shift selection right one space.

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. 
The cursor should then turn into an open hand. Mouse down, and move the 
cursor to the place you wish to paste the text. When the mouse is 
released, the hilighted text is moved to the new location.

Option-mouse does a "copy" instead. You can also drag selections between 
windows and to and from other applications, including 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.

You MUST have system 7.5 or above or Apple's "Macintosh Drag And Drop" 
extension installed. Get a copy from Apple or via Alpha's web page.

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 line contain tabs, the result may not be want 
you want. Converting tabs to spaces in the desired region before attempting 
rectangular selection usually fixes the problems.

Fill Routines

The 'fill' and 'wrap' routines reformat text to specified line lengths. 
This is useful in two case. 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 lines longer than 'Para Column' characters. This feature can be 
defeated by including the word 'nowrap' anywhere on the first line.

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', 'Para Column', and 'Left Fill Column' can 
all be set in the dialog "Config->Preferences->Text".

Both the fill and wrap routines come in two flavors, 'Fill/Wrap Paragraph' 
and 'Fill/Wrap Region'. 

Fill Paragraph
If there's a selection, then Alpha fills all paragraphs in that selection.
If not then Alpha fills the paragraph surrounding the insertion point. 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 after should
be placed after the '.' at the end of each sentence. This preference is set
in the dialog "Config->Preferences->Text".
Fill Region
If there's a selection, then Alpha fills all paragraphs in that selection.
If not then Alpha fills the region between the insertion point and the mark.
Wrap Paragraph
Wrap the paragraph surrounding the insertion point.
Wrap Region
If there's a selection, then wrap the selection. If not then wrap the 
region between the insertion point and the mark.

        User interface details

Alpha's interface has several non-standard features, which are described in 
this section.

Horizontal scrollbar 
You can remove the horizontal scrollbar from Alpha's windows in order to
give you more real estate. You can later get the scrollbar back when you
need it. The menu item Toggle Scrollbar in the Window menu inserts/removes
the horizontal scrollbar. The default for subsequent windows is controlled
via the preference 'Hor Scroll Bar' (look under
"Config->Preferences->Window").

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.

Tear-off menus
Alpha's menus can be torn off from the menubar to make floating palettes 
of them. Clicking on the buttons on the palettes performs the same action 
as the corresponding menu item. Note that dynamic menu items are separated 
into several buttons, one for each dynamic item.

If the torn off menu has submenus, there will be popup submenus on the 
palette. The submenus can in turn be torn off from the palette (as well as 
directly from the menu in the menubar).

If a torn off menu belong to a specific mode, the palette will 
disappear/reappear whenever you change from/to that mode.

If you do not want to use tear-off menus, you can disable this feature by 
unchecking 'Tearoff Menus' in the dialog "Config->Preferences->Appearance".

Bugs: 
Buttons in the palettes are not disabled when the corresponding menu 
items are.
Torn off submenus belonging to a specific mode are not hidden when you 
change from that mode, only the main menu.

Status bar
The stripe across the bottom of the screen is a floating window which is 
used to display short messages. This window is called the status bar. Some 
functions also uses it to prompt for input of some text.

To the right of the status bar there are three menus.
¥ Wrap menu. Shows if the lines in the current window are wrapped 
automatically and if the wrapping is soft or not. See the Section 
Text Wrapping for more information about text wrapping.
¥ File Attributes menu. Shows various attributes of the current window 
that can be changed. What "Mac", "Unix", "IBM", "MPW", "Think", and "None" 
means are explained in the Section File formats.
Read only lets you toggle if the current window can be edited or not.
Show invisibles toggles if invisible characters are shown or not. This 
affects all windows, not only the current one.
Tab size opens a dialog which lets you set the tab size of the current 
window, i.e. how many positions a tab uses.
¥ Mode menu. Shows the current mode and allows it to be changed. 

Finally, to the very right of the status bar the current line and column 
are displayed. Clicking opens a dialog that allows a specific line to be 
found.

You can't make the status bar go away. However, it can be dragged if you 
uncheck 'Lock Status' in the dialog "Config->Preferences->Window".

Funcs menu
Above the vertical scrollbar on the right is an icon with curly braces 
('{}'). This is the so called "Funcs" menu. The content of this menu is 
mode dependent, but for modes for programming languages it usually lists 
function definitions of the the current window. Select a function in the 
menu to jump to its definition in the window. Refer the mode specific help 
files for details about the Funcs menu for a specific mode. The menu is 
built when you press the braces, so it is always up-to-date. By default, 
the content in this menu is sorted alphanumerically. This feature can be 
turned off via the preference 'Sort Funcs Menu' in the dialog 
"Config->Preferences->Appearance", making the menu appear faster on slower 
machines.

Power user tip: cmd-opt-K will put up a listpick dialog of the content of 
the '{}' menu. As this is usually alphabetical you can type the starting 
letters of the index you want to go to.

Marks menu
Below the funcs menu is the "Marks" menu, which pops up over the icon with 
the large 'M'. The "Marks" menu lists all marks for the current window, and 
allows them to be cleared or automatically created. Marks are a kind 
bookmarks in a file and helps you navigate it. The marks are saved when you 
save the file. Select an item in this menu to jump to the corresponding 
mark in the window. Selecting 'Mark file' will generate marks for the 
current window. Which marks are generated is mode dependent. Refer to the 
mode specific help files for information about which marks are generated in 
a specific mode. For an extended discussion about marks, see the Section 
Marks.

Tip: ctrl-cmd-K will put up a listpick dialog with the current marks of 
the file.

Icons 
Above the Funcs menu is either nothing, a red disk icon, or a lock icon. 
The red disk icon indicates that the window is unsaved; clicking on the 
icon saves the window. The lock icon indicates that the window is 
read-only; command-clicking toggles the lock icon. Note, however, that an 
unsaved window cannot be made read-only.

Title bar
Clicking on the window title pulls down a popup menu showing all containing 
folders of the window's file. Selecting an item in this menu puts up a open 
dialog in the selected folder. 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.

Command-clicking on the title bar anywhere but right on the title pulls 
downs the Mark menu. This is also the case you click on the edges of the 
window. 
Tip: Using the sides of the window lets you access a particular area of the 
menu quicker as you can cmd-click in the approximate location of the menu 
item you want to select.
  
Option-clicking on the title bar brings down a menu. The content of this
menu is mode dependent, but not all modes will define the content of the
menu. If that is the case, the menu will contain a list of all files and
folders in the open window's folder. Selecting a file in the menu will open
it. Selecting a folder will open the containing folder in the Finder. Note
that for windows not saved to the disk there will be no menu with files.
Even if the mode will create a menu when option-clicking the title bar, all
files and folders in the window's folder may be added to the menu. This
happens if the number of items in the menu created by the mode is less than
what is specified by the preference 'Min Items In Title Popup' which you
find in the dialog "Config->Preferences->Window".

Split-pane bar
Above the vertical scrollbar, right under the Marks menu ('M') is a black 
"split-pane" bar. Double-clicking or dragging the split-pane bar splits the 
frontmost window into two separately scrollable panes. You can also use the 
menu item 'Split Window' in the Window menu. Either pane can be edited, any 
changes appear in both panes if they show the same text. Move from one pane 
to the other by clicking in the pane or by typing control-x, then 'o'. Go 
back to a single pane by either double-clicking again or dragging the bar 
back to the top of the window.

Iconified windows
Alpha can create small icons of the windows, which are ordered along the 
right edge of your screen. 'Iconify' (ctrl-I) in the window menu creates an 
icon of the frontmost window. If all windows are iconified it expands one 
of the windows again.

Checking 'Iconify On Switch' in the dialog "Config->Preferences->Window" will 
make Alpha do the following:
¥ Iconify all open windows when you switch to another app.
¥ Expand all windows, which were not iconified before switching from Alpha, 
when switching back to Alpha.

        File formats
        
Alpha can read and write files stored in different formats. In the Save 
asÉ dialog you can specify in which format a file should be written through 
the popup menus State and Format.
State popup menu
'State' allows you to specify how much extra information should be saved in 
files that you use.
MPW     Window position, current selection, tab sizes, and font 
        information are saved every time you open and close the file.
Think   Tab sizes, and font information are saved every time you open 
        and close the file.
None    No information is saved when you open and close the file.
The state information is saved in the file's resource fork. It is saved 
even if you don't modify the file. Saving this information does not change 
the modification date of the file.

Note that if a given file already has mpw information in it when the file 
is open, Alpha will always update that information when the file is closed. 
Note also that marks are always saved in the resource fork whenever a 
file is saved, regardless of the 'State'.

Format popup menu
This 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.
Mac     Lines end with a carriage return.
Unix    Lines end with linefeed.
IBM     Lines end with both carriage return and linefeed. 
            Typical, isn't it?          
Alpha will transparently 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 the default Mac format. Note that if you are 
going to be sharing files with a Unix or IBM machine, you probably don't 
want anything in the resource fork, so you'd probably want to set 
'State' to 'None'.

Both the state and format for a file can be change through the File 
attributes popup menu in the status bar.

The default Saved State can be changed in the dialog 
"Config->Preferences->Window".

Open file dialog
Alpha's open file dialog looks like the dialog in any other Mac application 
except for three extra checkboxes at the bottom.
Read only   Opens 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. 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.
Projector Aware Projector is freeware version control software from Apple 
            that is included in MPW. It also runs as a standalone 
            application known as SourceServer. It relies on the existence 
            of a 'ckid' resource in the files.

            "Projector aware" means that an application
                
    must)   not remove this ckid resource if one exists (that means if an 
            application saves a file by writing a new one, then delete the 
            old and rename the new one it must also make sure to copy over 
            an existing ckid-resource even if it uses just the data fork)
    should) interpret this 'ckid' resource correctly to treat a file as 
            read-only if the ckid resource says that the file is read-only 
            and not only if the Finder locked flag is set.

            However, I don't know how Alpha behaves in these two points.

            Finally, a ckid resource can contain a third state between 
            writable and read-only. This state is called MRO (modify read 
            only). Being a strange term (IMHO) MRO means that a file has 
            been modified locally but has not been checked out from the 
            version control pool before.

All files   Allows Alpha to open any file rather than just text files. 
            (Technically speaking: not only those with file type 'TEXT'.)

Paragraph format
Word processors such as Microsoft Word and MacWrite 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 
transparently 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 'Para Column', which can be set 
in the dialog "Config->Preferences->Text". Files can be mapped back to 
paragraph mode by using 'Paragraph to Line' in the text menu.

        Modes

Alpha is made for editing text of many different kinds. Therefore Alpha can 
switch between many different modes. When Alpha switch 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 25 modes, most of them being 
modes for different programming languages. The default mode is called Text 
mode and is used for editing plain text, like this manual for example. 
Alpha also switches to Text mode when you open a new untitled window. See 
the file Packages 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:
¥ Coloring of the text. Programming language all have special keywords. 
Alpha colors these keywords to make the code easier to read, and these words 
are naturally different in different programming languages.
¥ Alpha indents the code to make it easier to read. This is also naturally 
done differently for different programming languages.

Most modes also add functionality to Alpha, functionality which is not 
available for the basic Text mode. Some modes also have there own menu(s) 
which are inserted in the menu bar when switches to the mode in question. 
This menu(s) are removed again when Alpha leaves the mode. Some simple 
examples of extra functionality in different modes:
¥ In C++ mode Alpha can help you to quickly type certain language 
constructs, such as for loops.
¥ In HTML mode there is a function to create a link between two web pages.

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 menus from File to Config and the Window menu (the one with 
the three windows icon) are global menus.

When you open a file Alpha always chooses a mode for it. Alpha does its 
best to choose the mode you want. Therefore it is important to know how 
Alpha chooses the mode. The following is considered:
¥ The suffix in the file name. For example, 'file.c' is opened in C++ mode 
because of the '.c' suffix, 'file.html' is opened in HTML mode because of 
the '.html' suffix. You can view and edit the suffix mapping using the menu 
item "Config->Preferences->Suffix MappingsÉ"
In this dialog the suffices for each mode is specified as a list of 
patterns matching the file names. In these patterns * stands for 'any 
characters', e.g. the pattern '*.c' matches any file name ending by '.c'. 
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.
¥ If the first non-empty line contains a string '-*-Mode: <mode>-*-' 
or '-*-<mode>-*-' (without quotes) then Alpha switches to the mode <mode>.
For example, if the first non-empty line contains '-*-HTML-*-' Alpha opens 
this file in HTML mode.
¥ If the first non-empty line reads "#!/dir/subdir/command  ..." then Alpha 
tries to find a mode corresponding to 'command'. This kind of line is used 
in unix files.
¥ In some cases Alpha can choose the mode depending on which application 
has created the file. One example is that files created by MacPerl are 
opened in Perl mode.

You can customize which modes Alpha chooses in the last two cases, see the 
Sections modeCreator and unixMode.

You can also manually change mode for a window by selecting one in the mode 
popup menu in the status bar. The mode menu is the rightmost of the three 
menus in the status bar. You can also change mode using the menu item 
"Config->Mode Prefs->Change ModeÉ"

Once Alpha has chosen a mode for a window, Alpha remembers it when you 
switch between the windows, until you manually change the mode for the 
window.

Tip: Holding down the shift key while selecting a mode in the mode popup 
menu makes Alpha open the help file for the mode instead of changing mode 
for the window. 
Holding down the option key while selecting a mode in the mode popup 
menu makes Alpha give you a description of the mode. However, most of this 
description is hardly of any use unless you know Tcl programming.

Global and mode preferences
Alpha has two types or preferences, global and mode preferences. 
¥ Global preferences always apply regardless of the mode. These are set in 
the various dialogs "Config->Preferences".
¥ Mode preferences only apply to windows in that mode, and are set in the 
dialog "Config->Mode Prefs->PreferencesÉ". Some modes may also have other 
means of setting preferences. Note that in some cases there are mode 
preferences which coincide with a global preference. In this case the mode 
preference override the global one.

The 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, opened using 
"Config->Preferences->Edit Prefs File" and a mode specific one opened using 
"Config->Mode Prefs->Edit Prefs File".

To learn about writing your own code for Alpha, see the section Changing 
Alpha's behavior.

        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.

The packages come in three flavors:
¥ Modes. As have been discussed in the previous 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 adds a new submenu to a menu 
or some new menu items to a menu.

In practice the only difference between 'menus' and 'features' is that 
'menus' have their own menus in the menu bar.

Alpha comes with a large number of packages. See the file Packages for a 
complete list of them and for links for help for each of them. To find help 
for a specific package you can also use the menu item 
"Config->Packages->Read Help For A PackageÉ"
To learn how to install new packages see the Section Installing New Packages.

Menus and features can be activated and deactivated either globally or for 
specific modes. This is done using the menu items 
"Config->Preferences->Menus and FeaturesÉ" and "Config->Mode Prefs->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 Alpha. Once a menu or feature is deactivated
it does not affect Alpha's behavior at all. It is then as if it did not
exist. Note, however, that in some cases you the package is not deactivated
until you restart Alpha.

The dialog "Config->Preferences->Menus and FeaturesÉ" is divided into two 
pages, one for menus and one for features.

The page for menus is divided into two sections.
¥ Usual menus. These are menus designed to be used globally.
¥ Other possible menus. These are menus designed to be used in a specific 
mode or modes.
Thus, normally it is a good idea to only choose between the menus in the 
section 'Usual menus'. 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.

The page for features are similarly divided into two sections.
¥ Usual features. These are features designed to be used globally.
¥ Other possible features. These are features designed to be used in a 
specific mode or modes.
Also in this case it usually only make sense to choose between the ones in 
the section 'Usual features'.

        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. The first four items of the "Windows->Arrange" menu move windows 
around a virtual box on the screen, defined by the preferences found in the 
dialog "Config->Preferences->Tiling".
Vertically
Tiles 'Num Wins To Tile' number of windows vertically. Preferences 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 Windows 
preferences dialog.)
'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 window by splitting the space between them, with the proportion 
assigned to the first controlled by 'Tile Proportion'.


        Command-double-clicking

Command-double-clicking on a word activates a mode specific function which
uses the word you clicked on as input. In several programming modes, Alpha
tries to find the definition of the word you clicked on. Some examples:

When command-double clicking on a word in a C++ file Alpha first checks if
you clicked on an #include statement. Alpha then tries to open the file.
Next Alpha tries to look up the word in the tag file. If the word is not a
tag, or no tags have been specified, Alpha attempts to lookup the word
through the THINK Reference app. If you would like Apple's Toolbox
Assistant to be used instead, edit the proc 'C++::DblClick'.

In Tcl mode, if you click on a variable Alpha displays its value, if you
click on a command Alpha tries to look it up first in the Tcl folders, then
in "Alpha Commands", and then finally in "Tcl Commands".

        Command-clicking

Command-clicking on any text causes Alpha to try find a URL anywhere near 
where you click. If Alpha finds one it sends it to Internet Config which 
passes it to the right helper application. Unfortunately, this feature is 
rather buggy. Whenever there is a colon nearby where you click Alpha 
usually thinks there is a URL, although there is not, and sends it to 
Internet Config. If Internet Config returns an error Alpha then interprets 
your command-click as a command-double-click instead.

        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 saving a buffer to disk flushes the 
undo buffer.

        Text Wrapping

Alpha can wrap the text as you type in three different ways. How Alpha 
wraps the text can be set for each mode. Presumably you want Alpha to wrap 
plain text files, like this one, but not to wrap programming code.
How the wrapping is done is indicated in the leftmost popup menu in the 
statusbar, where also the way of wrapping can be changed. A change affects 
the current mode, not only the current window. The three ways of wrapping 
are:

None    No wrapping.
Wrap    When you type beyond 'Fill Column' positions, Alpha inserts a line 
        break to make you continue typing on the next line. 
Soft    Soft text wrapping is re-formatting the rest of the paragraph 
        on-the-fly as text is inserted and deleted. Soft-wrapping is 
        enabled by selecting "Soft" in the wrap popup menu in the status 
        bar. The text to be wrapped is delimited by the current line and 
        the last line in the current paragraph. Wrapping occurs after 
        insertions that result in the current line becoming longer than 
        'Wrap High' characters long (tabs counted as one character), or 
        deletions where the length of the line (tabs likewise) becomes less 
        than 'Wrap Low' characters long.
        The soft wrapping is not "true" soft wrapping like the one used by 
        word processors. Alpha rather reformat the paragraph and insert line 
        breaks at new positions on-the-fly.

The values for 'Fill Column', 'Wrap High', and 'Wrap Low' can be changed 
in the dialog "Config->Preferences->Text".

        Indentation
        
Alpha automatically indents the text for you to make it easier to read. 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.

if (a == 5) {
    b = 5;
} else {
    b = 17;
}

How many positions the code is indented is determined by the preference 
'Indentation Amount', which can be set in the dialog 
"Config->Preferences->Electrics". By default the code is indented 4 
positions for each level of indentation.

Whether the code will be indented by spaces or tabs is dependent of the tab
size, which can be set in the dialog "Config->Preferences->Appearance". 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, activate the feature 
"Indent Using Spaces Only" in the dialog "Config->Preferences->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, which makes Alpha do automatic typing 
for you. The exact behavior is mode dependent. The various electric 
features and enabled/disabled either globally in the dialog 
'Config->Preferences->Menus And FeaturesÉ' or per mode in the dialog 
'Config->Mode Prefs->Menus And FeaturesÉ'.

Electric return
Enabling the 'Electric Return' feature tells Alpha to indent the following 
line automatically whenever you press return.

Electric braces
Enabling the 'Electric Braces' feature tells Alpha to treat the left or 
right brace '{', '}' keys as special keypresses which enter the '{' or '}' 
character, followed by a return and then indent the following line 
correctly. It is useful for those programming modes in which '{' and '}' 
are used to delineate blocks of code in 'for' loops or 'if-then-else' 
groups etc.
If you only want a '{' or '}' without the electric behavior, type option-{ 
or option-}.

Electric semicolon
Enabling the 'Electric Semicolon' feature tells Alpha to treat the 
semicolon keys ';' as special keypresses which enters the ';' character 
followed by a return and then indents the following line correctly. It is 
useful for some programming modes in which ';' normally ends a line. The 
';' key is context-dependent so you can still enter a for( ; ; ) loop in C 
mode (for instance) without Alpha messing things up.
If you want a ';' without the electric behavior, type option-;.

Electric colon
Enabling the 'Electric Colon' feature tells Alpha to indent lines ending by 
a colon differently. This is for those programming modes which uses 
switch-case statements like e.g. C/C++, Java, and JavaScript.

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 
typing command-tab or F1. The documentation will always refer to 
command-tab as being the key combination for electric completion. However, 
command-tab conflicts with the application switching feature introduced in 
Mac OS 8.5. Read more about this conflict below.

Alpha can complete what you just have typed in several different ways, and 
the behavior vary from mode to mode. In many modes Alpha tries a set of 
different ways to complete and continues until one of them succeed (or all 
fails). Let us start with the simplest kind of completion, but which 
normally is tried last when everything else has failed.

Word completion: Type the first few letters of a word and hit command-tab 
(or F1). Alpha will then search the document for a word which begins with 
these letters. If one is found Alpha completes the word you have just typed 
the first letters of. If this is not the word you want, hit command-tab 
again and Alpha continues searching for another one beginning with the same 
letters. Hitting command-tab repeatedly will cycle through all words in the 
document beginning with these letters until no more such word is found. 
Alpha always starts searching backwards from the point where you are until 
is reaches the top of the document, then is continues searching forwards 
from the point where you are until the end of the document.

An example: Typing 'com' right here and hitting command-tab will expand 
this to 'command', which is the first word beginning by 'com' found above. 
Hitting command-tab again without moving the insertion point will expand it 
it 'completes', which is the next word beginning by 'com' found above.

Command template completion: For for loops, if statements and similar 
constructs used in programming languages Alpha can insert a template. As 
an example let's make an 'if' template for C, C++, Java, and other 
languages using the same construct. Simply type 

if

(when Alpha is in C, C++, or Java etc. mode!) and hit command-tab. Alpha 
then inserts a template

if (|){
    ¥
} ¥

with the insertion point between the parentheses. The bullets '¥', which 
are inserted are called template stops. When you hit tab, Alpha jumps to 
the next template stop and deletes. To use the template first type the 
condition and then hit tab. Alpha the jumps to the first bullet and deletes 
it. Then type the body of the if statement and finally hit tab again to 
jump to the last template stop. Note! The feature 'Electric tab' must be 
enabled for the mode in question to be able to jump between the template 
stops with tab, see below.

This section has only been a short introduction to electric completions. 
More detailed help is found in ElecCompletions Help. 

Some modes also have their own tutorial how to use completions in the mode. 
The tutorial is opened using 'Config->Mode Prefs->Completions Tutorial'. 
See also the documentation for the mode.

Electric tab
Enabling the 'Electric Tab' feature allows Alpha you to use the functions 
'Indent or Next Stop' and 'Complete or Tab' as any of your 'Special Keys' 
bindings. By default 'tab' is invokes the function 'Indent or Next Stop', 
but there is no key which invokes 'Tab or Complete'.
Indent or Next Stop will first look forward for a template stop '¥'. If one 
is found Alpha jumps to it and deletes it. If no ¥ is found Alpha will 
instead indent the current line.
Complete or Tab will make an electric completion.
If you want to insert a normal 'tab', type option-tab.

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 letter and using electric completions to make a word 
completion. Electric expansion is invoked by typing command-space.

The string you are going to use expansion on is entered in lowercase. The 
words in the target you are trying to hit have to start with a capital 
(except the first word), or, be separated by an underscore.

The hint can be embedded between non-alphabetic characters and certain 
punctuation marks ( '[', '(', '{', ',', ';', ':', ''', '"', ']', ')', '}' 
). The expanded hint remains so embedded, and the cursor appears one space 
beyond the trailing punctuation.

An example: Let's say there is a word 'someLongWord' in the file. Then 
typing 'slw' and hitting command-space will expand 'slw' to 'someLongWord'.

Another example: Let's say there is a word 'some_long_word' in the file. Then 
typing 'slw' and hitting command-space will expand 'slw' to 'some_long_word'.

This section has only been a short introduction to electric expansions. 
More detailed help is found in ElecCompletions Help. Some modes may also 
their own special expansions features, see the help files for the respective 
modes.

Special keys dialog

The dialog "Config->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. You can define keys for the following
functions:

Function                Action
Expand                  Electric expansion.
Next stop or indent     Alpha first looks forward for a template stop '¥'. 
                        If one is found Alpha jumps to it and deletes it. 
                        If no ¥ is found Alpha will instead indent the 
                        current line. This requires that 'electric tab' is 
                        enabled, otherwise a tab is inserted.
nth Stop                Jumps to the nth template stop.
Complete or Tab         If 'electric tab' is enabled Alpha will make an 
                        electric completion, otherwise a tab is inserted.
Next stop               Jump to the next template stop '¥' and delete it.
Clear all stops         Delete all template stops '¥' in the window.
Complete                Electric completion.
Real tab                Inserts a tab.
Prev stop               Jump to the closest template stop '¥' before the 
                        current position and delete it.

There are two predefined sets of key bindings for these functions. The 
alternative set is define to use key bindings like those which are used in 
Emacs. In the dialog 'Config->Special KeysÉ' you can choose one of these 
two sets of bindings or define your own.

Function                Default binding             Alternative binding
Expand                  command-space               command-space
Next stop or indent     tab                         no binding
nth Stop                control-tab                 control-tab
Complete or Tab         no binding                  tab
Next stop               no binding                  control-j
Clear all stops         shift-control-tab           shift-control-tab
Complete                command-tab                 no binding
Real tab                option-tab                  option-tab
Prev stop               shift-tab                   shift-control-j

Electric completions and Mac OS 8.5
In Mac OS 8.5 command-tab is used to switch between application. This 
conflicts with Alpha's use of command-tab for electric completions. This 
problem can be solved in three different ways:
¥ By default 'Electric completion' in Alpha is also bound to F1. Use F1
instead of command-tab. However, the package "Electric menu" uses F1
for someting else, so if you activate the "Electric menu", using F1 for
electric completions is not possible.
¥ Use the dialog "Config->Special KeysÉ" to define a new key combination for 
Electric completion.
¥ Change the key combination for switching applications in Mac OS. This is 
done in the following way:
    ¥ Open the Help Viewer
    ¥ Search on "tab" (or whatever is appropriate in your language)
    ¥ Select "Switching between open programs"
    ¥ Scroll down to the end of "Switching from one program to another"
    ¥ Click "Help me modify the keyboard shortcuts"

        Coloring
        
Alpha supports automatic coloring of the text. The way Alpha colors the 
text depends on the current mode. There are basically three different 
things Alpha can color.
Keywords    A set of words with a special meaning, e.g. keywords in 
            programming languages.
Strings     Text delimited by double quotes. Alpha can color single-line 
            strings only.
Comments    Comments in programming code.
For details about the coloring in a specific mode, see the help file for 
the mode. The coloring support in the different modes differ and some 
modes have a more complex coloring support than just the basic things 
mentioned above.

Colors for keywords, strings, and comments (for applicable modes) can all 
be changed via the "Config->Mode Prefs->PreferencesÉ" menu item. Some 
modes may offer more extensive customization.

By default there are seven different colors to choose between, blue, cyan, 
green, magenta, red, white, and yellow. If you wish you can redefine these 
via the menu "Config->Redefine Colors". For instance, you can redefine 'red', 
and any text that is currently red will then be the new color you specify. 
In addition, there are eight other colors 'Color_9' through 'Color_15' 
which you can use to define your own colors. Note that by default these 
colors do not show up in the mode preferences dialog because until you have 
given them a value they are undefined.

Coloring can be turned off completely by unchecking 'Coloring' in the 
dialog "Config->Preferences->Appearance".

Additionally, Alpha allows the text color and window background to be 
changed. These are changed by redefining 'Foreground' and 'Background' in 
the "Config->Redefine Colors" menu.

Advanced coloring customization 

If you don't find the customization in the mode preferences dialog 
sufficient, you can customize the coloring by adding some Tcl code to the 
mode preferences file. This file is opened via the "Config->Mode 
Prefs->Edit Prefs File" menu item. Coloring is defined using the command 
regModeKeywords. For a complete descriptions how to use regModeKeywords, 
see the file Alpha Commands. Here follows a few examples.

As an example the line:

    regModeKeywords -a -k blue Fort {blah bladdity}
    
will add the keywords 'blah' and 'bladdity' colored blue in Fortran mode.

        Search and Replace
        
Alpha has a full repertoire of searching commands. The 'Find' menu item in 
the Search menu brings up a dialog allowing the search and replacement text 
to be specified. Alpha can search either the current open window or a set 
of files. 
The dialog also allows the following options:
Forward         To search the text forwards or backwards. This does not apply when 
                multiple files are searched.
Ignore Case     Whether the search should match case or not.
Word Match      Whether the search should match only complete words or not.
Batch           When making a batch search, a list of all matches in the 
                fileset or current window are displayed in a new 
                browser window. A particular match can be displayed by 
                moving the cursor to a line in the file of matches and  
                hitting "return".
Grep            The search and replace text strings are interpreted as 
                regular expression. The word 'grep' comes from the unix 
                command with the same name.
Mult Files      To search through all files in a given file set. Checking 
                the 'Mult Files' box brings up a new popup menu. In this 
                menu you can choose which fileset to search. You can either 
                select an existing fileset in the menu or create a new one 
                by selecting "New FilesetÉ". Read more about fileset in the 
                file Filesets Help.
                In addition to the current filesets, the menu has an item 
                called 'Directory Scan'. This allows you to specify a 
                folder that will be searched. This folder is also saved at 
                the end of the menu for future searches.

And finally, Alpha allows a library of useful search and replace texts to
be defined. This library is used and edited in the popup menu 'Patterns'.
Selecting a pattern from the menu inserts the search and replace strings in
the dialog. In addition
Remember Pattern creates a new item in the menu from the current search and 
replace strings.
Delete Pattern lets you delete a pattern from the menu.

Incremental Searches
Emacs users will be happy that both forward and backward incremental 
searches are implemented. 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 menu items 'Quick Find' and 
'Reverse Quick Find' in the Search menu are the forward and backward 
incremental searches respectively. Start the search either from the menu or 
by typing ctrl-s or ctrl-r, then type the word you are searching for. After 
each letter you've typed Alpha jumps to the nearest point in the text 
matching what you have typed so far. The search string is also displayed in 
the status bar.

Typing ctrl-s or ctrl-r again while an incremental search is in progress 
causes the search to proceed to the next instance of the current text. 
Incremental search mode is exited when any other command (executed through 
the menus or through bindings that include at least one of the control key 
and the option key) is executed, or when the escape or delete key is used. 
Typing control-w while incremental search is active causes all the 
characters to the end of the next word boundary to be added to the search.

        Browser Window

Browser windows are used to list the result of batch searches, as well as 
other similar lists. Each line in the browser window refer 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'.

The browser windows are actually in a special mode, the browser mode. The 
complete set of keybindings in this mode is:

uparrow             move up one line in the window and select the line
ctrl-p                                      -"-
delete                                      -"-
downarrow           move down one line in the window and select the line
ctrl-n                                      -"-
space                                       -"-
return              go to match
enter                   -"-
ctrl-C ctrl-C           -"-

In the Search menu there is also a very useful command 'Next Match'. 
Regardless which window is frontmost, it brings the browser window to the 
front, navigate down one line, and goes to the match of that line. Thus, 
this gives you a quick way to jump to all matches without having to 
manually bring the browser window to the front.

        Regular Expressions

Regular expressions are used to find the part of a string which matches a 
certain pattern.

A regular expression is zero or more branches, separated by `|'. It matches
anything that matches one of the branches.

A branch is zero or more pieces, concatenated. It matches a match for the
first, followed by a match for the second, etc.

A piece is an atom possibly followed by `*', `+', or `?'. An atom followed
by `*' matches a sequence of 0 or more matches of the atom. An atom
followed by `+' matches a sequence of 1 or more matches of the atom. An
atom followed by `?' matches a match of the atom, or the null string.

An atom is a regular expression in parentheses (matching a match for the
regular expression), a range (see below), `.' (matching any single
character), `^' (matching the null string at the beginning of the input
string), `$' (matching the null string at the end of the input string), a
`\' followed by a single character (matching that character), or a single
character with no other significance (matching that character).

A range is a sequence of characters enclosed in `[]'. It normally matches
any single character from the sequence. If the sequence begins with `^', it
matches any single character not from the rest of the sequence. If two
characters in the sequence are separated by `-', this is shorthand for the
full list of ASCII characters between them (e.g. `[0-9]' matches any
decimal digit). To include a literal `]' in the sequence, make it the first
character (following a possible `^'). To include a literal `-', make it the
first or last character.

If a regular expression could match two different parts of the input
string, it will match the one which begins earliest. If both begin in the
same place but match different lengths, or match the same length in
different ways, life gets messier, as follows.

In general, the possibilities in a list of branches are considered in
left-to-right order, the possibilities for `*', `+', and `?' are considered
longest-first, nested constructs are considered from the outermost in, and
concatenated constructs are considered leftmost-first. The match that will
be chosen is the one that uses the earliest possibility in the first choice
that has to be made. If there is more than one choice, the next will be
made in the same manner (earliest possibility) subject to the decision on
the first choice. And so forth.

For example, `(ab|a)b*c' could match `abc' in one of two ways. The first
choice is between `ab' and `a'; since `ab' is earlier, and does lead to a
successful overall match, it is chosen. Since the `b' is already spoken
for, the `b*' must match its last possibility-the empty string-since it
must respect the earlier choice.

In the particular case where no `|'s are present and there is only one `*',
`+', or `?', the net effect is that the longest possible match will be
chosen. So `ab*', presented with `xabbbby', will match `abbbb'. Note that
if `ab*' is tried against `xabyabbbz', it will match `ab' just after `x',
due to the begins-earliest rule. (In effect, the decision on where to start
the match is the first choice to be made, hence subsequent choices must
respect it even if this leads them to less-preferred alternatives.)

To summarize, regular expressions are built up of the following pieces:

 c        literal char.
 ^        beginning of line.
 $        end of line.
 .        any character except carriage return.
 [...]    character class, can use ranges such as '0-9'.
          inside classes. Matches one character of the 
          enclosed choices. Ex: '[ac0-2]' matches 'a', 
          'c', '0', '1', or '2'.
 [^...]   negated character class, matches anything but
          the enclosed characters. ']' can be included
          by putting it immediately after the '^'.
 \t       tab.
 \r       carriage return or line break.
 *        zero or more occurrences of the previous
          pattern. Ex: 'ab*' matches 'a', 'ab', 'abb',
          'abbb' etc.
 +        one or more occurrences of the previous 
          pattern. 
 ?        zero or one occurrences of the previous 
          pattern. Ex: 'ab?' matches 'a' or 'ab'.
 a|b      matches either a or b. If enclosed in
          parenthesis, the extent of the alternated
          expressions is limited. Ex: (pete|bob) 
          matches either 'pete' or 'bob'.
 (...)    The interior elements are grouped together. 

Regular expressions constructed from the above elements can be 
concatenated to create larger expressions. 

The parenthesis also define substrings of the total matched string that 
can be used either later during substitution. The substring delimited by 
the pair of parenthesis that includes the nth left paren is denoted \n, 
where n is 1, 2, .... 9.  '\0' and '&' both refer to the matched text.

[examples to be added]

        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 suffix 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.

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:
¥ To match any file ending by '.c' use the pattern '*.c'. This will match 
files with names like 'blah.c' 'bladdity.c' 'gghjcdhj.c'.
¥ To match any file ending by '.c' or '.h' use the pattern '*.{c,h}'. This 
will match files with names like 'blah.c' 'blah.h' 'bladdity.c' 
'bladdity.h'.
¥ Lets say you have files with names 'chapter1.tex', 'chapter2.tex' through 
'chapter50.tex'. To match the first 9 chapters you could use the pattern 
'chapter?.tex' This will match the files 'chapter1.tex' through 
'chapter9.tex'. Another pattern which would match the same files is 
'chapter[1-9].tex'.
¥ To match the files 'chapter1.tex' through 'chapter9.tex' and 
simultaneously files 'chapter1.log' through 'chapter9.log' you can use the 
pattern 'chapter[1-9].{tex,log}'
        
        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.
Alpha uses three different types of marks.

The first is generically referred to as "the mark". The mark is set to the
current insertion point by the command 'Set Mark' (control-space). (This
requires that the Emacs feature is active.) The position in the file
indicated by the blinking cursor is referred to as the current insertion
point. Many commands (such as "cut" and "copy") can operate either on the
currently selected (hilighted) text, or the text between the current
insertion point and "the mark". For example, if you move the cursor to the
beginning of the word "allybaba", hit control-space (the status bar should
say "Mark set"), move to the end of the word and hit option-W (the status
bar should say "Region copied"), the effect is the same as if you had used
the mouse to select the text and then selected the "Copy" command from the
"Edit" menu.

The second type of mark are the permanent marks. Permanent marks are set,
removed, and moved-to through the three corresponding menu items in the
"Search->Named Marks" menu. Permanent marks differ from the generic mark in
that they have names, there can be any number of them, and they are saved
in the resource fork if the file is subsequently saved.

Permanent marks can be accessed via the "Search->Named Marks" menu items,
by a popup menu called by mousing down on the M icon above a vertical
scrollbar, or by command-mousing on a window's titlebar.

        International Users
        
There is a basic problem international users will notice, which have to do 
with the fact that the keyboard layouts are different in different countries. 
Therefore some keybindings in Alpha may not work with all keyboards. For 
example, on a Swiss keyboard, '/' is shift-7 (which means you have to press 
shift to get '/'. This means there is no difference between cmd-/ and 
shift-cmd-/ on such a keyboard. In Alpha these are bound separately to 
'zoom' and 'singlePage'.

If you're using a western keyboard Alpha can solve some of these problem
for you.

First: Activate the "International Menus" feature. It replaces some
keybindings in the menus and solves problems like the one just described.
However, only key bindings in the global menus "File" to "Windows" are
modified. Any other menu may still have problems.

Second: Tell Alpha which keyboard layout you're using in the preferences 
dialog "Config->Preferences->International". (In a future version, Alpha 
should be able to get this information from the OS directly.) This will 
make sure that some bindings not defined in the menus work, e.g. that the 
electric braces work. However, problematic bindings defined in the various 
packages are usually not cured by this.

Which menu items are affected?

The menu items that the International Menus package change are (depending 
on which keyboard layout you use, some of these may remain unchanged):

Edit menu: Twiddle, Twiddle Words, Shift Left/Right, Shift Left/Right Space
Search menu: Return to Bookmark, Goto Line, Mark Hilite
Windows menu: Zoom, Default Size, Choose A Window

Teaching Alpha new keyboard layouts 
If you're not using a western keyboard or if you do encounter any problems,
reading the following section will help to clarify things and should help 
you to fix the problem. This section requires that you first read the 
section Changing Alpha's behavior. If you need help defining 
a new keyboard layout, subscribe to the ALPHA-D mailing list and ask for help.

To solve the problem with bindings in the menus you can use the 
menu::replaceWith command. To solve the problem with the Swiss keyboard 
described above you would add the following to your preferences file:
   
    menu::replaceWith winMenu [list "//<Szoom" "//<S<I<OsinglePage"] \
        items "<S//zoom" "<S<O<U/=singlePage"

To define your keyboard layout, add a line like this to your preferences 
file:

    set "keyboards(U.S.)" {
     {¤1234567890-=[];'\`,./}
     {±!@#$%^&*()_+{}:"|~<>?}
     <U/[
     <U/]
    }

The first two lines tell Alpha how to map using the 'shift' key. Shift maps 
each item in the upper string into the corresponding item in the lower 
string.

The third and forth lines defines the keybindings for the left and right 
braces, in this example to shift-[ and shift-].

See the file alphaDefinitions.tcl for examples of keyboard layout 
definitions.

If you define an array entry keyboards(my-country), then you can just 
select that in the international prefs dialog, and Alpha will set the flags 
correctly. You can then send that keyboard array entry to the ALPHA-D 
mailing list for inclusion in a future version of Alpha.

If a package wishes to be told when the keyboard changes, it can do 
that by registering with the 'removekeyboard' or 'keyboard' hooks like
this:

    # tell me when we switch to a "Swiss German" keyboard
    hook::register keyboard keys::swiss "Swiss German"
    # tell me when we disable a keyboard
    hook::register removekeyboard my_disable_proc
    # tell me when we enable a keyboard
    hook::register keyboard my_enable_proc
    
In this way a clever package could remove the need for restarting 
Alpha by unbinding and then rebinding all necessary items.

        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. Using the menu "Utils->Compare" you 
can either compare 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.

The comparison is done using a port of the unix GNU diff program.

Alpha opens the two files in windows at the top of the screen with the diff 
file at the bottom. You can navigate between individual differences in the 
diff file 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

Bugs: File comparison only works if the files have Mac line terminations.

        Helper Applications

Alpha uses many helper application, e.g. a web browser and an ftp client.
You can choose which helpers to use by the menu item
"Config->Preferences->Helper Applications". Select which helper app you want
to change.

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 app. 

        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 check 'Backup' in the 
preferences dialog "Config->Preferences->Backups". By default the backup file 
is saved in the same folder, and its name is formed by suffixing a tilde to 
the name of the saved file. The backup behavior can be modified by changing 
the following preferences in the dialog "Config->Preferences->Backups":

Backup              Check this if you want Alpha to make backups.
Backup Folder       The folder where to save the backups. If none specified 
                    the backups are saved in the same folder as the 
                    original.
Backup Extension    The extension to add to name of the backup file. Don't 
                    pick a long extension! The total file name mustn't be 
                    more than 31 characters.
Backup Age Requirement In Hours     A new backup file is only created if the 
                    old backup file is older than this.

If you have chosen a backup folder and want to go back to the default 
behavior of saving the backup in the document's folder this is how to do 
it:
Delete or rename the backup folder. Alpha will then ask you if you want to 
create the backup folder. If you answer 'No' Alpha will revert to the 
default behavior.

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 preferences dialog 
"Config->Preferences->Backups". Alpha then saves the documents every 'Changes 
Lim' changes. 'Changes Lim' can be set in the same preferences dialog. Note 
that Untitled windows are not autosaved.

        Spell Checking

Alpha has the capability to interact with the spell-checker 'Excalibur', 
written by Robert Gottshall and Rick Zaccone. The menu item 'Spellcheck 
Window' is always available in the "Text" menu. Selecting this item will 
start up Excalibur and open the current window in Excalibur. 
For version 1.4 and earlier, if Alpha has to launch Excalibur you will need 
to dismiss Excalibur's opening dialog by hitting the Cancel button. 
Subsequent selections of the menu item will switch right into Excalibur 
with the correct file displayed. 
When switching back from Excalibur to Alpha, Alpha reads the corrected 
version of the file into the current window.

There is also a menu item 'Spellcheck Selection'. This copies the current 
selection to the clipboard and switches to Excalibur. You can then use 
'Open Clipboard' in Excalibur's File menu to spellcheck the selection. 
When you switch back to Alpha you have to paste the corrected text 
yourself.

Excalibur can be obtained from http://www.eg.bucknell.edu/~excalibr/excalibur.html

        Tags

Alpha supports the use of tags to find declarations of functions; by
default this is set up only for 'C'. When searching for a tag, Alpha looks
for the tag file specified by the 'Tag File' preference, which can be set
in the dialog "Config->Preferences->Tags". Alpha's tag generating routines
use the regular expression in the preference 'Func Expr' to look for
function declarations. In other words, we don't parse the text. If you
declare your functions differently, you can change 'Func Expr' to suit your
own style. Alpha currently uses the following regular expression to find C
function declarations:

              ^[^ \t\(#\r/@].*\(.*\)$

Although complicated, this expression makes sense if you slowly wade 
through it. The string that we are looking for must take up an entire 
line. It must begin with a character other than '\t', '#', '\r', '/', ' ', 
'(', or '@'. There must be a set of parenthesis.   

Note that not only can you customize this to your style of 'C'
declarations, you could also use it to generate tags for other languages.
The only thing you need to bear in mind is that the tag routines use the
complete word previous to the first '(' in the selected line as the
function's name. If there is no '(' in the selected line, the last word in
the line is used. Therefore, Pascal procedures with or without parameters
can be identified.

Caveat: Apple's list manager can't handle more than 32k of text in the 
entire list, so there is a practical limit of 2000 or so tags in your 
project.

        Calculator

Alpha has its own calculator. This is just a quick-and-dirty RPN stack
calculator, which works on both signed and unsigned decimals, hex integers,
and floating point.

Operations:                                                          
    +,-,*,/,|,&,%   Top of stack is 'y', next is 'x'. Does x OP y.   
    ~               bitwise NOT                                      
    ^               x eor y                                          
    <               x << y                                           
    >               x >> y                                           
    c               change y's sign                                  
    q               duplicate y                                          
    i               swap x and y                                     
    m               switch signed/unsigned/hex modes                         
    x               show current mode
    h or ?          help
    <delete>        pop stack                                        
    <space>         enter number    
    opt-P           pi (3.14159265358979323)
    shift-opt-E     e  (2.718281828459045)

Invoke from the Utils menu, holding down the shift key.

        Alpha's Menus

This section is an explanation of Alpha's main menus, from "File" to
"Windows" (menu with the window icons). The menu items listed here are the
ones available when no features are enabled in the dialog
"Config->Preferences->Menus and FeaturesÉ". Some of these features add new
menu items or new submenus to Alpha's main menus.

Alpha uses Ramon Felciano's Mercury MDEF to display menus. In addition to
allowing other modifiers to be shown in the menu, this MDEF also allows
alternates, items that change depending on the state of the modifier keys.
Alternate items are tagged below by the modifier that must be pressed to
display it.

File
    New                     New file.
    OpenÉ                   Open file.
    Close                   Close file.
    Close All (option)      Close all files.
    Close Float (shift)     Close a palette.

    Save                    Save file.
    Save All (option)       Save all files.
    Save Unmodified (control) Save file without changing the modification 
                            date.
    SaveAsÉ                 Prompt for name to same file under.
    Save A Copy AsÉ (option) Save a copy of the open window.
    Rename ToÉ (shift)      Rename file.
    
    Revert                  Revert to last saved version, throw away undo history. 
    Revert To Backup (option) Revert to last backup copy, if any.
        
    File Utils
        File RemoveÉ        Remove a file.
        File InfoÉ          Display/edit info about a file.
        Text to Alpha       Set creator a text files to Alpha.
        Show in Finder      Select the front window in the Finder.

    Page SetupÉ             Set print options.
    PrintÉ                  Print window.
    Print All (option)      Print all windows.

    Quit                    Quit Alpha.

Edit
    Undo                    Undo. 
    Redo                    Redo. 

    Cut                     Cut selection to scrap.
    Copy                    Copy selection to scrap.
    Paste                   Paste from scrap.
    Select All              Select entire file.
    Select Paragraph (option)   Select current paragraph.
    Clear                   Delete selection.

    Twiddle                 Exchange characters bracketing the selection point.
    Twiddle Words (option)  Exchange words bracketing the selection point.

    Shift Left              Shift selection left one tab.
    Shift Left Space (option)   Shift selection left one space.
    Shift Right             Shift selection right one tab.
    Shift Right Space (option)  Shift selection right one space.
    Balance                 Select text out to the next set of matching braces.

Text
    Fill Paragraph          "Fill" paragraph that contains the insertion point.
    Wrap Paragraph (option) Break lines longer than 'fillColumn' in paragraph 
                            containing the insertion point.
    Sentence Paragraph (option-shift) - Forces each sentence to start on new 
                            line. 
    Fill Region             "Fill" selection subject to 'leftFillColumn' and 
                            'fillColumn'.
    Wrap Region (option)    Break lines longer than 'fillColumn' in selection.
    Sentence Region (option-shift) - Forces each sentence to start on new 
                            line. 

    Line To Paragraph       Convert a line to a paragraph.
    Paragraph to Line (option) Convert a paragraph to single line.
    
    Sort Lines              Sort selected lines.
    Reverse Sort (option)   Sort selected lines backwards.
    Spellcheck Window       See here.
    Spellcheck Selection (control)

    Zap Invisibles          Delete all chars in file with ASCII code < 32, except 
                            for LF, TAB and CR.
    Tabs To Spaces          Convert tabs to space runs.
    Spaces To Tabs (option) Convert space runs to tabs.

    Indent Line             Indent the current line.
    Indent Selection (option) Indent the selection.
    
    Upcase Region           Upcase all chars in region.
    Downcase Region (option) Downcase all chars in region.
    
    Strings
        Insert Prefix           Prepend string 'prefixString' to every line in 
                                selection.
        Remove Prefix (option)  Remove prefix string from lines in selection. 
        Insert Suffix           Append string 'suffixString' to every line in 
                                selection.
        Remove Suffix (option)  Remove suffix string from lines in selection. 
        Set Prefix              Change prefix string.
        Set Suffix              Change suffix string.
    Comment Line            Comment out line, considering mode.
    Uncomment Line (option) Un-comment line, considering mode.
    Comment Box             Create a comment box around selected text.
    Uncomment Box (option)  Remove such a comment box.
    Comment Paragraph       Comment out a paragraph.
    Uncomment Paragraph     Uncomment a paragraph.

Search
    FindÉ                   Present a search dialog.
    Search Start (option)   Return selection point to where the last search 
                            started. 
    Find Again              Search forward again with same settings.
    Find Again Backward (option)    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 (option)   Use the current selection as replace text.

    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 (option)  Same as Quick Find but lets you use a regular
                            expression.
    Reverse Quick Find      Same thing in reverse.
    
    Replace                 Replace the selection.
    Replace and Find Again  Replace the selection and search again forward.
    Replace All             Replace all of occurances of the search string 
                            in the rest of the file.
    Replace in Fileset (control)    Global replace in fileset.
    
    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.
    Goto Line               Goto specific line number.
    
    Matching Lines          Find all lines that match a regular expression and 
                            summarize in new window. 
    Goto Match              Jump to the original text specified by the current 
                            line in a "Batch Find" or "Matching Lines" window.
    Next Match              Jump to the original text specified by the next 
                            line in a "Batch Find" or "Matching Lines" window.
    Goto Func               The same as selection an item in the Funcs menu (the 
                            one with two curly braces at the right top of the window)
    Goto File Mark          The same as selection an item in the Marks menu (the 
                            one with the M icon at the right top of the window)
    Mark Hilite             Select text last manipulated, such as from a paste.
    Named Marks->           Manipulating named marks.
    Unnamed Marks
        SetÉ
        Exchange Point And Mark

Utils
    Compare
        Windows             Compare top two windows, sending output to a third. 
                            Selecting a line in the third window and hitting 
                            return (or enter) moves that line to the top of 
                            the window.
        Files               Same as above, but prompts for files.
        Directories         As above, but works for entire folders. 
    
    Win Utils
        Insert Path NameÉ   Prompt for a file and insert complete pathname in 
                            window.
        Insert FileÉ        Insert the text of another file.
    
    Ascii Etc
        Quote Char          Wait for key press and insert key.
        Key Code            Wait for key press and insert keycode and modifier 
                            string suitable for key binding.
        Key Ascii           Same as above, but use ascii form.
        Get Ascii           Display ascii code for char to right of insertion.
        Insert Ascii        Prompt for ascii code and insert character.
        
    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. 
    Toolserver Shell (control) See here.
    Calculator (shift)      See here.
    
    Word Count              Count lines, words, chars in window.
    Send URL                Send selection as URL to proper internet application.
    Cmd-Double Click        See here.
                            
Config
    Preferences             Set global preferences.
        Menus and FeaturesÉ Change global menus and features.
        Suffix MappingsÉ    Displays and allows editing of suffixes (really
                            filename patterns) for all existing modes. 
        Edit Prefs File     Put your own arbitrary startup code here. 
                            Loaded after all standard Tcl code. 
        Interface Preferences etc. The rest of this menu is used to set 
                            preferences.
                            
    Packages
        Miscellaneous PackagesÉ     Set preferences for packages.
        Describe A PackageÉ         Show a description of a package.
        Read Help For A PackageÉ    Opens the documentation for a package.
        Uninstall Some PackagesÉ    Uninstall one or more packages.
        Internet Updates->          To download packages from Internet.
        Rebuild Package Indices     The Alpha's index of all installed 
                                    packages.
                            
    Mode Prefs              Set preferences for current mode.
        Menus and 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.
        Describe mode       Describe current mode's variable settings and 
                            bindings.
        Change ModeÉ        Change the current mode.

    Set Font TabsÉ          Change font and/or tabs for current file.
    Special KeysÉ           Set key bindings for electric features.
    Describe BindingÉ       Wait for a keystroke, then display that keystroke's 
    List Packages           List all installed packages.
    List All Bindings       List all current key bindings.
    List Global Bindings (option) List all current global key bindings.
    List Functions          List all functions currently defined, both
                            "core" functions (those coded in C), and those
                            coded in the supplied Tcl files.
    View Saved SettingsÉ    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 SettingsÉ  This function allows settings to be removed.

    Redefine Colors->       See Coloring.
            
Windows (an icon with three windows)
    Zoom                    Zoom windows in and out.
    Default Size (option)   Resize window to default size.
    Choose A Window         Choose window to select from list (proc 
                            chooseAWindow).
    Iconify                 Toggle iconification of front window.
    Arrange->               Rearrange open windows.

    Split Window            Split window into two panes, or unsplit.
    Toggle Scrollbar        Toggle the horizontal scrollbar on the frontmost 
                            window. 

        Installing New Packages
        
Where to find new packages

Currently the best place to look for new packages is 
<ftp://ftp.ucsd.edu/pub/alpha/>.
For those from Europe, you may wish to try the mirror: 
<ftp://anu.theologie.uni-halle.de/comp/mac/Alpha>

Using the menu "Config->Packages->Internet Updates" Alpha can download and
automatically install packages for you.

[to be continued]

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 menu item "Config->List Packages" lists all packages which are 
installed. The list contains the package names, versions, and maintainers.

If there is no read me file accompanying the package you are about to 
install, you can find the version number in the beginning of the tcl file. 
Look for a line of one of the forms:
alpha::extension <name> <version> ...
alpha::menu <name> <version> ...
alpha::mode <name> <version> ...
Make a sure the number given by <version> is higher than the one for the 
currently installed package.

Installing

How to start the installation depends on if the package you are about to 
install is accompanied by a file 'READ ME TO INSTALL' (or similar) or is 
just a single file someName.tcl.
¥ If there is a file 'READ ME TO INSTALL', open it (hence the name!). All 
packages built up of more than one file must actually have such a read me 
file in order to be possible to install. If there is a file 
installScript.tcl (or similar), don't open it. It only contains 
instructions to Alpha what to install.
¥ If there is only a single file someName.tcl, open it. Some single file 
package are configured to automatically close themselves and open a 
installation dialog. Otherwise proceed as below.

If there are instructions in the read me file how to install the package, 
follow them (of course!). In other cases this is how a typical installation 
is made.
¥ After you have open the read me file or the single someName.tcl, make 
sure Alpha has inserted a menu 'Install' in the menu bar. This means Alpha 
is in installation mode. If not, you can manually switch to installation 
mode by selecting 'Inst' in the mode popup menu in the statusbar.
¥ Select 'Install This Package' from the Install menu.
¥ An installation dialog is now opened. Here you can choose to make an Easy 
Install or a Custom Install. The Custom Install lets you choose exactly 
what to install. The Easy Install installs everything. If you are not sure 
which files you need use the Easy Install. 
¥ There are also two options in the installation dialog.
If 'Backup removed files' is checked Alpha will save any removed file in a 
folder InstallationBackup in Alpha's folder. This as a safety measure so 
you can recover any changes you may have made to them or so you can switch 
back to them if the newly installed package doesn't work as you wish.
If 'Show installation log' is checked a window is opened after 
installation showing which files have been put where and which files have 
been deleted.

After Alpha has put the files in there correct location Alpha rebuilds its 
index files. This make take a little while. The index files are used by 
Alpha to keep track of where the various packages and function are.

After the installation is completed you must quit and restart Alpha.

If something goes wrong

What to do if you're unlucky and have installed a package which simply
doesn't work, possibly crashing Alpha when it's launched? The obvious thing
is then to uninstall the package. If Alpha can be launched with the new
package installed you can uninstalling it using the method in the next
section.

If the newly installed package causes Alpha to crash when you launch it,
the situation is more problematic. Then you have to manually delete some
files to make Alpha run again. First delete the files you've just
installed. During the installation the package's files are copied to
various locations in the folder "Tcl" inside Alpha's folder. Locate and
delete the ones with the same names as the ones in the set of files you
installed. Then before you launch Alpha again you have to delete a folder
from Alpha's preferences folder. Alpha's preferences folder is called
"Alpha-v7" and is located in the Preferences folder in the system folder.
Delete the folder "Cache" inside "Alpha-v7". Deleting the folder "Cache" is
harmless. It will be re-created the next time you launch Alpha. It is very
likely, though, that the old content was causing Alpha to crash.

If this doesn't help, as a last way out try removing the complete
"Alpha-v7" from the Preferences folder.


        Uninstalling Packages

Many packages support a mechanism for uninstalling them. Please note before 
starting to uninstall packages you think you won't ever need that the only 
thing you save by uninstalling a package is disk space - unless you have 
installed some buggy package causing obvious problems. Installed packages 
which are not in use, i.e. either not enabled through the dialog 'Menus and 
Features' or modes which are not used, are never loaded into Alpha's 
memory. Thus you do not save any memory by uninstalling packages. Thus if 
you have plenty of disk space, there is hardly any point in uninstalling 
anything.

Uninstalling a package in done using the menu item
"Config->Packages->Uninstall Some Packages". Select the package you want to
uninstall from the popup menu in the dialog. All files belonging to the
package are now permanently deleted. Only a reinstallation will restore the
package.

After the uninstallation you must restart Alpha.

If you can't find the package you want to uninstall in the popup menu, it 
means that the package doesn't support the mechanism for automatic 
uninstallation. In this case the only way uninstall the package is to 
manually find the files belonging to the package and delete them. Don't use 
this method unless you know what you are doing. Deleting the wrong files 
may result in all sorts of troubles.

        Changing Alpha's behavior
        
The rest of the manual discusses some general topics about how to extend 
Alpha by writing 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. There is one global
preferences file which is loaded when Alpha is launched. In this file you
should put code which should be loaded regardless of which mode you're
working in. This preferences file is opened using the menu item
"Config->Preferences->Edit Prefs File".

Then there is one preferences file for each mode. The file for a mode is
loaded after as the last code to be loaded when a mode is used the first
time. This preferences file is opened using the menu item "Config->Mode
Prefs->Edit Prefs File".

These preferences files are intended for code for personal use. If you want 
to write a complete new package for Alpha, which others also can use, read 
the file Extending Alpha.
        
        ALPHA-D mailing list
        
There is mailing list for Alpha where you can discuss problems, suggest new 
features etc. To subscribe, email <listserv@listserv.syr.edu> and, in the 
body of your message (not the subject line), write: 
SUBSCRIBE ALPHA-D

There are a number of known bugs which will hopefully be corrected in a 
future release. PLEASE read the Bug Reports and Debugging file for a list 
of known bugs, and for how to give an informative bug report, without which 
it is unlikely any bug you found can be fixed.
        
        Key bindings
        
Any Tcl command can be bound to any single keystroke. One way to bind a 
function is with a statement such as:
  
      Bind 'c' <modifier string> funcName [<mode>]
          
where c is a character, <modifier string> is an optional string containing 
one or more of:

      c   - command modifier
      o   - option modifier
      s   - shift modifier
      z   - control modifier
      e   - escape modifier      

'mode' is an optional parameter that specifies, when present, that the 
binding is only active in a given mode. Note that given a general binding 
(no mode specification) and a binding specific to the current mode, the 
last binding to have been created is the one found first.

For example, the following line binds cmd-shift-f to the function 
'forwardChar':

    Bind 'f' <cs> forwardChar

Additionally, the modifier string can contain a capital letter specifying 
that the binding is only activated if preceded by control and the lowercase 
version of that letter. This feature allows multiple-key combinations a la 
Emacs. This requires that ctrl-<the character> is bound to the function 
'prefixChar'. By default ctrl-C, ctrl-Q, and ctrl-X are bound to 
'prefixChar'. The next line would bind 'forwardChar' to ctrl-x ctrl-f:

    Bind 'f' <cX> forwardChar 

Additionally, most keyboards have keypads and/or function keys. These 
keys can be bound using case-insensitive numeric labels using the same 
bind command as above, with the label replacing the character. For 
example, to bind F1 to function 'funcName', the following would work:

    Bind F1 funcName

As above, the binding can include a modifier string. The following labels 
are defined:

  Esc F1 F2 F3 F4 F5 F6 F7 F8 F9 F10 F11 F12 F13 F14 F15 Help Home Pgup Del 
  End Pgdn Left Right Up Down Clear Kpad0 Kpad1 Kpad2 Kpad3 Kpad4 Kpad5
  Kpad6 Kpad7 Kpad8 Kpad9 Kpad= Kpad/ Kpad* Kpad- Kpad+ Enter Kpad.

The above labels may not be sufficient for all keyboards (attention
international users). In particular there are some problems when binding to
accented characters (more about that below). If a hex number is used
instead of a character inside the single quotes, the binding is done to key
codes instead of ascii values. The following is a key code version of the
same binding:

    Bind 0x03 <cs> forwardChar

The key code for any given key can be obtained by selecting the menu item 
"Utils->Ascii Etc->Key Code" and then typing the key. Alpha then types the 
key code.

Also, there is an alternate form that allows the specification of an 
ascii code directly:

    ascii 0x20 <z> setMark
    
Binds control-space to 'setMark'. The ascii code for any given key can be 
obtained by selecting the menu item "Utils->Ascii Etc->Key Ascii" and then 
typing the key. Alpha then types the ascii code.

Note that menu item command equivalents take precedence over bindings, and 
that the 'Bind' command does not affect the command equivalents displayed 
in the menus. Also note that key code bindings take precedence over ascii 
bindings.

Finally, there are 'unBind' and 'unascii' functions, with identical 
arguments to their counterparts. 

Bindings to accented characters

To bind to an accented character is not always as straight forward as 
binding to an un-accented one. 

Accented characters which can be typed directly without using a dead key, 
you can bind to them as long as they have a modifier different from <s>. As 
an example with a French keyboard

    Bind 'Ž' <c> ...
    Bind 'Ž' <z> ...
    
works fine, but

    Bind 'Ž' ...
    Bind 'Ž' <s> ...
    
does not. In the latter case the key code has to be used instead:

    Bind 0x13 ...
    Bind 0x13 <s> ...

Accented characters which are obtained using a dead key has to be bound 
using ascii, e.g '“' on a French keyboard:

    ascii 0x93 ...

What to bind to?

When you want to define a new key binding you obviously want to use a key
combination which is not already in use. There are two different ways to
find if a key combination is free. 

First, the menu item "Config->List All Bindings" will list all of the
bindings currently in effect.

Second, you can use "Config->Describe Binding" to find what a certain key
combination is bound to. Select "Config->Describe Binding" and then hit the
key combination you are interested in. Alpha will then display a dialog
saying which function the key combination is bound to, or "Key combination
unbound." if it is not bound to anything. 

There is one thing to note about bindings involving the shift key. If there
is nothing bound to a key combination including the shift key, typing this
key combination will have the same effect as the one wihout the shift key.
A specific example to clarify this: command-P is bound to "print", but
there is no binding defined for command-shift-P. Still hitting
command-shift-P has the same effect as hitting command-P. But if you now
define a new binding for command-shift-P, then command-P and
command-shift-P will have different functionality.

        Menus, user-defined
        
If you want to make your own menu with your personal Tcl functions, this 
section explains how to do it. If you want to add new menu items to the 
existing menus, see the next section for instructions. However, in that 
case you also need to read this section.

Alpha's menu commands allow the user to build custom menus which contain
names of functions, macros, or arbitrary TCL commands that just HAVE to be
in the menus, as opposed to being merely callable through the bindings. The
menu items are defined as a list of strings. The following meta characters
can be embedded in the strings:

   Meta-character     Usage
   --------------     -----

    ; or Return       Separates multiple items.
    ^                 Followed by an icon number, adds 
                      that icon to the item.
    !                 Followed by a character, marks the
                      item with that character.
    <                 Followed by B, I, U, O, E, or S,  
                      sets the character style of the item.
    /                 Followed by a character, sets up
                      a keyboard equivalent.
    (                 Disables the item. Use (- to get a 
                      separator line.

The following modifiers can be used to require other combinations of 
modifiers than just the command key. Control-option, for instance, is 
specified by putting the string "<B<I" in the menu item. The menu symbol 
for shift is an upward outline arrow, control is the outlined ^ symbol 
("Wins->Iconify" has one), and option is the wavy line with the dot in the 
upper right ("Search->Replace All" has one). The following are characters 
that can follow the '<' and what they signify.

    B       - control key required
    I       - option key required
    U       - shift key required (only for alpha-numerics!)
    O       - command key required
    S       - is part of a dynamic item.
    E       - forces item to start new dynamic item.


A '/' followed by a character in the left column sets up a keyboard 
equivalent for the key in the right column:

    a   Enter           n   F10
    b   Return          o   F11
    c   Tab             p   F12 
    d   Num Lock        q   F13
    e   F1              r   F14
    f   F2              s   F15
    g   F3              t   Help
    h   F4              u   Del
    i   F5              v   Forward Del
    j   F6              w   Home
    k   F7              x   End
    l   F8              y   Page Up
    m   F9              z   Page Down
    
The menu creation syntax is :

    Menu [-s] <-n name> <-i num> [-p procName] [-m] [-M <mode>] "Tcl list of menu items"

Where the arguments have the followings meanings:
  -s            Use system menu definition proc (faster).
  -i <num>      Resource id of icon suite to use for menu title.
  -n <name>     Name of menu.
  -m            No menu form. If not supplied, each menu item is split into 
                words at each capitalized letter.
  -p <pname>    Rather that having alpha call a Tcl proc named by the menu 
                item's text, this option tells Alpha to call the tcl proc 
                named by 'pname' with two arguments: the menu name, and the
                text of the menu item chosen.
  -M <mode>     Bindings only take effect in specified mode.
  
The 'Tcl list of menu items' can include another menu definition allowing 
you to create hierarchical menus. Once the menus are created, they can be 
inserted and deleted from the menu bar by the syntax:

   insertMenu "name"
   removeMenu "name"

As alluded to above, Alpha attempts to make procedure names readable in the 
menus by separating words at any capitalized letter. For example, 
'findFile' becomes "Find File". This function is turned off by the '-m' 
option. 

Menu items can be enabled and disabled through the TCL command 
'enableMenuItem'. Menu items checkmarks can be turned on and off via 
'markMenuItem'. Menu items can be appended via 'addMenuItem' and deleted 
via 'deleteMenuItem'. See the "Alpha Commands" help file for syntax.

As explained above, Alpha uses various keys to specify text style and key 
equivalents. Sometimes you may want these characters included in your text 
literally. If an ampersand ('&') is the last character in a menu item, 
these special characters are not interpreted.

If an ellipsis ('É') is the last character in a menu item (except possible 
for the above ampersand), it is stripped off before searching for the 
function corresponding to the chosen item.

        Modifying Alpha's menus
        
Alpha's global menus and most mode menus can be modified using commands
menu::insert, menu::removeFrom, and menu::replaceWith. The use of these are
explained in the section Adding items to global menus in the file Extending
Alpha.

        Event hooks
        
When certain events occur. e.g. when opening and closing windows, Alpha 
calls an event hook. You can register your own event hooks to add to the 
default behavior when the corresponding event occurs. Below is a table of 
all available hooks. 

To add your own hook there are two things you have to do. First write a 
proc to be called when some events occurs. This proc must have the 
parameters shown in the table. Lets say you want to define a saveHook. 
Then define some proc

    proc mysaveHook {name}{
        .
        .
    }
    
The next thing you have to do is to register the proc. This is done with a 
line like:

    hook::register 'hook-name' 'your proc' 'mode' ?... 'mode'?

The optional mode parameters specify in which modes the hook will be 
called. If no mode parameters are given the hook will be called regardless 
of the mode. Avoid this unless absolutely necessary.

Let's assume that you want your hook to be called in TeX and Perl modes. 
To register it you would use the line:

    hook::register saveHook mysaveHook TeX Perl

Note, however, that a few hooks doesn't use the mode to determine when to 
be called and should be registered slightly differently, see below.
    
Window hooks
  Hook                                              Parameter(s)
¥ activateHook                                      path to file
  Called when a window is brought to front
¥ deactivateHook                                    path to file
  Called when a window is sent to back
¥ openHook                                          path to file
  Called when a window is opened
¥ closeHook                                         path to file
  Called when a window is closed
¥ saveHook                                          path to file
  Called when a window is saved
¥ saveasHook                                        path to old file, path to new file   
  Called when a window is saved as
¥ savePostHook                                      path to file
  Called after a window is saved
  
Alpha hooks
  Hook                                              Parameter(s)
¥ startupHook
  Called at the end of startup
¥ quitHook
  Called when quitting Alpha
¥ suspendHook                                       an empty string
  Called when switching to another app
¥ resumeHook                                        an empty string
  Called when switching to Alpha from another app
  
Mode hooks
  Hook                                              Parameter(s)
¥ mode::init
  Called the first time a mode is loaded
¥ changeMode                                        new mode
  Called when the mode is changed
¥ dialog::modifyModeFlags                           a string (title of dialog)
  Called after a mode prefs dialog is closed
¥ mode::editPrefsFile
  Called when a mode prefs file is opened 
  for editing
  
Keyboard hooks
  Hook                                              Parameter(s)
¥ keyboard
  Called at startup and when the keyboard prefs 
  is changed
¥ removekeyboard
  Called when the keyboard prefs is changed
  
The keyboard hooks use the keyboard name (the ones in the keyboard popup menu 
in the International preferences dialog) rather than the mode to determine 
when to be called. Thus to register a keyboard or removekeyboard hook use 
lines like:

    hook::register 'hook-name' 'your proc' 'keyboard name' ?... 'keyboard name'?

Miscellaneous hooks
  Hook
¥ launch
  Called when a helper app is launched by calling app::ensureRunning
  
The launch hook uses the application signature rather than the mode to 
determine when to be called. Thus to register a launch hook use a line like:

    hook::register launch 'your proc' 'signature' ?... 'signature'?

¥ requireOpenWindowsHook    
  Called when opening and closing windows.

This hook is used to en-/disable meaningless menu items which would require 
the presence of a certain number of windows to be active. You can register 
your own menu items using a line like:

    hook::register requireOpenWindowsHook [list menu item] N

where 'N' is the number of windows required (1 or 2 usually)

As an example, this is a line from Diff mode registering the item 'Compare 
Windows' to require 2 open windows to be enabled.

    hook::register requireOpenWindowsHook [list compare windows] 2

        modeCreator

The modeCreator array allow you to tell Alpha which mode to choose when you 
open a window depending on which application has created the file. Add to 
this array with lines like:

    set modeCreator(<signature>) <mode>
    
'Signature' is the signature of the application which has created the file 
and 'mode' is the mode which you want Alpha set for the window. For 
example, to open all files created by Netscape in HTML mode use the line:

    set modeCreator(MOSS) HTML
    
Tip: To find the signature of an application, launch it, open the Tcl 
shell (command-Y) and type 'ps' at the prompt. This will list all running 
applications; the second column lists the signatures.

        unixMode

When you open unix files where the first non-empty line reads 
'#!/dir/subdir/command ...' then Alpha tries to find a mode corresponding to 
'command'. With the unixMode array you can tell Alpha which mode to choose 
when opening such a file. Add to this array with lines like:

    set unixMode(<command>) <mode>
    
where 'command' is the command in the line '#!/dir/subdir/command ...' and 
'mode' is the mode which you want Alpha set for the window. For example, to 
make Alpha open files with a line '#!/dir/subdir/perl ...' in Perl mode use 
the line:

    set unixMode(perl) Perl

        Word breaking
        
Alpha allows you to redefine its internal notion of what a word is, through 
the preferences 'Word Break', and 'Word Break Preface'. 'Word Break' is set 
to a regular expression that defines a word to you. 'Word Break Preface' 
should be a regular expression that matches exactly one of any characters 
that are not in your word definition.

The value of 'Word Break' and 'Word Break Preface' are mode dependent, as 
what is meant by a word may be different for different types of text. For 
example, in Text mode the default definition of 'Word Break' is '\w+'. This 
matches any contiguous sequence of contiguous alphanumeric characters.

The default value in Text mode for 'Word Break Preface' is '(\W)', 
basically just the negation of any any of the characters in your 'Word 
Break' definition.

The need for both these variables in backward searches can be seen as 
follows. Suppose your window's text is 'hey hello', and the current 
insertion is between the two 'l's. Now, searching backwards for the above 
'Word Break' definition will take the insertion to between the 'e' and the 
first 'l', not really where we want to say is the start of the word. By 
contrast, if we search backwards for 'Word Break Preface' and 'Word Break' 
concatenated together, and then move forward one character after a 
successful search, we end up right before the 'h' in 'hello', just where we 
want to be.

There are also two similar preferences 'Wrap Break' and 'Wrap Break 
Preface' used for automatic word wrapping. In Text mode their default 
values are '[\w_]+' and '([^\w_])' meaning that wrapping should not occur 
between alphanumeric characters or underscore.

