ftp.barnyard.co.uk/2015.02.ftp.barnyard.co.uk.tar/ftp.barnyard.co.uk/cpm/walnut-creek-CDROM/BEEHIVE/ZSUS/Z3HELP-3.LBR/L.LBR/LSH.HZP/LSH.HLP

Text File | 2000-06-30 | 22KB | 425 lines

;

                                    LSH.COM                                   

             Size (recs) CRC   Version    Author/Latest Issue      Disk
LSH10.3OM      6k (48)   B73E  1.0q       Rob Friefeld 10/89       Z3COM5
LSH10.4OM      7k (56)   F08C  1.0q       Rob Friefeld 10/89       Z3COM5


  1- Usage  2- Commands  3- Configuration  4- Error Messages  5- Notes        

   Log SHell is  a screen oriented command line editing shell.   Its interface
may  be toggled between  a normal  blank line  with system prompt  and  a full
screen text editor.  Command lines are saved in an ordinary text file, limited
in size by disk capacity.  On callup, LSH reads the named log into the editor,
and the user  can then  enter new command lines  or move among ones already in
the log.   On  a carriage return, LSH loads the current line into the multiple
command line buffer and returns to ZCPR 3.3.

   LSHINST.COM  installs  the  program  defaults  and  control  key  bindings.
HELPLSH.COM displays a help screen when run from LSH.
:1

  
 Syntax   LSH [logfile]

   Install LSH shell using the log  file specified.   The default type is CMD.
If no DIR is specified,  the file is searched for in the  current DIR, then in
LSH's  DIR.   If the file is  not  found,  and  no  DIR  is named, the file is
created in LSH's DIR.  If no log  file is  specified,  LSH.CMD is the default.
[The default name is LSH's current name.   If you rename the program to X.COM,
the default log file becomes X.CMD.]

   As LSH is distributed,  you can't load a log file with a blank type because
LSH will look for a file with the default type.   If that is a problem, change
the default type to blanks.  Examples:

     LSH                 Start LSH with LSH.CMD.
     LSH WORK            Use WORK.CMD in current DIR if it exists,
                         else use or create it in LSH's DIR.
     LSH FOO:WORK        Use or create WORK.CMD in FOO: directory.
     LSH FOO:MY.LOG      Open specific file type.

:
                      >>> LSH 1.0q CONTROL LIST <<<

  ESC  
LEAD-IN KEY #1         Z  
Last Screen            ^KY  
Clear Q         
    K  
LEAD-IN KEY #2         G  
Delete Char             ^B  
Duplicate Line  
    Q  
LEAD-IN KEY #3       DEL  
Delete Left              O  
Old Line Search 
    P  
LEAD-IN KEY #4         T  
Delete Word Rt       ESC O  
Toggle Direction
   CR  
ENTRY KEY              -  
Delete Word Lt           L  
Recall Next Line
    H  
Backspace              Y  
Delete Line          ESC L  
Auto Line Recall
    S  
Char Left            ^QY  
Delete to EOL        ESC S  
Toggle Save     
    D  
Char Right             -  
Carriage Return      ESC Q  
Quit Shell      
    E  
