Alpha Dev Menu Help
Name:Alpha Developer Menu
Version:1.5
Last update:2019-11-27 14:12:55



This package creates an Alpha Dev menu (represented in the menu bar by a letter α with a wrench) that can be placed in the main menubar. This menu includes utilities for creating and modifying the Tcl code used by Alpha. It can also be activated for specific modes, such as Tcl or Chng.
See the Menus Preferences dialog to activate the package.
Another useful package is the Support Folders Tool.

Description

Its various menu items include utilities for: Select the Alpha ↣ Global Setup ↣ Keyboard Shortcuts ↣ Menu Shortcuts command to add/change the keyboard shortcuts associated with any of these menu items. Click here to open the Menu Shortcuts dialog.
Note that all shortcuts will be available in all modes (e.g. for any active window) if this menu is turned on globally.

Submenus help

This section documents the AlphaDev modules corresponding to the different submenus.

Alpha Testing

The AlphaDev ↣ Alpha Testing submenu includes several menu items to help AlphaTcl developers test and implement new changes.

Timing Data

AlphaTcl includes built-in timing capabilities, which are implemented with the [alpha::recordTimingData]. When Alpha is first launched, all of the various AlphaTcl initialization steps are recorded in the database.
When you select Alpha Testing ↣ Display Timing Data the contents of this database are re-formatted and placed in a new "* Timing Data *" window. This information can be used to optimize the initialization sequence.
Note that whenever a file is sourced using [source] (or is auto_loaded), a new timing entry is automatically placed in the database.
Developers can also record other steps that take place in any procedure or source file -- just add a line like 
    alpha::recordTimingData "Starting this procedure..."
somewhere in the body of the procedure or file. This is most useful when timing data is recorded in pairs, so that you can tell when something starts and is later finished.
Select Alpha Testing ↣ Flush Timing Data at any time to clear the database when it contains information that you don't want or need anymore. If you want to clear the data before each test of your Tcl routine, include 
    alphadev::testing::flushTimingData
at the start of the procedure or file. If you want to automatically create the timing data report window when the procedure has finished, include 
    alphadev::testing::displayTimingData
at the end of it. To start a new table in the results window, record a string of "=" as in 
    alphadev::recordTimingData "========"
To include a dividing line within the current table of results, record a string of "-" as in 
    alphadev::recordTimingData "--------"
The Alpha Testing ↣ Time AlphaTcl Proc menu item will open a dialog allowing you to enter the name of a procedure to time, and automatically place the necessary code within the proc's body for you.

Loading Modes and Menus

