AlphaTcl Support Folders Help
Name:Support Folders Tool
Version:1.1
Last update:2019-10-17 13:28:26



When the Support Folders Tool package is activated, there is a new Tools ↣ Support Folders submenu which 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).
For more information about Application Support folders see the Application Support Help page.

Support Folder Locations

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 .

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.

'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

As explained elsewhere (see Application Support Help), 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.

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.