Line Up                N  
New Line             ESC [  
Toggle Mode     
    X  
Line Down              V  
Insert/Overwrite     ESC C  
Warm Boot       
    F  
Word Right             U  
Undelete             ESC M  
Shell Pause     
    A  
Word Left            ^QU  
Unchange Line        ESC T  
Text Lines/ Time
    J  
Line End/ Start        -  
Control Key            TAB  
Repeat Token #  
  ^QD  
Line End             ^KZ  
Clear to EOF           ^PZ  
Set Place Mark  
  ^QS  
Line Start           ^KB  
Yank Line to Q         ^QZ  
Go To Next Mark 
    R  
Up Screen            ^KK  
Yank & Kill Line       ^KH  
Clear Markers   
    C  
Down Screen          ^KV  
Insert Q & Clear     ESC J  
HELP (Run Cmd)  
    W  
First Screen         ^KI  
Insert Q        
:2
                             
 COMMAND SUMMARY 

   The commands which follow are installed with LSHINST.  Run the installation
program to  see  the  current  control  key set.   (The default  is similar to
WordStar.)  Commands marked with "*" are ignored in  single-line mode.   Those
with "-" are not installed.


 SHIFT KEYS 

All of the   editor  control keys  are  single bytes.  The number of available
functions is expanded by  using  leadin  keys  to  trigger  a search for those
command characters with some of their  high bits set (handled automatically by
the installation program).  Four lead-in keys are available.

Usage is: <lead-in key> <shifted key>.  Example:  ^KQ (or ^K^Q).

Lead-in key #1         (ESC)
Lead-in key #2         (^K)
Lead-in key #3         (^Q)
Lead-in key #4

 EDITING FUNCTIONS - 1/2 

Entry key        CR  Command execution key
Backspace       BSP  Non-destructive
Char left        ^S  Same as backspace
Char right       ^D
Line up          ^E  Go to start of previous line
Line down        ^X  Go to start of next line
Word right       ^F  (Word separator characters may be installed)
Word left        ^A
Line end/ start  ^J  First to line end.  If there, to start
Line start      ^QS
Line end        ^QD
Up screen *      ^R  First to top of screen, then previous screen
Down screen *    ^C  First to bottom of screen, then next screen
First screen     ^W  Top of file
Last  screen     ^Z  End of file.  (Quickest way to append to log)

 EDITING FUNCTIONS - 2/2 

Delete char      ^G  At cursor
Delete left     DEL  Destructive backspace
Delete word rt   ^T
Delete line      ^Y  Deleted line saved to kill buffer
Delete to EOL   ^QY  Saved to kill buffer.  UNKILL recovers.
Carriage rtn      -  Usually preempted by the ENTRY key
New line         ^N  Same as <cr> in INSERT mode
Insert/overwr    ^V  Toggle text insertion mode
Dupicate line    ^B  Duplicate current line
Undelete         ^U  Recover text deleted with DELEOL or DELLINE
Unchange line   ^QU  Restart current line (doesn't work after DELLINE)
Control key      ^P  Trigger for control key insertion
Clear to EOF    ^KZ  Zap everything from cursor to end of file
TAB               -  Insert a tab

 QUEUE FUNCTIONS   (* None are available in single-line mode)

Use the queue to re-organize the history file by  picking up lines one  by one
in the order you want them, then unloading the queue.

Keep and kill   ^KK  Save line, delete it, advance to next
Insert Q        ^KI  Insert queue contents at line
Insert & clr    ^KV  Insert queue, then clear it
Clear Q         ^KY

 SPECIAL FUNCTIONS 

Old line srch    ^O  Look for match to current line up to cursor
Search dir    ESC O  Toggle search direction forward or backward
Line sequence    ^L  Go to line after one last executed
Auto seg      ESC L  Automatic return to next line on reentry
Toggle save   ESC S  Recording on/off
Quit shell    ESC Q  Finished with LSH
Mode        ESC ESC  Full-screen mode / single-line mode
Warm boot     ESC C  Do warm boot if at beginning of line
Pause *      ESC CR  Shell pause for key strike before reentry
Text lines *  ESC T  Set # lines for SCREEN mode
Time display   "     LINE mode, show time in system prompt
Token         TAB #  Replicate, save tokens 1...9
Mark place      ^QZ  Line markers are retained in log file
Go to mark      ^QP  Any number may be set
Clear markers   ^QQ  Deletes all place markers
HELP          ESC J  Run preset command line - HELPLSH.COM

 ENTRY KEY   <CR>

   The entry  key causes  the  current line  to execute  as  a  command.   For
editing purposes, a ^N will substitute for <CR>.   (It inserts  a <CR>  at the
cursor.)  If you want the <CR> available for editing,  you may install another
control character as the entry key.

 SPECIAL FUNCTIONS   <ESC>

        <ESC> Q - QUIT the shell
          "   C - Warm boot  [ ^C not available ]
          "  CR - Execute line with shell PAUSE.
          "   S - Toggle SAVE on/off
          "   T - Set number of TEXT lines. [ 1 .. screen size ]
          "   L - Toggle LINE sequencing
          " ESC - Toggle MODE of operation [full screen or line]
          "   O - Toggle OLD string search direction
          "   J - HELP screen

   Many functions have  no analog in a pure editor.   LSH requires commands to
stop the shell,  initiate  a warm boot,  and pause  before shell execution (to
look at the screen before it is wiped out).   Most of these have been assigned
to the escape key.

 SWITCH MODES   <ESC><ESC>

   LSH operates in two modes.   In LINE mode, LSH shows a system prompt pretty
much as usual.   LSH's presence is  not that obvious until you make use of its
editing features or recall old lines.

   In SCREEN mode,  a  selectable number  of  command lines  appear in  a text
window at the top of the screen.   You have what amounts to  a menu of command
lines to choose from.  Move the cursor to a line, press <CR>, and it executes.
Screen mode is handy for editing, reaaranging, or just viewing the log file.

   [The "modes" are actually separate editors.   In LINE mode,  LSH has no way
of finding out  where it is on the screen.   The only cursor movement commands
possible are backspace and advance by re-printing.   In FULL SCREEN mode,  the
current line appears one up from the bottom of the screen.   If you are at the
end of the file, what has preceded will appear on screen.   Most  of  the full
screen commands are available in line mode -  except queue functions and shell
pause.]

 TEXT LINES   <ESC> T

   The number of text lines displayed may be set on-the-fly.  The installation
program also lets you set the default number.   4-5 lines is usually enough to
show where you are in the log file and  what is coming.   The display  is also
crisper when the  entire screen  doesn't  have  to be rewritten.   The minimum
setting is 1 line; the maximum is CRT lines less three.   For convenience, you
can  request  some large number like 99,  and LSH  will  set the maximum lines
available.

   In LINE mode,  this function  has  no meaning.   LSH uses  the same control
sequence to toggle display of the system time on the prompt line.

 SHELL PAUSE   <ESC><CR>

   In screen mode,  you may want LSH to pause before putting up its display to
give you time  to inspect console  output  from  the last command before it is
overwritten.  You can force a shell pause by executing the line with
<ESC><CR>.

   LSH can also be installed  to pause automatically.   If the text  window is
only  a few  lines in  size,  there is  generally room  below  the display for
console output.   LSH clears the lower part of the screen, leaving the command
lines showing.   When there are many lines  in the text window,  it makes more
sense to  clear the screen on command execution,  let the command run,  pause,
clear the screen  again,  and  redisplay  the command lines.   You can set the
decision point.   The default setting is 10 lines.   If you put it to 0 lines,
LSH will always do  a shell pause.   If you set  it to 99 lines, the automatic
pause function is disabled.

 SAVE   ESC S

   None of the usual ^KX, ^KS, ^KD, ^KL, functions are implemented.  LSH has a
recording toggle instead.  When ON, all changes made are saved to disk.   When
OFF, any changes to the file are temporary and are lost between invocations.

 OLD LINE   ^O

   A 
^O will search for a match to the current line up to the cursor position.
Press 
^O again to continue the search.  To reverse the search direction, press

ESC O.  Default is backward.

    If you are at  the  start  of  a  line,  blank  or not,  you can type some
characters, then search.   If a match is found,  the characters you just typed
are NOT saved.

 LINE SEQUENCE   ^L

   LSH ordinarily comes up  on  a  blank line  at the end  of the log.  Before
running  a command line,  it  stores a pointer to the current line.   When LSH
runs again, it increments that pointer  to the NEXT line.   To go right to it,
press 
^L.  
ESC L toggles  an automatic 
^L on entry to the editor.   The effect
of auto line sequencing is to present the log line by line, "replaying" it.

   Single-line and full-screen modes use independent auto sequence flags.  The
default is auto ON for full-screen, auto OFF for single-line.

   [If the log has been changed with the SAVE state off or with an independent
editor, the pointer may not give you the line you expected.]

 PLACE MARKER   ^QZ, ^QP, ^QQ

   An  unlimited number of line markers  may  be  set.   They  are  maintained
between invocations of LSH.  ^QZ sets a marker to the current line.   ^QP goes
to the next marker, wrapping to  the beginning  of the text.   ^QQ clears them
all.

   [In order to guarantee that the markers stay with the right  line when text
is added or deleted,  it was necessary to set the high bit of the character at
the start  of the line,  rather than using pointers.    That can cause trouble
when a text editor which sets high  bits for its  own purposes is  used on the
history file.  The clear command will reset all high bits in the file.]

 UNDO   ^KU

   While  a line is being edited,  it is held in a line buffer.   UNDO cancels
any changes to the current line by reloading the line buffer from the  body of
the text.  Once you move off the line or delete it,  the line buffer is loaded
back into the text and UNDO has no effect.   A deleted line  can  be recovered
from the kill buffer.  See UNKILL.

 UNKILL   ^U

   A line deletion or delete to end of line  saves the text to  a kill buffer.
The buffer's contents may be entered  at  the cursor  with 
^U.   This function
may immediately  recover from  an accidental deletion,  or can be used to move
deleted text somewhere else.   Note that the  buffer  is entered  on  the line
according to the setting of the insert/overwrite toggle.

 CONTROL CHAR   ^P

   A control character can  be inserted with the ^P trigger.   CAUTION - since
^Z is the end of file marker for text files, you truncate the log by inserting
it.  (Use ECHO ^Z.)   You can insert a tab with ^PI,  but if you are editing a
file with a lot of tabs in it, you'll want to install the TAB key to do tabs.

   The SCREEN mode display expands tabs.   LINE mode shows  them  as character
"I".

 HELP   ESC J

    It is helpful to see  a reminder of LSH's features,  but  I didn't want to
add another 1k or so to the program for  a help  screen.   My solution  was to
write a separate program,  HELPLSH.COM,  which will look for LSH in memory and
display a screen showing the current command key set.  To make it easy to call
it from within LSH, the 
ESC J command was created to run a preset command line
-- HELPLSH.   Be sure  that HELPLSH.COM  is somewhere on  the path so that the
command processor can find it.   When (or if) you  don't want the help screen,
you  can install  some other command line  to  be run  by this function.   One
possibility would be  an ARUNZ alias which could  easily be changed as desired
without reinstalling the command line in LSH.

 MOVING TEXT 

        ^B  - Keep line to queue, advance to next.
        ^KK - Keep and Kill line, advance to next.
        ^KV - Insert queue contents, then clear the queue.
        ^KI - Insert queue at current line.
        ^KY - Clear the queue.

   LSH uses  a queue rather than  block functions.   A queue  picks up command
lines as you mark them,  then deposits them  where you like.  (First in, first
out.)  That is just what we are most likely to do in this application.  If you
have  ever suffered  the tedium  of re-ordering  a list with  the  usual block
functions, you will appreciate an alternate  way to  do it.  (Or, if you don't
appreciate it, the log file is available to your text editor.)

   Note  that ^KK  adds the line  to  the queue  then deletes it,  leaving the
cursor at the start of the next line.   Sitting on  the ^K key sucks lines up.
Do not use ^KB and ^KK as a pair.  [Generally, I have been using several ^KK's
and later a ^KV to unload the queue.]

 TOKEN REPEAT - 1/2   TAB n

   There are two "advanced features"  for  moving  text  which  use  the  kill
buffer.

1) Token repeat saves the  token # (1 - 9) you  have selected into the buffer,
then enters it  at the  cursor.   The idea is  to save typing.   While playing
with this command, you can cancel any mistakes with UNDO.

        Example:  vde myprogam.z80;z80asm 
TAB2;
TAB2

generates the line:

                  vde myprogram.z80;z80asm myprogram;myprogram

Since token repeat uses the kill buffer,  the second 
TAB2 in the example could
just as well have been ^U.

 TOKEN REPEAT - 2/2 


2) 
TAB TAB yanks  the  current  line from  the  cursor position  into the kill
buffer.  It loads the buffer with the  same  text  which delete-to-end-of-line
would delete.   The buffer contents can be entered later with  an UNKILL (^U).
This canb  be  used to store  a string you intend  to  use  several times when
building a series of command lines.
:3

 Configuration 

   Initial states of the toggles, default log file type,  prompt delay, number
