Boston 2/boston-2.iso/DOS/HILFEN/SYSTEM/STACK/STACK.DOC

Text File | 1993-12-01 | 24KB | 581 lines

     STACK - Command Line Editor/Enhancer, Version 2.4
     =================================================

ACKNOWLEDGEMENTS
----------------

I thought that it was about time I gave credit to some of those
users whose suggestions have improved STACK or helped me isolate
faults.

Barry Foelsch of Raleigh, NC who helped me track down a problem
with mono displays.

All the members of the Canberra C SIG whose many suggestions
resulted in version 2.0

Jeff Bowles of Columbus, Ohio who helped isolate the repeated
command fault in version 2.3 and suggested the F3 option.


AUTHOR'S RAMBLINGS
------------------

Isn't it always the way ?  You just finish setting up a new bit of
software and out comes an upgrade.  However you shouldn't find
updating to version 2.4 a traumatic experience as it is completely
compatible with versions later than 2.0 and all of the new features
are initially disabled.  Unfortunately I wasn't able to keep the
command file to the same size as for 2.0 and it has grown by about 200
bytes.  Still I think the size increase is worth the benefits.  (For
those who are wondering what happened to 2.1 it had a minor bug which
was quickly discovered but not until after I had distributed a few
copies.)

The down side of all this is that STACK is now becoming fairly
complex.  To combat this I have presented the commands available in
two sections and new users may find it simpler just to use the basic
commands initially and only use the more esoteric commands when they
find they need them.

All of the new features have been included in the documentation and
are summarized in the file HISTORY.STK




WHAT IS IT ?
------------

There are a number of programs around that record the last few
commands that were typed in a stack and allow you to recall them
with a few key strokes.  I've always used one and feel a bit lost
on a computer that doesn't have one.  The problem that I have
with such utilities is that the stack quickly gets cluttered up
with a 'rubbish' commands that I don't want to use again and I
loose track of whether the command I want is still in the stack
or has been pushed out.

STACK is my solution to this problem.  In addition to the usual
command line editing features STACK allows you to flip open a
window showing you what commands are in the stack.  You can also
copy these commands to a separate list associated with the
function keys.


FOR USERS OF EARLIER VERSIONS
-----------------------------

Users of version 1.x of STACK will notice a few changes,
hopefully all for the better and none too traumatic.  The main
changes are:

-  the command to modify STACK.COM is now ALT-W

-  the function key list now uses a select bar similar to the
   command stack

-  the command stack is not cleared when STACK is loaded so it is
   possible to save commands in the stack as well as the
   function key list

-  new commands are always added to the bottom of the stack (as
   displayed on the screen) with old commands dropping off the
   top.

-  commands that are already in the command stack or function key
   definitions will not be copied into the command stack.

There are some other minor differences but these can be changed
with the setup utility.


COMPATIBILITY WITH OTHER UTILITIES
----------------------------------

STACK patches some DOS interrupts and can clash with other
resident utilities especially keyboard enhancers such as
SMARTKEY.  If you load it before such utilities there shouldn't
be any problem.

Some users have asked if it is possible to make STACK work within
utilities such as XTREE that "shell" to DOS to let you execute
commands.  The answer is a qualified sometimes.  Many of these
programs don't actually shell to DOS but instead use their own
code to collect a command string from you then get DOS to execute
the command directly.  In these situations STACK doesn't get a
look in and there is usually no way around it however setting the
always enabled flag in STACK may work in some cases.


COPYWRITE, ETC
--------------

STACK (all versions) may not be sold for profit or "bundled" with
other products without my permission.   Other than that there are
no restrictions on who can use STACK or under what conditions.
Go for it.


COMMANDS - GENERAL
------------------

The commands recognized by STACK are presented in two groups, the
common commands, which are essentially those compatible with
earlier versions of stack, and the less common commands.  A
summary of all commands is presented afterwards.

POSITION OF COMMAND LINE.  So that long command lines do not
interfere with the window display STACK will automatically move
the command line to the bottom of the screen if it might get in
the road of an opening window.

TERMINOLOGY.  When a window is opened the highlighted line is
referred to as the current command.  Except where otherwise
indicated all commands affect or action the current command.

Where the command descriptions below refer to a command in the
stack the details are equally applicable to function key
definitions in the function key list, except where noted.


COMMON (OLD) COMMANDS
---------------------

Return/Enter - execute the current command

UP       - select the preceding command and display it at the
(arrow)    DOS prompt.  If a window is open the select bar is
           moved to the previous command.  In 1.x versions of
           STACK the up arrow recalled the command prior to the
           last command rather than the last command.  Some users
           found this useful and you can select between the two
           alternatives using the setup utility.

