;
                                    LSH.COM                                   

             Size (recs) CRC   Version    Author/Latest Issue      Disk
LSH10.3OM      8k (59)   FFE8  1.1        Rob Friefeld 8/91        Z3COM11
LSH10.4OM      9k (68)   9256  1.1        Rob Friefeld 8/91        Z3COM11

  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] [/C]

   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 /C              Run LSH once, without invoking the shell.
     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.1 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             -  Delete Command       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      HOME  Complete Name   
    W  First Screen         ^KI  Insert Q             ESC J  HELP (Run Cmd)   
 Unchange Line:   ^QU
Current line is restarted.  Does not work after line is deleted.

 Undelete:   ^U
Recover the last "delete line", "delete to end of line", or token command
at cursor position.

 Repeat Token:   TAB n
TAB TAB   Put text from cursor to EOL into delete buffer.  Recover it with ^U.
TAB 1..9  Put token #n into delete buffer and also enter it at cursor.

 Queue: 
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.

 Duplicate Line: 
A single key-stroke duplicates the current line.  This command may be
installed to automatically replace the first token (command verb) with GO.

 User Command:   ESC U
Execute a user patch.  You may write a custom routine to toggle the
printer, manipulate the terminal, etc.
 Command Completion 

   Idea taken from PCED:   When completing the first token  on the line,  only
.COM types are matched  (along the path),  and  a  trailing space is appended.
Then you are immediately ready to add command arguments.  For example:

     c<COMMAND COMPLETE>
     cl <AGAIN>
     crunch
then...
     crunch f<COMMAND COMPLETE>
     crunch foo.com<AGAIN>
     crunch foo.z80
     
   Command Complete now recognizes "=" and ","  as  token  separators,  so  it
works on argument lists and for  CP,  REN,  etc.   It also now  handles  lines
starting with ":" or "." to force search of current directory on first token.
:2 :LSH-C
:3
 Configuration - 1/3 

   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.

                                LINE SEQUENCING

   The automatic line  sequencing  command can be  configured to return to the
same line rather than go to the next line.  This cannot be toggled within LSH,
but must be configured with LSHINST.
 Configuration - 2/3 

                                 USER ROUTINE

   A small user's routine can be installed in a 32 byte patch area.   The code
there is run when the User Patch key is pressed.   The patch must end with RET
if LSH is to keep running.  All registers are available for your use.

   Code can be assembled to an object file and overlayed on  LSH  with  BCOMP.
The patch area is surrounded by "USR> ..patch..  <USR" markers.   You can also
enter hex code directly with LSHINST.

   The patch could be used to send a terminal or printer init string.  Another
possibility is a system  specific  patch to  turn  the printer on and off.  It
does not work to use the usual ^P because the editor does not input characters
via BDOS function 2.  (Embedding ^P in a command line does not work either.)
 Configuration - 3/3 

; Sample printer toggle user routine

dospat	  equ  0d628h	 ; Printer toggle location (in my DOS, not yours!)

patch:    ld   a,(dospat)    ; Get state
          cpl                ; Flip it
          ld   (dospat),a    ; Store it
          ld   e,7           ; Beep
          ld   c,2           ; Char out
          jp   5

	if ($-patch) gt 32
*** TOO BIG ***
	endif
          end
:4
 Error Messages  - 1/2 

MEM OVFL:        - There is not enough  TPA to hold the log  file.   Solution:
                   reduce the default READ RECS (LSHINST item 1.1.1).  If your
                   system has a very small TPA, use the Type4 version of LSH.

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

LOG?             - The log file in use can't be found (erased, disk changed).

NAME?            - The log file specification must be UNambiguous.

TCAP?            - The editor couldn't find needed support in your TCAP entry.

R/W ERR:         - On reading, attempt to read past end of file without  find-
                   ing a 1AH text terminator.  On writing, disk full.  A hard-
                   ware error gives this message for either operation.
 Error Messages - 2/2 

[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/6 

   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/6 

   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.  

   d. Fixed Log Version:   
      There is now a separate version of LSH which uses  a  fixed size history
      file.   Its purpose is to speed up operation on floppy  disks,  or  even
      hard disks,  by allowing you to place the history file on the outer disk
      tracks  (i.e. it will be one  of  the  first files on the disk) and know
      that it will STAY there.   The Variable Log  version keeps adding to the
      history indefinitely,  so you will eventually end  up  reading  from the
      inner tracks.
 LSH Notes - 3/6 

      - A new history file,  or an old  one  which is shorter than the nominal
      length, is padded to the full size.   When the history is full, only the
      end of the file is written to disk.   You lose the first  command lines.
      - The file size is installed  with  LSHINST.   The  distributed  version
      reserves 4k, but 2k may be all you need.
      - CAUTION:   If you edit a history file  independently,  the text editor
      will probably truncate it.   However, if LSH runs immediately afterward,
      it will pad the file back out to its  reserved length  when  you execute
      the next command.

   e. Vs 1.1 updates (8/25/91, Rob Friefeld):
      - In previous versions,  the line editor would warm boot on ^C.   Vs 1.1
        warmboots  (in  Line Mode  only)  when  the  "screen down"  command is
        pressed.  That is still ^C for a WordStar-like installation, but could
        be something else after running LSHINST.   You can also get a warmboot
        using ESC C, just as for Screen Mode.   (This change is a  side effect
        of some consolidation of the two editors.)
      - Vs 1.1 does not rely on the integrity of alternate regs across  a call
        to CIN.
 LSH Notes - 4/6 

      - The DUOK flag is checked before displaying prompt.
      - Terminal installation has been removed.   The full screen divider line
        is now drawn with a call to VLIB routine GHBAR,  if available.   (This
        one routine added almost 3 records to LSH.  Worth it?)
      - LSH is coded to run safely as  Type3  or  Type4  under ZCPR3.4.   Those 
        running ZCPR3.3 need to patch the first byte of the  Type 3  version to
        C3h (JP),  rather than C7h (RST 0).   No Type 1 version is distributed.
        I will be happy to assemble one for anyone who needs it.
      - Screen mode now obeys the  CLS  flag  setting  when  a line is executed
        with shell pause.
      - Command  Complete and  Token  Repeat  control  bindings  are no longer
        required to be single keys.  It is OK to use meta-key/key combinations
        now.
      - A half dozen small bugs were fixed.
      - A new ZERRLSH, the error handler which corrects LSH's history file, is
        needed for the  Fixed Log  version.   I also recommend the newer error
        handler for the variable log version.   It signs on as  ZERR+LSH,  Vs.
        1.5d.   The error handler part is the same as ZERR 1.5,  only the +LSH
        part is new.
 LSH Notes - 5/6 

   f. Vs. 1.0r updates:
      -- The state of the recording toggle is now displayed continuously.
      -- Optional terminal-specific  strings  are  now 8-bit data headed  by a 
         character count rather than the previous 7-bit, 0-terminated strings.
      -- In LINE mode,  LSH calls CLREOS to clean up dangling line wraps where
         possible.  ^R will also Retype the line now.
      -- A filename completion command,  similar to the one in EASE,  has been
         implemented.   Complete  is  nominally assigned to  HOME key to avoid
         conflict with documentation of Token Repeat (TAB key).   You can bind
         it to TAB,  as EASE does,  if you want to use it  a lot.   Note that,
         since Complete has  to look  back  to  see  what the previously typed
         command was,  Complete and Token Repeat MUST be assigned to  a single 
         control key, NOT a meta-key/control combination.

   g. Vs. 1.0q updates:
      -- 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.
 LSH Notes - 6/6 

      -- 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
