Alpha
Version:	9.2.3 - "Suhail"
Last update:	2021-05-21 14:43:30

Alpha makes use of Application Support folders in which auxiliary resources may be stored. Many packages take advantage of these folders to install the data they manage. For instance, the user defined filters created via the Filters Menu are installed in a Filters subfolder of an Application Support folder folder. Similarly notes produced via the Notes package, templates produced by the Function Comments package, dictionaries handled by the Dictionary package, macros recorded using the Tools ↣ Macro Recording submenu are installed there.

Support Folder Locations

There may be two Application Support folders for Alpha:

the User's Application Support folder: ~/Library/Application Support/Alpha. This folder is created automatically by Alpha if it does not exist already. It contains resources which are available only to the currently logged user.
the Local Application Support: /Library/Application Support/Alpha. This folder must be created by a superuser with admin privileges. It contains resources which are available to any user of the machine.

Support Folders allow the user to create/edit files that will be stored outside of the application bundle's file hierarchy, so that they will be available after program updates. The contents of these Support Folders can also be copied and installed in other computers.
When the local Support Folder exists, its files contents are available to all users of the system but only the system administrator has the write permissions to add, edit or remove these files.
If you keep all of your AlphaTcl modifications in your Support Folder, you will be able to easily install them on other computers if desired; just locate it using the Alpha ↣ Preferences ↣ Show Support Folder… command, make a copy of the entire folder, and move it to the proper location on another machine.

New AlphaTcl Packages

New AlphaTcl packages (i.e. those not included in the standard distribution) should be installed in one of the Support Folders.
Both Support Folders (user and local) contain an AlphaTcl subfolder with exactly the same structure as the main AlphaTcl library contained in the application's bundle:

    --- AlphaTcl
       |--- Examples
       |--- Help
       |--- Tcl
           |--- Completions
           |--- Menus
           |--- Modes
           |--- Packages
           |--- SystemCode

These folders should be used to install third-party packages, i.e. those which are not contained in the standard distribution. AlphaTcl/Tcl contains folders named Completions, Menus, Modes, Packages. Each Support Folder's AlphaTcl will also include the following directories: ((li Help li)), ((li Examples li)). The contents of these folders are queried to determine which help or example file should be presented to the user.
Alpha does its best to detect that you have added new packages to your AlphaTcl library and to rebuild the package indices if necessary. If you have added a package in the AlphaTcl hierarchy of your Support Folder and package indices were not automatically rebuilt next time you launched Alpha, you must select Alpha ↣ Preferences ↣ Rebuild Caches… in order to ensure that the new packages are recognized. This is especially true if you are copying a Support Folder from one computer to another.

Standard AlphaTcl Packages

Some examples of AlphaTcl packages in the standard distribution which make use of Support Folders include the following:

Filters Menu.: The Filters Menu is distributed with a default set of filter files. System administrators can supplement the default set by placing new files in the local Support Folder hierarchy. They can also add new filters by placing them there.
Users can create their own filters, stored in the user Support Folder hierarchy. Users can also over-ride the default versions of installed filters by editing Support Folder copies of them.
License Templates: The License Templates package provides a default set of templates (such as All Rights Reserved or Gnu Public License) that are inserted into the active window by the package Document Projects or the package Electric Menu . The user (and the system admininistrator) can re-define these templates, or add new ones. All modified license template files are stored in a .../Templates/Licenses/ Support Folder.
Macros: The Macros package allows users to save commonly used macros; these are automatically stored in their user Support Folder hierarchy.
Notes: The Notes package creates a folder in which users can store files easily accessed by the File ↣ Notes menu. The default location of these note files is in the user Support Folder hierarchy.

AlphaTcl Developer Notes

SUPPORT is a global variable defined either by the core Alpha application or (if necessary) by the AlphaTcl System Code. The SUPPORT array will always exist, with local and user entries. AlphaTcl code that wants to make use of these variables should always confirm that the directories referred to by the array entries are not the empty string, as in

if {($SUPPORT(local) ne "")} {
	...
} elseif {($SUPPORT(user) ne "")} {
	...
} else {
	...
}

If the array entries have any value other than "", assume that the folders did in fact exist when Alpha was launched. (Yes, if the user deletes these folders while Alpha is running, there will probably be trouble, but normal error handling should take care of this.)
See the files filtersMenu.tcl and macros.tcl for examples of how SUPPORT folders are used in AlphaTcl.