F3       - using the setup utility F3 can be made to act the same
           the UP key.  If this option is selected then you can
           still invoke the F3 function from the function key
           list using the highlight.  To act as a reminder when
           F3 is switched to act as the UP key the 'F3' label is
           blanked out in the function key window.

DOWN     - select the next command and display it at the
(arrow)    DOS prompt.  If a window is open the select bar is
           moved to the next command.

PGUP     - open a window and display the command stack.

PGDN     - open a window and display the function key definitions
           for the function key list.

HOME     - move the cursor to the left of the current command

END      - move the cursor to the right of the current command

DEL      - delete the character at the cursor

INS      - toggle insert mode.  Insert on is indicated by a block
           shaped cursor.  The default insert state can be set
           using the setup utility.

Backspace -delete the character to the left of the cursor

ESC      - clear the command line and close the window

TAB      - delete the currently highlighted command from the stack

Fn       - copy the command associated with that function key
shift Fn   to the command line and execute it if the definition
           is terminated with a carriage return (see next
           command).  You can also issue the command associated
           with a function key switching to the function key
           window (PGDN) and selecting it with the highlight bar
           and then pressing Return/Enter. The function keys that
           can be programmed in this way are F1 to F10 and shift
           F1 to shift F5.  See the note on F3 above.

Ctrl Fn  - copy the current command to this function key.  Ctrl F1
Alt Fn     to ctrl F10 copy to the corresponding function key,
           alt F1 to alt F5 copy to shift F1 to shift F5
           respectively.  If STACK is currently in insert mode (ie.
           you pressed INS and the block cursor is showing) then NO
           carriage return is added to the end.  This means that you
           can add some more to the end before pressing Return/Enter.
           If insert mode if off then a carriage return is added to
           the end and the command will be executed as soon as you
           press the function key.

Alt w    - modify STACK.COM by writing the current (ie. in memory)
           command stack and function key definitions to
           STACK.COM.  The memory copy of STACK expects STACK.COM
           to be located in the current drive and directory, if
           it isn't you'll get an error message on the command
           line which can be cleared by pressing ESC.  Note that
           the current contents of command stack is also written
           out.

^        - can be used to concatenate several commands on one
           line, eg.   cd \ws^ws^cd \
           (this can be used to replace small batch files).  This
           character can be changed using the setup utility.


LESS COMMON (NEW) COMMANDS
--------------------------

Ctrl LEFT - move left one word in the current command

Ctrl RIGHT - move RIGHT one word in the current command

Ctrl t   - delete from the cursor to the end of the current word
           (taken to be the next non-alphabetic character)

Ctrl END - delete from the cursor to the end of the current
           command

Ctrl HOME - delete from the cursor to the start of the current
           command

Right Shift RETURN - copy the current command line into the
           highlighted position in the current stack (if no
           window is displayed then the command stack is the
           current one). This is mostly useful for modifying your
           function key definitions.  You can select a function
           key using the highlight bar, edit it as the current
           command and then copy it back into the function key
           stack without executing it.

Left Shift RETURN - copies the command line to the command stack
           as if Return/Enter was pressed but the command is not
           executed.  This is different from Right Shift Return
           in that it copies the command to the bottom of the
           command stack where as Shift Return copies the command
           to the CURRENT position in the current stack (the
           command stack OR the function key list).  I often find
           that I have almost completed entering a command only
           to realise that I need to issue another command before
           it.  This command saves me some typing without having
           to fiddle around concatenating the other command to
           the start of the existing one.

