From AlphaWiki

FAQ: Applying AlphaTcl Patches

In Bug# 928 Mr. Noyb reported a problem with AlphaTcl's supersearch package, a discussion ensued as to the proper fix, and after the solution was discovered and added to the CVS.AlphaTclCVS he posed this question:

So, is this a Tcl-edit job that I could do myself? What's the fix?

and he got no response. The answer is a little complicated, at least if you are trying to give a general response about how to implement bug fixes, and it is even rather hard to just give a quick response in this specific case because it depends on what version of AlphaTcl he is using, if the fix assumes changes made in seemingly unrelated files, etc. Not impossible to describe, but a challenge. This wiki page attempts to explain some the nuances, and includes the following sections:

and a section that should be read for all methods,

See also the ModifyingAlphaTclProcedures? wiki page for information about how you can attempt to debug procedures yourself if you have not been given any patch to add to your AlphaTcl library.


Updating to AlphaTcl CVS HEAD sources

AlphaTcl sources are contained in a CVS (Concurrent Versions System) that keeps track of all changes made to the various files that add most of the user-interface and extra functionality found in Alpha. Each version of each file in the CVS.AlphaTclCVS has a set of cvs 'tags' associated with it, and all files contained in your local installation of AlphaTcl should have the same tag. When 'final' public releases of Alpha are created, all of the files have the STABLE tag, and during development phases the latest versions of files (those like supersearch.tcl) that have some fixes applied have the HEAD tag.

It is possible that the fix for this bug, which was applied to the HEAD version of the file supersearch.tcl (see [http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/alphatcl/Tcl/SystemCode/CorePackages/superSearch.tcl]), relies on some other fix applied to another file in AlphaTcl. The best way to ensure that whatever fix was applied to this particular problem works for you is to update your AlphaTcl sources using the application MacCVS Pro that was included with your distribution of Alpha, updating all of your sources to HEAD. This will give you the latest, cutting edge version of AlphaTcl, including any documentation updates. But it will, of course, potentially include new bugs that were inadvertently introduced while fixing something else. You have to decide what level of risk you are willing to take with your text editor, but note that most developers are using HEAD sources, and of course are trying to deal with any bugs contained therein.

See the CVS.AlphaTclCVS page for more information on updating your local AlphaTcl library.


In addition to updating AlphaTcl, you can apply fixes directly to source files, by adding some lines to a prefs.tcl file, or by activating the AlphaTcl Smarter Source feature and putting corrected source files in the appropriate directory. All of these methods have pros and cons -- the more complicated methods have more flexibility, but are more difficult for the 'normal' user to understand and utilize at first glance, supporting the impression that you need to become a Tcl hacker to fix things. In my opinion, updating via the CVS.AlphaTclCVS using an application like MacCVS Pro is the easiest to explain and use, though 'easiest' is most definately a relative term.

Applying changes directly to local files

In some cases, you might be told to change line xxx in file xxxx.tcl to correct the offending code. File xxxx.tcl is contained somewhere in your Alpha:Tcl: hierarchy, if you weren't told its exact location you can either ask for more help or take a look through the file system (or perform an OS file search). Open the file in Alpha, click on the lock or pencil icon in the upper right portion of the window above the vertical scroll bar to ensure that the file is not read-only, find the offending line and add the fix.

Save and close the file, and then restart Alpha. Hopefully the patch you applied will take care of the problem you observed.

The disadvantage to this method is that file xxxx.tcl is now locally modified, and if you later attempt to perform an update via the CVS.AlphaTclCVS the message window will indicate an error with this file, and all sorts of havoc might ensue. In this case, your best option is to delete that file and perform the CVS update again -- the missing file should now be restored with the proper version.

Adding code in a "prefs.tcl" file

Another option is to open/create a prefs.tcl file by using the

Config > Preferences > Edit Prefs File

menu item. Copy the entire definition of the procedure in question, paste it into your prefs.tcl file, and precede this definition with

 
    auto_load  theProcName

