========================================
STLTask Tray-Icon Filter Control Utility
      Supplementary Documentation
            Updated: 9/14/01
========================================

STL Error Decryptor Web Page: www.bdsoft.com/tools/stlfilt.html
(The STLTask revision log is in the file STLTask-log.txt)

Written by: Leor Zolman
            leor@bdsoft.com
            www.bdsoft.com

STLTask...
a) Replaces STLFilt.bat as the toggle-file manager,
b) automates installation/uninstallation of the Proxy CL,
c) allows on-demand error decryption of clipboard contents

Written using wxWindows, a freeware, platform-independent C++ GUI 
library. (get it at www.wxwindows.org).

For instructions on building STLTask.EXE from the source code, see
CUSTOMIZE.txt.


=============
Configuration
=============

There are two ways to configure file/directory names:

1. In the source: Edit the user-configurable area of STLTask.cpp

2. At run time: STLTask.EXE automatically takes configuration info
   from the [common] and [stltask.exe] sections of the Proxy-CL.INI
   file in the system's Windows directory, or from a filename specified 
   as a command-line argument.

    The recognized options are:

            In the [common] section:

    FILTER_SCRIPT               The full pathname of the Perl script (default:
                                STLFilt.pl)

    TOGGLE_FILE_DIR             Directory where the "Toggle control file"
                                resides (default: c:\)

    NATIVE_CL                   The *filename* (no path) of the renamed
                                native CL (default: CL2.EXE)

    PERL_EXE                    Full pathname of Perl interpreter executable



            In the [stltask.exe] section:

    CL_DIR                      MSVC's native bin directory. Default:
                              c:\program files\microsoft visual studio\vc98\bin

    CLIPBOARD_ONLY              "true" to use STLTask *ONLY* for 
                                clipboard filtering (default: false)

    PROXY_CL_UNINSTALLED_FNAME  The *filename* (no path) for the "inactive"
                                Proxy CL (default: CL.STL)

    CHECK_FOR_PREVIOUS_INSTANCE "true" to use a sentinel file (STLTASK.LOK) in
                                the CL_DIR directory to mark an instance of 
                                STLTask as active. This prevents multiple 
                                instances from running at the same time.
                                If the sentinel file is detected upon startup
                                and CHECK_FOR_PREVIOUS_INSTANCE is true, then
                                STLTask will present an "Are you SURE..." 
                                dialog and offer the choice of either 
                                continuing or bailing out.


=========
Operation
=========

[Note: In the following descriptions, I refer to CL2.EXE and
 CL.STL, but those actual names are controlled by the variables
 NATIVE_CL and PROXY_C_UNINSTALLED_FNAME, respectively.]

Startup:

    Before running STLTask, make sure your native (MSVC's) CL.EXE 
    has been renamed to CL2.EXE, and the Proxy CL (named either CL.EXE
    or CL.STL) is in CL_DIR (MSVC's bin directory CL_DIR).
    If compiling from the command line, this directory must be on the
    system PATH (normally initialized by the VCVARS32.BAT batch file.)

    Upon startup, STLTask examines all compiler-related files in CL_DIR
    for consistency (e.g., an unambiguous "installed" or "uninstalled" state),
    as follows:

        1) makes sure the Proxy CL.EXE is present in CL_DIR as
            CL.STL (by copying CL.EXE to CL.STL if it isn't the same
            size as CL2.EXE)

        2) makes sure the native CL.EXE is present in CL_DIR as CL2.EXE

    If there's any ambiguity about the current state of the Proxy's
    installation, it favors the native configuration, i.e., "uninstalled".
    During subsequent operation, it strives to keep the configuration from
    ever becoming broken. Any renaming that STLTask performs is documented 
    at the top of its startup dialog (unless run with the /q option).


General Operation:

    Once STLTask is in the taskbar, right-click to bring up the
    context menu. Double-(left)click to directly bring up the Status
    report.

    When you select "Enable filtering" or "Disable filtering",
    STLTask simply toggles the filter control file name accordingly.

    When you select "Install Proxy CL", STLTask copies CL.STL to CL.EXE.

    When you select "Uninstall Proxy CL", STLTask copies CL2.EXE to CL.EXE.

    Note: Except when in clipboard-only mode, STLTask offers all menu 
    choices at all times, regardless of whether or not the Proxy CL is 
    installed. I could have had it "gray out" the enable/disable filtering 
    options after uninstalling the filter, or gray out one of the enable/
    disable pair after the other was selected; however, if the STLFilt.bat 
    batch file is used to toggle filtering, or you do it manually by renaming 
    files, the state of STLTask would get out of sync. Thus, no state is 
    revealed in the appearance of the menu items. When "show status" is 
    selected, it always looks to the disk to figure out how things are 
    currently configured.


Clipboard Filtering:

    You can use STLTask to apply the Perl filter to message text
    copied into the clipboard from MSVC's output area. Just copy the
    text you want to filter into the clipboard, and choose the new
    "filter Clipboard" command from the STLTask context menu. The text
    in the clipboard will be processed by Perl, and the result of the
    filtering will be displayed in a dialog box.

    This feature is provided so you can leave the proxy CL filter
    uninstalled normally, and filter error messages only upon demand.
    This would be the most useful on slow machines, where the performance
    impact of having the proxy CL always active may be prohibitive.

    Note that clipboard filtering is tuned to process diagnostics
    generated within the Visual Studio IDE only. 


Setup for "Autoload":

    To having STLTask loaded upon system startup, place a shortcut in
    your Startup folder and give it the /q ("quiet") option. It won't put
    up the dialog box you normally have to "OK" out of, nor complain if
    a previous instance sentinel file is detected upon startup.


Important note regarding re-installation of the MSVC package:

    WARNING: If applying a Visual Studio Service Pack, you must "Uninstall"
    the Proxy CL and then ****MANUALLY DELETE CL2.EXE*** from the CL_DIR
    directory before applying the Service Pack. Otherwise, the
    next time STLTask starts up it may copy the old CL2.EXE on top of
    a possibly updated CL.EXE.