of records of the log  to read,  initial text lines,  and entry key can be set
with  LSHINST.COM  or ZCNFG 1.3 (by A. E. Hawley)  and  LSH.CFG.   A  terminal
specific  "clear to end of screen" string  may  also be installed  if desired.
The editor control key bindings can only be installed with LSHINST.
:4

 Error Messages 

"LOG  OVFL"  -  There is not  enough  TPA  to  hold  the log file.   Solution:
                change the default READ RECS to something smaller.  If the TPA
                is  nearly  full  and  you  enter  a lot  of  text,  LSH  will
                eventually stop accepting input.

"STACK FULL" -  The shell stack is either non-existent or full.  In the latter
                case, pop something off the stack, then try again.

"NAME?"      -  The log file specification must be unambiguous.

"TCAP?"      -  The editor  couldn't  find  needed support in your TCAP entry.
                Are you sure it is loaded?

   [One condition that LSH does NOT complain about is a text line that is not
a command line:  comments, titles, etc.  To insure that the command processor
doesn't try to run them, start them with ";" or with NOTE.]
:5

 LSH Notes - 1/4 

   a. System Requirements:

      ZCPR 3.3 with external FCB,  shell stack,  TCAP.  Shell stack entry must
      be at least 32 bytes (standard).   Performance with a hard disk is good,
      with a RAM disk is excellent.

      [ In addition to its own name,  LSH uses the stack entry to keep part of
      the fcb for its log file,  a save  to disk flag,  a command pointer, the
      number of text lines to display,  the insert/overwrite toggle,  a string
      search direction flag,  the current mode (screen oriented or line),  and
      the command execution key.  When another shell is run on top, the entire
      entry must be  pushed down in  the shell stack,  then moved up  when the
      application is popped.  As far as I know,  all programs which use SYSLIB
      will do this.  I have only tested it with ZFILER and EASE. ]

 LSH Notes - 2/4 

   b. Security:  The only  built-in  security  feature is  a check of the DUOK
      flag  for  system  prompts.   Wheel  status  is  not  required.   [Those
      concerned with system security should  configure  the command  processor
      accordingly.]

   c. The editor  is intended to be comfortable to use for those familiar with
      VDE  or WordStar.   There  are  several  minor  differences  in  control
      function  from VDE which will become immediately evident.   Mostly,  the
      variations save  key strokes  and/or code.   The LSH  editor puts cursor
      mobility ahead of text alteration.

 LSH Notes - 3/4 

   d. Vs 1.0n improvements:
      -- tab expansion code eliminated from screen editor
      -- 4 lead-in keys now available
      -- on switching from LINE mode to SCREEN mode,  current line appears one
         up from bottom of screen rather than one down from top
      -- the prompt upper/lower case reflects the current task under BGII
      -- a flag may be set to disable deletion of cr/lf pairs in LINE mode
      -- line markers are now reverse-searched
      -- LSHINST is more menu-oriented; manual install of CLREOS eliminated
      -- HELPLSH now works with BGII running

   e. Vs. 1.0o improvements:
      -- Vs 1.0n lost track of its line pointer when memory size  was altered,
         e.g., due to RSX's coming and going.   Now uses a pointer relative to
         program location.  This affects line/recall sequencing commands.
      -- Fixed bug in line mode editor (mixup of ^QS and ^QD commands)
      -- Added  "delete word left" command  (disabled in  distributed version
         since there are no free single letter command keys)
      -- modified to work with Bridger Mitchell's scheduler AT

 LSH Notes - 4/4 

   f. Vs. 1.0p improvements:
      -- Console I/O via BDOS rather than BIOS
      -- Bug in marker deletion routine fixed
      -- In screen mode, with auto line sequencing ON, cursor now appears near
         bottom of screen to give  emphasis to command lines  already executed
         rather than those coming up.

   g. Vs. 1.0q improvements:
      -- backspace is now destructive (same as delete key)
      -- new time display routines, with installable option  to  show  time in
         standout video mode.  Shortened display format.
      -- Queue commands implemented for LINE mode.
      -- new command:  duplicate line (^B),  which  copies  current  line  for
         modification and re-use.   LSHINST sets flag to allow this command to
         automatically substitute "GO" for the first token on the line.
      -- LINE mode echoes  a CR to show that something has happened  while LSH
         is busy updating the history file.
      -- numerous bug fixes