as in

 
    auto_load supersearch::generalSearch

    proc supersearch::generalSearch {} {
        global supersearch
        if {$supersearch(b)} {
            supersearch::batchSearch
        } else {
            if {$supersearch(multi)} {
                supersearch::getFiles
                set supersearch(multiindex) -1
                supersearch::findNextOkLocation
                return
            } else {
                if {$supersearch(inselection)} {
                    goto $supersearch(start)
                } else {
                    goto [expr {$supersearch(f) ? [getPos] : [minPos]}]
                }
                supersearch::basicSearch
            }
        }
    }

to ensure that the offending version is loaded first, and then the corrected version will replace it. Your prefs.tcl file is sourced whenever Alpha is first launched, after all of the required init files have been sourced.

If the problematic proc is part of a mode's source files, you should instead create a <mode>Prefs.tcl file, as in TeXPrefs.tcl. Create this by opening a window in the mode you want to change, and then use the

Config > <mode> Mode Prefs > Edit Prefs File

menu item. Unlike the prefs.tcl file, your mode-prefs file is not sourced when Alpha is first started, but only after the mode in question is loaded for the first time.

The only real disadvantage here is that if you subsequently update via the CVS.AlphaTclCVS you probably want to remove that code from your prefs files, which means that you have to remember that you put it there in the first place. Failure to remove it might cause trouble later when additional patches are put in the CVS.AlphaTclCVS.

Using the AlphaTcl "Smarter Source" feature

Using this method, you must

  1. Activate the Smarter Source feature, using the Global Setup > Features dialog.
  2. Define a TclExtensionsFolder preference, using the Config > Preferences > Input-Output Prefs > Files dialog. The default value is your Alpha Prefs folder, but that location might not be so obvious. (See the FAQ.MultipleVersionsOfAlphaOnYourLocalDrive page, which lists the default location.)
  3. Place a copy of the offending file in this directory. Make your changes as necessary. Restart Alpha.

For more information, see the ModifyingWithSmarterSourceFiles? wiki page.

The disadvantage here is the same as the above: if you subsequently update via the CVS.AlphaTclCVS you probably want to remove the entire file from your prefs folder, which means that you have to remember that you put it there in the first place. Failure to remove it might cause trouble later when additional patches are put in the CVS.AlphaTclCVS.


Updating AlphaTcl package indices

For all of the methods described above, if any of the changes occur with an alpha::package call, as in any of

 
    alpha::flag
    alpha::mode
    alpha::menu
    alpha::feature
    alpha::extension

then you must rebuild your AlphaTcl indices by using the

Config > Packages > Rebuild Package Indices

menu item. An example of some code contained in an alpha::package type declaration would be this:

 
    alpha::feature supersearch 1.5.1 global-only {
        alpha::package require AlphaTcl 8.0d1
        set supersearchOn 0
        array set supersearch {
            f 1 i 1 m 0 r 0 p 0 w 1 b 0 multi 0 
            multifsets "" ismultifset 0 inselection 0 pattern "" 
            ignore 0 casereplace 0
        }
        # This setting is persistent - saved in user's prefs
        if {![info exists supersearch(wrap)]} {
            set supersearch(wrap) 1 
        }
        namespace eval supersearch {}
    } {
        set supersearchOn 1
        supersearch::onoff
    } {
        set supersearchOn 0
        supersearch::onoff
    } maintainer {
        {Vince Darley}
    }  help {
        ...
    }

If you are updating via the CVS.AlphaTclCVS, chances are that the next time you restart this will take place automatically, but if not you must perform this task "manually" in order to ensure that the changes you made will be recognized.


cbu 21March05

Category.FAQ

Retrieved from http://alphatcl.sourceforge.net/wiki/pmwiki.php/FAQ/ApplyingAlphaTclPatches
Page last modified on June 04, 2006, at 03:20 PM