Ctrl PGDN - toggle automatic displaying of the function key
            window.  When toggled on the function key window will
            be automatically displayed when DOS is waiting for a
            command.  This, together with the label character
            (see below), forms a basic menu system.  Why a menu
            system ?  Well some of the other people who use my
            computer don't know DOS and don't want to (sometimes
            I don't blame them).  This provides them with a
            simple interface without lumbering me with a big menu
            system.  When automatic function key display is
            toggled on the window will be opened immediately (or
            replace the command stack window).  If automatic
            display is toggled off the window will remain until
            it is closed with ESC or Return but will not
            automatically reappear.  This feature can also be
            permanently turned on using the setup utility.  If
            this all sounds confusing then just try it out.

Ctrl PGUP - toggles automatic displaying of the command stack
            window similar to Ctrl PGDN for function keys.  This
            can also be set to default to on using the setup
            utility.  If both automatic displays are set on using
            the setup program then the command stack window will
            be displayed.

Ctrl w    - writes the current command stack and function key
            definitions (only) to a nominated file.  The file name can
            be set using the set up program or you can use the set up
            program to indicate that the file name will be given on
            the command line.  If the file name is given on the
            command line then typing
                    C:\>\dos\mystack.dat
            at the dos prompt and pressing Ctrl w will create the file
            MYSTACK.DAT in the indicated directory and write the
            stacks to it.  Ctrl w created a small (2.5K) file separate
            from STACK.COM and does not modify STACK.COM as does Alt
            w.

Ctrl r   - reads a file created by Ctrl w into the command stack
           and function key list.  The name of the file is given
           as for Ctrl W and STACK expects to find the file in the
           indicated directory.

Alt a    - toggles always enabled flag.  Normally STACK only
           works at the DOS prompt but when you toggle it to be
           always enabled it will work whenever a program
           requests DOS to input a string.  Surprisingly few
           programs use this function usually just other DOS
           programs such as DEBUG and EDLIN.  You can also set
           this flag permanently using the setup utility.

#        - indicates that all preceding characters were a label.
           They will be displayed but will not be included in the
           command to be executed.  This character can be changed
           using the setup utility.

Search   - if STACKUP is used to set the search character (to either
           the '+' key or the Shift-tab) you can recall a command
           (from the command stack) by typing the first few letters
           and pressing the search key.  The search can be repeated to
           find the next command starting with the same characters,
           ie. you don't have to re-enter the search characters (see
           the example below).  The number of characters used in the
           search can be set using the setup utility.

           Example: if the command stack contained the following
           commands:
                      cd \dos
                      dir /w
                      cd \

           and you entered "cd" then pressed the search key, the
           following would appear at the command line:

                     cd \dos      (1st press)

           pressing the search key again would produce

                     cd \         (2nd press)
                     cd \dos      (3rd press)


COMMAND SUMMARY
---------------

Cursor movement

HOME          - move the cursor to the left of the current command
END           - move the cursor to the right of the current command
Ctrl LEFT     - move left one word in the current command
Ctrl RIGHT    - move RIGHT one word in the current command


Deleting

DEL           - delete the character at the cursor
Backspace     - delete the character to the left of the cursor
Ctrl t        - delete from the cursor to the end of the current word
Ctrl END      - delete from the cursor to the end of the line
Ctrl HOME     - delete from the cursor to the start of the line


Window Control/Command Selection

TAB           - delete the highlighted command from the stack
UP arrow      - select the preceding command
DOWN arrow    - select the next command
PGDN          - open the function key window
PGUP          - open the command stack window
Ctrl PGDN     - toggle automatic display of the function key
                window
Ctrl PGUP     - toggles automatic display of the command stack
                window
ESC           - clear the command line and close the window
search        - finds a command based on first few letters


File Functions

Alt w         - write command and function key stacks to STACK.COM
Ctrl w        - writes the current command and function key
                stacks to the file named on the command line
Ctrl r        - read the command stack and function key list from
                the file named on the command line


Function Keys

Fn/shift Fn   - issue the command associated with that function key
Ctrl/Alt Fn   - copy the current command to the function key


Special Characters

^             - concatenate several commands on one line
#             - indicates that all preceding characters were a label
search        - finds a command based on first few letters

Miscellaneous

Return/Enter        - execute the current command
INS                 - toggle insert mode
Right Shift RETURN  - copy the current command line into the
                      highlighted position in the current stack
Left Shift RETURN   - copies the command line to the command
                      stack (same as Return/Enter but not executed)


STACK SETUP UTILITY - STACKUP
-----------------------------

STACKUP is a basic setup utility for customising your copy of
STACK.  It is simple to use and the notes below are intended to
describe what aspects of STACK it will change rather than how to
use STACKUP.

Command Line
------------
You may specify a full path and file name on the command line to tell
STACKUP which copy of STACK to modify.  If you have renamed the .COM
file then you will have to use STACKUP to modify the filename so that
Alt-w will work correctly, eg

               STACKUP \DOS\UTIL\STK

will cause STACKUP to read/modify a file called STK.COM located in
the directory \DOS\UTIL.

Some users have reported a problem with their screen display when
using STACKUP, usually stray characters on the screen or strange
positioning of input fields.  If this is a problem then you can try
running STACKUP with a "/v" option, ie.

               STACKUP /V

This causes STACKUP to use a different method of screen handling
which should solve the problem.  I would be interested in hearing
from anyone who has the problem especially if /v doesn't fix it.
If you do write to me about this then please indicate what machine
you have, its age, your version of DOS and the version of the BIOS
your machine is using if you know it.

Colours
-------
Allows you to select the colours STACK uses for the window and
highlight bar.

Options
-------
Sets various toggles and parameters:

SUPPRESS FLICKER DETECTION ON CGA DISPLAYS - some early model CGA
displays flicker and display "snow" when a program writes
directly to the screen.  STACK detects CGA displays and tries to
suppress this flicker however this may not be necessary with your
adapter.