Using the Alpha Testing ↣ Load All Menus/Modes menu items, you can evaluate the activation scripts for menus/modes. A new window will then be opened listing all of the new global variables that were created by the scripts. The Alpha Testing ↣ Open Document All Modes will go one step further and create a new window for each mode.
The Alpha Testing ↣ List Sourced Files will create a new window listing all of the current files that have been sourced by Alpha and which contain indexed procedures. (See the window's annotation for more information.)

Alpha Sources

The AlphaDev ↣ Alpha Sources submenu provides support for updating the AlphaTcl library inside the application bundle after modifications have been made in the working copy.
All the commands assume that you have already extracted a working copy from Alpha's repository at SourceForge. You must specify the top location of these sources in the Alpha Source Folder preference found in the AlphaDev Menu preferences (Alpha ↣ Preferences ↣ Package Preferences).
You can update your working copy using the Update Alpha Sources menu item found in this submenu. The command Rebuild Alpha's Core compiles the sources using the xcodebuild command line tool: this requires that Xcode be installed on your machine.
The other commands let you synchronize various parts of the library inside the bundle with the modified files in your working copy. The following commands are available:

AlphaDev Web Sites

The AlphaDev ↣ AlphaDev Web Sites submenu provides support for access to various Alpha Web Sites. All sites and their corresponding urls can be edited by the user. By default it includes some specific pages in the Alpha wiki which are listed in the second section of the menu.
The service defined in your viewURL Helpers Preferences determines how the files will be viewed.

What are the default web sites?

There are a number of web resources out there which Alpha developers might find useful. Some are specific to Alpha, others to Tcl, and several pages in the Alpha Wiki provide development guidelines or are ongoing discussions about future efforts.
These are some of the default sites listed:
Alpha Project Page
This site is Alpha's project page at SourceForge.
Alpha SVN Repository
This site contains the collection of all Alpha source files, along with their complete revision history.
Alpha Home Page
This site serves as the home page for Alpha.
Alpha Bugs Tracker
This is the database of all reported bugs associated with Alpha and its supporting editors. See the 'Bug Reports' submenu in the Help menu.
Alpha Mailing Lists
There are two primary public listserv forums devoted to both the use and the development of Alpha and its editors. This web site includes information about signing up for the listservs (daily digests are also available), or for searching the mailing list archives.
The Users forum is for, well, 'users' of Alpha that need help for some specific editing operation or want to provide feedback for future development. In general, the traffic on this list is relatively light.
The Developers forum is more technical, addressing programming issues in both Alpha as well as the core applications. Most developers are also subscribed and monitor the Users list (providing help there when necessary). All bug reports from the Alpha's Bug Tracker are automatically forwarded to the developers list.
Tcl Developer Site
This site is the home page for Tcl. Most of Alpha's functionality lies in its set of AlphaTcl source files, written in Tcl, creating the set of modes, menus, and other features associated with the graphic user interface.
Tcl stands for Tool Command Language, a cross-platform computer language created by John Ousterhout which provides a basic set of commands that can be used by any application. The Alpha text editor relies on Tcl to perform basic tasks of variable creation and manipulation, OS file accessing, and script evaluation. Tcl does not have to be installed on your local drive in order for Alpha to function properly because a Tcl framework is included in the application bundle.

What is the Alpha Wiki?

The Alpha Wiki serves as the discussion forum for the developers and users of Alpha.
Wiki sites are simply a collection of interactive www pages that can be edited by anyone visiting the web site. Each page is retained on some remote web server, and is generally identified as a file number with an 'alias' name which allows them to all be hyperlinked amongst themselves.
These pages (as well as any other urls) can also be viewed in Alpha using the package WWW Menu -- you can set your viewURL Helpers Preferences in order to automatically download and view urls using Alpha. Wiki pages from any site can also be edited and saved to the wiki's remote server using the Alpha package Wiki Menu -- the 'Edit' hyperlink found at the bottom of wiki pages which have been rendered by the WWW Menu will set everything up for you, creating a new window that you can edit and 'Save' to the remote server.
As always, feedback and code contributions are always welcome.

AlphaTcl Internals

The AlphaDev ↣ AlphaTcl Internals submenu provides support for variables and procedures introspection. The following commands are available: These commands let you specify the namespaces or modes you are interested in and display their output in text windows for easy inspection.
The Unlock Bindings command re-enables bindings if they have been accidentally disabled.

Smarter Sources

The AlphaDev ↣ Smarter Sources submenu provides commands to easily manage smarter source files. This feature is described in the Smarter Source Help page which can be accessed using the AlphaDev ↣ Smarter Sources ↣ Smarter Source Help menu item.

Help Files Marking

The AlphaDev ↣ Help Files Marking submenu provides support for colorizing a help file or creating hyperlinks in a document window. More on this subject may be found in the Help Text Marking page.

Contextual menu

An Alpha Dev Utils contextual menu module is also available for Tcl mode, as well as an Alpha Dev Help module.
In addition to the utilities provided by the menu items, it also includes support for Tcl mode, such as:

Known problems

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

License and Disclaimer

Original Author: Vince Darley.
Co-Authors: Craig Barton Upright, Bernard Desgraupes.
Copyright (c) 1997-2019, Vince Darley and Contributors.
Contributors: Craig Barton Upright, Bernard Desgraupes.
All rights reserved.
The Alpha Developer Menu 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 VINCE DARLEY OR THE CONTRIBUTORS 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.