AlphaTcl Support Folders Help
Alpha
Version:9.0a14
Last update:2017-02-13 09:08:43



The Tools ↣ Support Folders submenu provides support for access to the Support Folders used by AlphaTcl. There are two possible Support Folders available: one for system administrators (referred to as local) and one for individual users (referred to as user). 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.

Support Folder Locations

There are two possible Support Folder locations, referred to as local (for system administrators) and user (for the current user). These names correspond to two of the domains used in Mac OS X: Select the Tools ↣ Support Folders ↣ Support Folders Status menu item to find out the current Support Folders status. To locate them in the Finder, select Alpha ↣ Preferences ↣ Show Support Folder… or click here .
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.

Possible Support Folder Uses

Some of the standard AlphaTcl packages use Support Folders to store editable files such as Filters, Macros, Templates, Notes, AppleScripts, or anything else that might be used during the course of an editing session: see the Standard AlphaTcl Packages section.
When you install new AlphaTcl packages, the files are placed in the Support Folder hierarchy too: see the New AlphaTcl Packages section.
Modified AlphaTcl files (i.e. changes to the .tcl files included in Alpha's standard distribution) can be placed in Smart Source support folders to change some default program behavior: see the 'Smart Source' Support Folders section.
The Tools ↣ Support Folders menu allows you to easily open a file in a Support Folder, save the active window in a Support Folder, or show the Support Folder in the Finder.

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.

New AlphaTcl Packages

New AlphaTcl packages (i.e. those not included in the standard distribution) that include an OPEN-TO-INSTALL installer file are automatically installed in one of the Support Folders.
Both the local and user Support Folder directories include a folder named AlphaTcl/Tcl, which in turn contains folders named These folders should be used to install third-party packages, i.e. those which are not contained in the standard distribution. Each Support Folder's AlphaTcl folder will also include the following directories: 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.

'Smart Source' Support Folders

As described in the New AlphaTcl Packages section, the AlphaTcl folders can be used to add new AlphaTcl packages.
They can also serve as Smart Source folders for files in the standard distribution, allowing you to modify Alpha's default behavior. In order to make use of this functionality, you need to know
  1. the name of the file you wish to modify, and
  2. how the AlphaTcl code directs certain behaviors.
If you want to modify Alpha's behavior, you probably want to first post a question to one of the mailing lists described in the Readme file; hopefully somebody will tell you which file is responsible for the operation you want to enhance. Once you know the name of the file, select the command Tools ↣ Support Folders ↣ Open AlphaTcl File and navigate to the file you need to inspect.
Sometimes you can use this item to just browse the hierarchy to view the contents of an AlphaTcl file. The source code for the Ada mode will, for example, most likely be found in the AlphaTcl ↣ Tcl ↣ Modes folder, and the file adaMode.tcl would be a very good guess.
Once you have selected a file name, a copy of this file will then be placed in your user Support Folder. This file is now considered a Smart Source version, and will be used the next time that you launch Alpha. It will continue to be used as long as it resides in your Support Folder, even after you upgrade Alpha to a newer version.
To stop using this as a Smart Source file, you can either delete it, or change its name. One common practice to temporarily disable a Smart Source file is to change its extension from .tcl to .txt.

Rebuilding Package Indices

Alpha stores a cache of startup information for each package to make the process of launching Alpha and loading these packages more efficient. The information stored in [alpha::package] declarations, such as
alpha::mode
alpha::menu
alpha::feature
alpha::extension
alpha::library
is included in this cache. If you change any of the information in these package declaration scripts, your AlphaTcl Package Indices need to be rebuilt in order for the changes to take effect. You can select the command Alpha ↣ Preferences ↣ Rebuild Caches… at any time to perform this operation. After rebuilding package indices, you need to immediately quit Alpha and restart it.
As explained above, Alpha does its best to detect that you have added new packages to your AlphaTcl library. If you have added a package in the AlphaTcl hierarchy of your Support Folder and package indices were not automatically rebuilt, 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.

Trouble-shooting Smart Source Files

While Tcl is a fairly easy language to learn, like any programming language it is easy to make a small mistake in the code which will completely disable some functionality. You will be able to compare your Smart Source file against the original at any time.
Just select Tools ↣ Support Folders ↣ Open AlphaTcl File and navigate to the name of the file in question. If you have already created a Smart Source version of this file, you will be offered several choices, including one to open the original version. Select this option, and then select the menu item Tools ↣ Compare ↣ Windows to view the windows side-by-side to see what is different between them.
See also Debugging Help for more trouble-shooting tips.

'Smart Source' vs 'Smarter Source'

For most users who are only working with one installation of Alpha, the Support Folders Smart Source feature is sufficient. There is also an AlphaTcl package Smarter Source which extends this type of over-ride functionality even further. The difference between the two is somewhat subtle, but can be very important.
You only have one Support Folder for Alpha that will be used by all versions of Alpha that you might have installed. Smarter Source Folders, on the other hand, are specific to the particular version of Alpha that you are using, because the location of the Smarter Source Folder is defined in your preferences, and each Alpha installation is allowed to define its own Prefs folder. Smarter Source files are generally used by AlphaTcl developers who need to maintain the latest stable version of Alpha while they are also working on the latest, cutting-edge beta version of the application and its supporting AlphaTcl library. See the Smarter Source Help file for additional information.
A similar logic applies to the User Packages folder that is contained in your preferences folder. This is an alternative location for new packages, again specific to each Alpha installation. For most users, new packages should simply be installed in Support Folders so that you only need to worry about one location that contains all of your AlphaTcl modifications.

System Administrator Notes

Alpha maintains two different Support Folder locations. Each user has one specific to his/her account, and there is a single local Support Folder. This local folder will be in play for all users, and this is where you can place new packages, or provide over-ride files for pre-existing ones in the standard AlphaTcl distribution. The order of precedence is
  1. $SUPPORT(user)
  2. $SUPPORT(local)
  3. $HOME
See the AlphaTcl Developer Notes section, for an explanation about the SUPPORT variable.
If the package Smarter Source has been turned on, all files in the user's Smarter Source hierarchy take precedence over others.
The Tools ↣ Support Folders ↣ Open AlphaTcl File command will always make a copy of either the $HOME (or if it exists, the $SUPPORT(local)) file in use and place it in the $SUPPORT(user) hierarchy. If you, acting as the system administrator, decide to make your version the default one used for all users, you must copy it manually to your $SUPPORT(local) hierarchy. Use the Alpha ↣ Preferences ↣ Show Support Folder… to expose both locations in the Finder, and then copy the files as needed.
This helps ensure that your personal modifications will not be available by other users unless you take some explicit action to make this the case.

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.

Known problems

Please report any problem or bug you encounter to Alpha's Bug Tracker.

License and Disclaimer

All rights reserved.
The Support Folders package is free software and distributed under the terms of the new BSD license:
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL CRAIG BARTON UPRIGHT BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
This document has been placed in the public domain.