Recent Changes - Search:



Modifying AlphaTcl procedures

An Alpha user asked on one of the AlphaTclMailingLists:

    > Is it possible to define the default document template for Alpha's
    > TeX mode?  ...  Can I write this into a template somewhere that's
    > called when I create a new TeX document?

Yes, you can redefine nearly every routine found in AlphaTcl. To accomplish this you must do the following:

  1. Find the original procedure (or 'proc') that performs some operation.
  2. Copy this proc into a file that will be sourced by Alpha.
  3. Modify this proc as desired.
  4. Ensure that this proc will be called when Alpha is launched.

Here's how one would go about modifying the TeX new document routine.

(1) Find the original procedure (or 'proc') that performs some operation

The TeX document template creation proc is TeX::newLaTeXDocument, which then calls other procedures as necessary. You'll find this in the file "[$HOME]/Tcl/Modes/latex Mode/latexMacros.tcl". Copy this and other other relevant procedures, and place them in a prefs file.

If you decide that you want to change the behavior of some operation and are having trouble figuring out what procedure to modify, feel free to ask on one the AlphaTclMailingLists.

(2) Copy this proc into a file that will be sourced by Alpha

The two most logical places to place altered code are "prefs.tcl" and "TeXPrefs.tcl". You can open the first by selecting

Config > Preferences > Edit Prefs File

Most users place redefined 'global' procedures in this file. Since the code you want to change is specific to TeX mode, you can open any window in TeX mode and then select the command

Config > TeX Mode Prefs > Edit Prefs File

These files are stored in your Alpha Preferences folder, and will still be in play when you install a new version. See the WhereIsMyAlphaPreferencesFolder wiki page for more information.

An alternative to redefining individual procedures is to turn on the feature named "Smarter Source" and place a copy of the file which defines this procedures(s) in your new "Smarter Source Folder". See the ModifyingWithSmarterSourceFiles wiki page for more information.

(3) Modify this proc as desired

To modify the procedure, it helps to know something about Tcl, as well as some basic of the AlphaTcl library of procedures. Fortunately, most of the code that you see is fairly transparent for minor changes.

One valuable tip is that the menu command Tcl Menu > Evaluate will 'load' the contents of the active window/selection in Alpha's internal Tcl interpreter. This means that you can modify the proc, evaluate it, and test the changes. If you really screw something up and Alpha won't work any more, you can comment out the changes you have made and restart Alpha to get a fresh slate.

Turning on the AlphaDeveloper Menu (via Config > Global Setup > Menus) will provide you with some additional tools and access to various Help files that you might also find useful if you want to know more about how procedures in the AlphaTcl library actually work.

(4) Ensure that this will be called when Alpha is launched

These prefs files are sourced in a specific order. For example, the "prefs.tcl" file is sourced during startup, after all other required code has been loaded. Mode prefs files (such as "TeXPrefs.tcl") are sourced after the mode has been loaded the first time.

For efficiency, however, many procedures are only sourced on an "as-needed" basis. This means that even if you have redefined a proc in a prefs file, the original version might be sourced _after_ startup, or after a mode has been loaded, and your modifications will thus be ignored.

Use the auto_load command to ensure that the original is first sourced. To redefine TeX::newLaTeXDocument, include this in your "TeXPrefs.tcl" file:

    auto_load TeX::newLaTeXDocument

    proc TeX::newLaTeXDocument {} {

If you are modifying a Smarter Source file, this is of course unnecessary.

The user asked a related question:

    > Similar templates appear for other menu items, such as the
    > "eqnarray."  Can I edit the default template for these items as
    > well, and also bypass the box of options that pops up every time
    > this function is called?

Following the steps above, you can redefine any template. In TeX mode, the code is admittedly somewhat convoluted so some templates are easier to modify than others.

Here's the procedure path that leads to the dialog you want to avoid:

    TeX::macroMenuProc "Math Environments" "eqnarray"
    TeX::TeXmathenv "eqnarray"
    prompt::var "$envName:  how many rows?" numberRows 3 ...

I would suggest modifying TeX::TeXmathenv with something like this:

    proc TeX::TeXmathenv {envName} {

        set _t [TeX::indentEnvironment]

        TeX::checkMathMode "$envName" 0

        switch -- $envName {
            "eqnarray" {
                set numberRows 3
            "eqnarray*" {
                set numberRows 3
            default {
                prompt::var "$envName:  how many rows?" numberRows 3 \
                  is::PositiveInteger 1 \
                  "invalid input:  unsigned, positive integer required"

        switch $envName {

Another major clean-up of TeX should be undertaken to make it easier for the user to over-ride the default routines w/o needing to redefine the menu procedures. There have been a lot of ad-hoc methods built in, but we should come up with a consistent design that is easily explained. Some day ...

Note: while it is possible to redefine AlphaTcl procedures, you should first decide if this is worth your time. In the TeX mode new document template example, you might decide that pressing


is sufficient to insert the 12pt option and then begin working with your document. Learning how to modify a procedure is a time commitment, and chances are high that the time you save in the future with will never equal the time you invested in a productivity enhancement project.

If you intend to modify many procedures in this way to change Alpha's behavior, the cost-benefit ratio will be decreased, of course, as you become more proficient in your AlphaTcl development. And if your changes are deemed useful to the wider Alpha community and incorporated into the next release, the $benefits variable can be multiplied by the number of users who take advantage of it.


Page last modified on January 23, 2006, at 11:17 PM
Hosted on Logo