WIDTH OF WINDOW - allows you to set the width of the window STACK
will use.  The penalty of a larger window will be that STACK will
occupy more memory when loaded.

TOP ROW FOR WINDOW - sets the top row where the window will be
opened.

LEFT COLUMN FOR WINDOW - sets the left column where window will
be opened.

SORT OPTION - Allows you to adjust the way STACK manipulates commands
in the command stack:
  No Sort - This is the default.  New commands are added at the end of
     the command stack.  When the stack gets full the command at the
     top of the stack is pushed off.
  Move Forward - when a command is executed it is moved forward to the
     end of the command stack.  When the stack gets full the command
     at the top of the stack is pushed off. The effect of this is that
     the most used commands drift towards the end of the command stack
     and the others fall of the top.
  Delete Least Used - commands are not moved around the stack but when
     more room is needed in the command stack rather than delete the
     command on top the oldest, least used command is deleted.
  Both - enables both Move Forward and Delete Least Used.
If you use the Move Forward option then you might find it useful to
have the UP key recall the next to last command rather than the last
command (see below).  Try it and you'll see what I mean.

AUTOMATIC DISPLAY - can be set so that STACK will automatically
open the command stack or function key window when DOS is waiting
for a command.

UPKEY RECALLS PREVIOUS COMMAND - In earlier versions of STACK the
up arrow recalled the command prior to the last command rather
than the last command.  Selecting "N" here will cause STACK @.0
to behave in the same way as earlier versions.

ENABLE REPOSITIONING OF COMMAND LINE - if set to "Y" then STACK will
reposition the command line if will interfere with the window.  If set
to "N" then the length of the command line will be shortened to
prevent it from overwriting the window display.

INSERT MODE DEFAULTS TO ON - if set to "Y" then STACK will start
with insert mode on.

ENABLED OUTSIDE OF COMMAND LINE - normally STACK will only
operate at the DOS prompt.  Allowing STACK to operate outside of
the DOS prompt will allow you to use in in programs such as DEBUG
and EDLIN (Does anyone use them ?).

MINIMUM LENGTH OF COMMAND TO KEEP - as there is not much point in
storing away short commands you can instruct STACK not to keep
commands below a certain length.

F3 ACTS AS UP KEY - switches F3 to act the same as the UP.

CHARACTER TO JOIN COMMANDS - the character you wish to use to
concatenate commands.  This can be any printable ASCII character
(the IBM extended character set is not allowed).

CHARACTER TO INDICATE LABEL - the character you wish to use to
indicate that the preceding characters were a label only and are
not to be executed.  This can be any printable ASCII character
(the IBM extended character set is not allowed).

SEARCH CHARACTER - allows you to enable/disable the search for command
facility and set the trigger key to either Shift-Tab or the '+' key. I
suggest the '+' key as it is a single key stroke and easy to press.

SEARCH LENGTH - sets the number of characters from the command line to
be used when searching the command stack for a match.

PATH/FILENAME FOR COMMAND FILE UPDATES - specifies the path and file
name that STACK will look for when you press ALT-W.

SOURCE OF FILE NAME FOR CONTROL W/R - the file name to be used for
Ctrl-W and Ctrl-R commands can either be set permanently to a name
stored inside of STACK (see previous item) or the file name can be
entered on the command line.  This option tells STACK where to look
for the file name.

PATH/FILENAME FOR CONTROL W/R - (only offered if the source of
the filename for control W/R  is set to table file) specifies the
path and file name that STACK will look for when you press Ctrl-W
or Ctrl-R if you indicate that you won't be using the command
line to specify a file name (see next item).


REGISTRATION, etc
-----------------

STACK is NOT shareware and you are under no obligation to
register as a user.  However the popularity of STACK has left me
with something of a problem as it was becoming expensive to send
people new versions (I had to stop).  So if you would like me to
send you a new version of STACK I would ask that you include
enough funds to cover the cost of a diskette, packaging and
postage.  If you wish you may register as a user of STACK in
which case I will undertake to automatically send you the next
two updates to STACK and advise you of any subsequent updates.
If you wish to register as a user then please send $20 to the
address below giving your name, address and which version of
STACK you are using.  If you just want the latest version then
$10 should cover it.  If you are writing from outside Australia
please add $4 for currency transfer costs.

Once again I would stress that you are not obliged to register as
a user.  Feel free to just drop me a line if you have something
to say about STACK.  If you have a good idea to incorporate or
find a bug to be fixed I'll send you an update anyway.


CONTACTING THE AUTHOR
---------------------

If you discover bugs in STACK or would like to discuss some
aspects of it I can be contacted at home on [phone] or by
writing to PO Box 78, Dickson, Australian Capital Territory, 2602



Shane Bergl
30 Mar 1990