Amiga ISO Collection/AmigaUtilCD2.iso/Workbench/Shell/ZSHELL27.LHA/ZShell27/ZShell.doc

Text File | 1995-08-15 | 124.4 KB | 2,881 lines

ZShell-Documentation 2.7 (15.08.95)
----------------------------------------------------------------------------
                    ________   ___         ___
                   /____   /\ (___' |___| |__ '|    |
                   \___/  / / ,___) |   | |___,|___,|___,
                      /  / /____________    _____   _____
                     /  / / \__________ \  /_____\ /__ _/
                    /  / /__           \ \// /___/_\__ \
                   /  /_____\           \_/  \_________/
                   \________/
       _________________________________________________________
     _|                                                         |_
    | |   ZShell v1.30 is Copyright © 1990,91 by Paul Hayter    | |
    | | Update to v2.7 is Copyright © 1993-95 by Martin Gierich | |
    | |________________________________________________________ | |
    |__\|                                                     |/__|
     \|                                                         |/
             Titlepage created by Timothy D. Cochran (XMR)

If you have used another version of ZShell, please read Changes.

============================================================================
Contents

For those who never read the whole Documentation
Introduction, Features and Concepts

Starting ZShell:
  Starting from CLI/Shell
  Starting from Workbench
  Opening window on own screen
  Starting using console handlers like KingCON
  Starting from Hotkey-/Directory-Utilities
  How to use CON:
  Errormessages during starting
  Several notes

General Usage:
  History and Command Line Editing
  Executing Commands

  Using Numbers
  Wild Cards
  Options
  Redirecting Input/Output

  Anonymous Pipes
  Filename Completion
  Tips and Hints

Internal Commands:
  Builtin Commands for Disk Management
  Builtin Commands for Scripts and Controlling
  Builtin Commands for Advanced Users

Past, Present and Future:
  Changes                               ->Past
  Known Problems                        ->Present
  Possibilities for Future Improvements ->Future

Distribution
Copyright
Disclaimer

Credits
Authors
============================================================================
For those who never read the whole Documentation

Start the file called ZShell from Workbench or CLI (SHELL), or even
better: Put the file ZShell in the C: directory and start the file ZSH.
Now press the HELP key. Among lots of other information you see "TYPE HELP
? ...". Make sure that ZShell.doc is in the current directory or in S:
and try that. You will see how to use the ONLINE HELP. Try to type
"HELP HISTORY" to see how command line editing works. Execute the
example startup file "ZStart" or put it into the S: drawer and
have a look at it.
Please send me your comment; my Internet-Adress is:
[e-mail] (Martin Gierich).

Things somewhere hidden in the documentation:
* To avoid using an internal command or an alias, you can put a point
  before it, eg. ".list libs:".
* To complete a filename, type in a bit then press TAB.
* If you use "config hide *.info", DIR and Filenamecompletion ignore Icons.
* To start buffering output, use "review 20000"; press Shift+TAB to see it.
  With it you can use ">m" to redirect to MORE, a bit like piping to MORE.
* If you have OS3.0+, try "config colour 01111111".
* Aliases work different to them in normal Shell.
* Use "prompt %n.%p>" to get a full path prompt with process number.
* See FLAGS on how to configure some things you need.
  With "flags icon on" you can switch on Iconifying.
* Try "flags debug on" to debug your script-files and your aliases.
* Try to drag Workbench-Icons into the ZShell window
* See Features and Tips and Hints for more.
============================================================================
Introduction

ZShell is a small, fast and powerful Shell.
Have a look at Features to see the advantages.
ZShell is tested with Kickstart 1.3 , 2.04 and 3.0 and should
run also with other Kickstarts. There are no special requirements,
but some things can only be used with Kickstart 2.0 or better.
I tried to made usage similar to AmigaDOS. If you did not
understand something, have a look at your AmigaDOS usermanual.

Used Abbreviations:
OS2.0+ means Kickstart and Workbench versions are 2.0 or better
OS1.3- means Kickstart and Workbench versions are 1.3 or older
FNC means filename completion
============================================================================
Concepts

I have heard that there is a Shell called "zsh" on UNICS-systems. ZShell
has nothing to do with it, because it tries to be AmigaDOS compatible,
not just another UNICS shell clone. The compatibility is, of course, not
100%, if you need that use the original AmigaDOS Shell. So ZShell has some
differences, that give the special feeling of it.

The first main advantage of ZShell is its power/size ratio. In just 32K
there are all often needed commands (like list,copy etc.) and some not
so often needed, which do not increase size much.

The second main advantage is the Filename completion (short: FNC) and the
review buffer. FNC is like those shells on UNICS and can therefore be
controlled fully with the keyboard. No annoying filerequesters pop up,
that make it neccessary to change from keyboard to mouse.
Nevertheless you can use ZShell with (memory hungry and slow) console
handlers like KingCON.

Third, I tried to make using ZShell as easy to use as possible. Not like
UNICS shells which have thousands of options you will never keep in mind.

Fourth thing is script file execution. ZShell itself supports only the
basic stuff to execute scripts, because if you need a more complex
construction you can use ARexx or another programming language.
ZShell was never intended to be a substitute for a programming language !
You can use scripts made for AmigaDOS shell without problems, because
the command EXECUTE uses AmigaDOS to execute it.

See Future for the future concepts.
============================================================================
Features

* Freeware, no payment required.
* Usage is similar (or better) to the standard AmigaDOS shell.
* About 32K small (pure assembler code, source included).
* Supports the standard housekeeping commands which are builtin,
  so no disk access is necessary.
  eg. list, dir, cd, rename, makedir, delete, copy, path, info, type
* A total of 66 builtin commands.
* Starting from Workbench (!) or CLI/Shell. No Installation required.
* Fast Filename completion by simply pressing TAB.
* Anonymous pipes. You can choose between real and pseudo pipes.
* Review buffer to see again what scrolled out of the window.
* Some commands and features for programmers.
* Online Help function and AmigaGuide-Documentation with examples.
* Command line editing better than OS2.0/3.0 Shell.
* Support of OS2.0+ and OS3.0+ specific features
* Wild cards and recursive processing.
* Real RUN and NEWCLI command that reenters ZShell quickly.
* DIR and LIST both sort (by default) and show filesize.
* Inbuild Amigaguide-/Multi-viewer
* Application-Window/-Icon
* Can open window on own screen.
* 100% script compatibility.
* Can create and show Hard- and Softlinks.
* Command and Function key aliasing.
* Can iconify itself.
* Most things are localized if locale.library is available.
* Colorful output (or fast scrolling with OS3.0+, see CONFIG COLOUR)
* Simple MORE type text viewer.
* Makes itself resident for quicker starting and memory saving.
============================================================================

############################################################################

============================================================================
Starting ZShell

There are three ways of starting ZShell:
 1. The easiest way:
    Start the file called "ZShell" from Workbench or CLI/Shell.
 2. Put the file called "ZShell" in the C: directory and
    start the file called "ZSH" from Workbench or CLI/Shell.
 3. A bit complicated and only for starting from Workbench:
    Make a startup script (see below) or an empty file with a PROJECT
    icon. Change the default tool to "ZSH" or "ZShell" (better ZSH,
    but then put ZShell in C: ) with the right path. Doubleclicking on
    this project icon will start ZShell and execute this script.
    You can also shift-doubleclick a startup script with ZSH/ZShell.

The first way is recommended for having a quick glance at ZShell,
but if you use ZShell sometimes, the second way is better, because "ZSH"
is about 800 Bytes long and starts the ZShell-resident if possible.
So loading "ZShell" is only necessary the first time you use ZShell
after booting up. Anyway using "ZSH" is fully optional.
============================================================================
Starting from CLI

If starting from CLI/Shell you can specify the name of a script file
(see EXECUTE) as an argument which will be executed after starting.
Precede the name with "-s". If there is no name given, ZShell will try
to execute S:ZStart . After "-w" you can specify a window-description.
See NEWCLI for more details, it is exactly the same.
eg.     ZSH -sram:hello     {will try to execute ram:hello}
        ZShell              {will try to execute S:ZStart}
        ZSH -sram:hello "-wCON:10/10/90/90/Hi there" {opens this window}

All CLI-Options:
 -Sname (Script): Start script named "name" (default: S:ZStart)
 -Wdesc (Window): Open window with window-description "desc"
 -Ccmd (Command): Start command named "cmd"
 -D     (Detach): Creates its own process (must be last option)
 -N      (Noraw): Switches off the internal command-line-editing
 -Edepth/diplayID/overscan/title (scrEEn): Opens Public Screen, OS2.0+
 -Hfile   (Help): Determine the file (with path) of the online help (default: S:ZShell.doc)
 -r (not Resident): Testing-stuff (must be first option and lowercase)
============================================================================
Starting from Workbench

If starting from Workbench you can specify the window-description
and the startup script (default S:ZStart , see above) with ToolTypes:
eg.     WINDOW=con:20/50/400/100/Moin
        SCRIPT=ram:hello
        WINDOW=             {this would not open a window}
Make sure that WINDOW and SCRIPT are in capital letters.
(You can edit the ToolTypes by selecting an icon and then choosing
"Information" from the Workbench-Menu.)

All ToolTypes:
 SCRIPT=name : Start script named "name" (default S:ZStart)
 WINDOW=desc : Open window with window-description "desc"
 COMMAND=cmd : Start command named "cmd"
 NORAW=      : Switches off the internal command-line-editing
 ICONNAME=name : Specify name of the icon for iconifying (OS2.0+)
 XPOS=number : Give the position of the icon (OS2.0+)
 YPOS=number : Give the position of the icon (OS2.0+)
 ICONIFY=    : Start in iconifyed mode (OS2.0+)
 SCREEN=depth/displayID/overscan/title : Opens a Public Screen (OS2.0+)
 HELPMAN=file: Determine the file (with path) of the online help (default: S:ZShell.doc)

These two are handled by Workbench 2.0+:
 DONOTWAIT   : Use this if you put ZShell in the WBStartup-drawer
               (preferably together with the ICONIFY ToolType)
 TOOLPRI=pri : Sets the priority of the process
============================================================================
Opening window on own screen

OS2.0+
You can open a Public Screen using the CLI-Option "-e" or the
Tooltype "SCREEN". Optionally you can pass some arguments:
depth: (default 2) Number of Bitplanes being used
displayID: (default $8000) DisplayID looked up in sys:WBStartup/Mode_Names
overscan: (default 1) Overscan type. 1=text, 2=standard, 3=maximum
title: (default ZShell) Case sensitive name of Public Screen

To get your window open there, you have to add ".../SCREEN ZShell" to your
window-description.

Examples for CLI-Start:
ZShell "-wCON:////Shell/CLOSE/SCREEN ZShell" -e
ZShell "-wCON:1/10/640/390/Shell/CLOSE/SCREEN ZShell" -e1/$8004
ZShell "-wCON:////Shell/CLOSE/SCREEN Super" -e3/$8000/2/Super

Example for Workbench-Start:
SCREEN=3/$8000/1/ZShell-Screen
WINDOW=CON:1/10/640/190/CLOSE/SCREEN ZShell-Screen
============================================================================
Starting from Hotkey-Utilities or Directory-Utilities

In most cases you have to use a template like starting from CLI
when configuring the utility.

If the utility does not open a window, you have to use the "-w" option.
If the utility seems to hang up after starting ZShell, try the "-d" option.
With "-d" you do not need a "-w" option.
Example:  zshell -wCON:1/10/640/100/ZShell -d

Some special programs:
YAK: Use "zshell -d" as argument of a hotkey-definition.
MachV: EXECMD"zshell -d"
MTool: Define a program with "zshell" as program and "-d" as parameters.
============================================================================
Starting ZShell using KingCON

KingCON is a Console-Handler with some GUI-Features.
If you do not use KingCON, you can skip this chapter.

Starting from CLI/Shell:
  Use the option -n, and you can optionally use option -w.
  Examples:  ZShell -n
             ZShell -wKCON: -n

Starting from Workbench:
  Use the ToolTypes NORAW and WINDOW=KCON:

The CLI-Option "-n" and the ToolType "NORAW" switch off the internal
command-line-editor, so you could make use of the command-line-
editing facilities of KingCON.
============================================================================
How to use CON:

CON: stands for Console-Handler. This is a program which handles
keypresses and textual outputs on its window similar to a file.

You have to pass several things when opening a CON: window:
CON:leftpos/upperpos/width/height/title
leftpos,upperpos are the position of the left top edge in pixels.
  Both need to be 1 or more.
width,height are the window's dimensions in pixels.
title is a string

With OS2.0+ you can pass some more things and you can drop some things.
So "CON:" alone is valid and opens with the default settings.
To get a close gadget you have to append "/CLOSE", eg.
    CON:1/1/600/100/Great/CLOSE
"/SCREEN screenname" opens on a public screen
"/WAIT" stays till you click the close gadget or press CTRL-\
"/ALT" gives an alternative size with the zoom gadget
... there are some more but I do not know much of them
============================================================================
Errors during starting

If there is an error during starting, a recoverable alert will appear
and show a number. Here is a list what these numbers mean:

Workbench-Start:
1: No memory for CLI-Structure
2: CLI-Table 20 limit
3: No current directory
4: No icon.library
5: No icon
OpenWindow:
10: Already opened
11: Cannot open output
12: Not interactive
13: Cannot open input
Newcli:
15: Cannot copy CurrentDir
16: Cannot set up pipe process
Input:
20: Input failed
21: Unexpected window closure (harmless)
22: Forbid or Disable state (bug in external command)
============================================================================
Several notes

* You can start ZShell from within the Startup-Sequence. After ending
  ZShell the Startup-Sequence will continue. If you use "ZShell -d" in
  the Startup-Sequence, it will continue and a ZShell will pop up.
* If you would like a scrollbar, try CB (ConBuffer) from
  Aminet/util/shell/conbuffer11.lha . A bit old, but it works.
* You can rename "ZSH" as what you like, but do not rename "ZShell"
* If you start ZShell from the Workbench-Menu "Execute Command",
  you can close the window after ending ZShell with CTRL-\  or
  doubleclick the close-gadget.
* ZShell and ZSH are PURE (see RESIDENT,PROTECT).
============================================================================

############################################################################

============================================================================
History and Command Line Editing

ZShell has a 1024 byte circular history buffer. It works similar
to most other shells, the NEWCON: handler in Workbench V1.3 and
the standard console handler in OS2.0+.

You can change the edit keys with CONFIG CTRLKEYS.
These are the default keys:

  UP ARROW        - go back one line in the history buffer
  DOWN ARROW      - go forward one line in the history buffer
  SHIFT UP ARROW  - go to the 1st line in the history buffer if nothing
                    was typed. Otherwise the string left of the cursor
                    will be searched in history buffer (like in OS2.0+)
  SHIFT DOWN ARROW- go to the last line in the history buffer, which
                    holds the last modified line

  LEFT ARROW      - move cursor left
  RIGHT ARROW     - move cursor right
  SHIFT LEFT ARROW- move cursor to left end
  SHIFT RIGHT ARROW move cursor to right end
  CTRL R          - move cursor to start of previous word
  CTRL T          - move cursor to start of next word

  CTRL S          - delete to start of line
  CTRL E          - delete to end of line
  CTRL W          - delete one word right of cursor
  CTRL Q          - delete one word left of cursor
  CTRL X          - delete whole line

  TAB             - see FILENAME COMPLETION (that is great !)
  SHIFT TAB       - read review-buffer with MORE
  CTRL V          - read history-buffer with MORE
  CTRL F          - pop up a filerequester (needs asl.library)
  CTRL L          - clear the ZShell window
  CTRL P          - clear the Filename completion buffer. This is useful
                    with CrossDOS, because it does not notice changes.

  RETURN          - put commandline in history-buffer and execute it
  SHIFT RETURN    - put commandline in history-buffer without executing
  ESC (Escape)    - quit ZShell like ENDCLI (I like this very much !)

Words are delimited by space, point, slash and colon ( ./:).
Again, command line editing is similar to most shells. Backspace,
delete and return do what they are supposed to do.

If you have defined (using ALIAS) some Function keys,
you can use them, too.

OS2.0+:
You can drop Workbench-Icons into the ZShell's window. Then the name of
the icon will be inserted into the commandline.
When in iconifyed mode, you can drop an icon on that
Application-Icon with the same effect.
============================================================================
Executing Commands

Most commands can be aborted by depressing Control-C.
Nearly everything is case independent.
To use a disk command simply type its name after the prompt, the
same way as you would do in other shells. The first part of the input
up to the first space is interpreted as commandname. It is searched
for (in this order) :
 1. in the alias list
 2. in the internal (builtin) command list (see COMMAND OVERVIEW)
 3. in the resident command list
 4. in the current directory (see CD)
 5. in the command search path
and, if it is found, it is executed. The part after the first space
is taken as arguments, also called parameters. The arguments are
separated by spaces. ZShell will allow up to 25 arguments.

If the commandname was found on disk, it will be analyzed:
 1. If the commandname is a directory, the current directory will be
    changed (see CD) to it.
 2. If the script flag is set, it will be executed eighter
    as ZShell script or as ARexx script.
 3. If the execute flag is set (and it is set in most cases), it will be
    tried to treat it as normal executable command.
 4. If the command is not executable, it will be shown using
    amigaguide.library (This is an easy way to view Guides).

eg.     addbuffers df0: 15
"addbuffers" is the command, that will be found as a internal command.
"df0:" is the first argument. "15" is the second argument. The third
argument does not exist.

You can avoid using an alias or an internal (builtin) command or
changing the current directory by typing a point before the
commandname (this is called "force disk").

To abbreviate internal or resident commands put a point behind it.
If you use just a point, the current directory will be set to the
last current directory ("dir back").
To get to the parent directory, you have to use a slash ( / ).

eg.     .addbuffers df0: 20
{This uses the disk command or if available the resident addbuffers}
        ad. df0: 20   {uses the internal addbuffers command}
        .add. df0: 20 {if available this uses the resident addbuffers}
        .             {go back to old current dir}

BEWARE of other matching commands! The first matching will be taken!
"as." can mean ASK or ASSIGN, but ASK will be taken !
There is no abbreviation for disk commands, use Filename  Completion
( TAB-Key ) instead.

A textual error message will be displayed if an AmigaDOS error occurs.
============================================================================
amigaguide.library

For those who do not know:
 amigaguide.library is Commodore's great hypertext system that can
 easily be used to view documentations or to implement online-help into
 own applications.
 It needs Kickstart 1.3 or better.
 You can get it from Fish Disk 920 or from Aminet as text/hyper/aguide34.lha

amigaguide.library V34+ can show AmigaGuide documents and ASCII documents.
V39+ that comes with OS3.0+, can show all kinds of files that are supported
by your datatypes including AmigaGuide and ASCII texts.
So, with OS3.0+, you can enter the name of a picture in ZShell just like
a command to view it.
============================================================================
Using Numbers

Various internal commands need numbers as arguments. Usually you simply
give a decimal number, but you also can use these prefixes:

  + Positive number
  - Negative number
  % Binary number
  $ Hexadecimal number
  & Hexadecimal APTR converted to BPTR
  ! Hexadecimal BPTR converted to APTR
  ^ Filename containing number

See EVAL for more.
============================================================================
Wild Cards

ZShell supports wild card file descriptions on some commands
(DIR,LIST,DELETE,COPY,CONFIG,JOIN,MOVE,PROTECT)

OS2.0+ note: The default is to use AmigaDOS wildcard patternmatching.
  It is localized and has not the limitations of the internal matcher.
  But you have to be careful when looking at the examples in this
  documentation, because they are made for the internal matcher.
  (You can even use * instead of #? with the AmigaDOS matcher, because the
  wildstar flag is set by ZShell in the system for all programs. Please
  tell me if this makes problems.)
  To switch back to the internal matcher use: FLAGS WILD OFF

  AmigaDOS patternmatcher:

    ?       Matches a single character.
    #       Matches the following expression 0 or more times.
    (ab|cd) Matches any one of the items seperated by '|'.
    ~       Negates the following expression.  It matches all strings
            that do not match the expression (aka ~(foo) matches all
            strings that are not exactly "foo").
    [abc]   Character class: matches any of the characters in the class.
    [~bc]   Character class: matches any of the characters not in the
            class.
    a-z     Character range (only within character classes).
    %       Matches 0 characters always (useful in "(foo|bar|%)").
    *       Synonym for "#?", not available by default in OS2.0,
            but is switched on by ZShell.

    "Expression" in the above table means either a single character
    (ex: "#?"), or an alternation (ex: "#(ab|cd|ef)"), or a character
    class (ex: "#[a-zA-Z]").


The following refers to the internal patternmatcher:

Wild cards are like those supported on MessyDOS or UNICS systems, and not
the same as the ones on AmigaDOS. So use * instead of #? .
NOTE: You can only effectively put one * character in a wild card.

Character       Meaning
  *         Match zero or more characters.
  ?         Match one character.
  ~         Negates the following wildcard.
 [  ]       Specifies a class of characters to match.
            (One of the characters in the brackets must match)
  |         Separate multiple filenames (can be wildcards)
            (One of the file descriptions separated by | must match)

To get that just try the examples following and try it out with DIR.
eg.    list *.info      {lists all files ending in .info}
       dir z*.s         {lists all files starting z, ending in .s}
       delete df0:*.info   {deletes all .info files from df0:}
       copy *.s ram:    {copies all .s files to ram:}
       copy 1? df0:     {copies all two char files beginning with 1}
       dir ~*.s         {lists all files NOT ending in .s}
       list ~*.info     {lists all files except for .info files}
       dir *.[co]       {lists files ending in .c or .o}
       list [abcd]*     {lists files beginning with a,b,c or d}
       list c:mount|version {lists the files Mount and Version}
        {OS2.0+ this would be: list c:(mount|version)  }
       list ram:env/a*|*b   {lists all files starting with a or
                             ending with b from RAM:env (environment)}
       copy ~*.info|*.bak   {copies all files NOT ending in .info
                             and NOT ending in .bak}
============================================================================
Options

As nearly everything, options are also case independent.
The internal commands support only four options, because this is
easier to remember. These options start with a dash (-) followed by
one character.

  1. -C (means Clear) , used by AVAIL,ENDCLI,LOCATE,PATH,RESIDENT
  2. -R (means Recursive) , used by COPY,DELETE,DIR,LIST,JOIN,
              MOVE,PROTECT
  3. -Q (means Quick) , used by DIR,JOIN,LIST,DELETE
  4. -S (means Sort)  , used by COPY,MOVE,PROTECT

Instead of -R you could also use ALL , if FLAGS ALL ON is set.

For some special cases there are longer options used: "delete bla force"
FORCE is here an option. You can abbreviate this by a point
(see CONFIG DOT), so "delete bla f." is the same.

To avoid a filename, that is equal to an option, to be treated as an
option you have to surround it with quotes:
      copy "-r" ram:     {to copy the file -r to ram:}
      delete "force"     {to delete the file named force}
============================================================================
Redirecting Input/Output

The standard redirection operators are supported for all internal
commands, as well as disk based and resident programs. (Redirection only
affects those programs which use the dos.library's Input() and Output()
functions.)

    >filename   redirect std output
    <filename   redirect std input
    >>filename  append redirect output (tacks output onto the end of file)
    <>filename  redirect input and output
    >M          view output with MORE after the command has ended,
                you need a review-buffer for that which is big enough,
                otherwise some of the output will be swallowed.
    <W >W <>W   opens a window and inputs/outputs there.
    <* >* <>*   redirection to current window (rarely used)

    If you do not give a filename, input/output will be redirected to NIL:

Redirection can be placed before, between and after arguments and has
the same effect for all three cases.
Note that pipes are some kind of redirection.

eg.    dir >ram:directory df0:c
       type zshell.doc <raw:0/0/100/100/input >raw:0/0/640/100/output
       sortfile things >>df0:things.log
       list >m df0:             {view output with more}
       copy > df0: ram:         {redirects to NIL: , no output !}
       type S:Startup-sequence >W    {outputs on own window}
============================================================================
Anonymous Pipes

ZShell supports anonymous pipes with background tasks like those in UNICS
and with temporary files like those in Amiga-csh.

General things about pipes   What are pipes ?
Real pipes                   The real thing.
Pseudo pipes                 Are better in some cases.
Filters                      Something to use pipes with.
Notes                        What else is interesting.
============================================================================
General things about Pipes

Have you ever tried to view the output of a command with an external
text viewer ? Then you probably have tried something like:

    List >T:listing -r dh0: ; MuchMore T:listing ; delete T:listing

(You do not need spaces before and after semicolons)
Using anonymous pipes you simply have to type:

    List -r dh0: | MuchMore

The "|" character is the pipe symbol. This is why they are called
ANONYMOUS pipes: You do not have to specify a filename.
You can leave out the space after "|", but you need to keep the one
before the pipe symbol.
In the above example MuchMore stands RIGHT to the pipe symbol. This means
that it gets its input from the output of the command LEFT to the pipe
symbol. You can simulate this by "MuchMore <T:listing" instead of
"MuchMore T:listing".
Not every command supports reading its input from an input redirection,
so not every command can stand RIGHT to | . All commands can be placed
LEFT to | , but with those having no output it does not make sense.

You can use multiple | in one line like:

    List -r dh0: |UUencode |MuchMore

The List command will pass its output to UUencode, this will modify the
data and outputs it to MuchMore which will display the modified output
of the List command.
Commands, like UUencode, which read data from input, modify it and
output the modified data are called filters. They are usually used
RIGHT to or BETWEEN pipe symbols.
Using pipes and filters it is easy to process streams of data like:

    filter1 <infile | filter2 | filter3 | filter4 >outfile

You cannot put multiple commands between pipe symbols, like
    List |UUencode;MuchMore |MuchMore
This will be interpreted as "List |UUencode" and "MuchMore |MuchMore".
============================================================================
Real Pipes

Real pipes are switched on by default. You can switch them on by using
FLAGS PIPE ON.

All commands right to pipe symbols are launched as background tasks.
This allows asynchronous data processing.
Real pipes need the PIPE: device to be mounted:
  Make sure you have pipe-handler (OS1.3) or queue-handler (OS2.0+) in L:,
  check DEVS:Mountlist or DEVS:DOSdrivers (OS2.1+) for an entry called
  PIPE: then type "mount pipe:".

If you type in:

    List | MuchMore

in the current shell the command "List >PIPE:ZShellXX" will be started
(XX is a unique number) and a background shell will be launched similar
to the newcli command, which will execute the command
"MuchMore <PIPE:ZShellXX" (XX is the same number as above).

As long as the List command is executed, both shells will be in system
and you can check this out using "show t" from a third shell.
Output of the List command appears directly on the MuchMore screen, you
do not have to wait till the List command finishes.

After the List command has been finished, it waits for the launched shell
to end, just to not confuse you with a prompt. If you do not want to wait,
you can press CTRL-E and you can go on using the first shell. Nevertheless
you cannot start a new pipe until the old one ends.

A drawback however is, that not all commands are able to handle input
out of the PIPE: device, in fact NONE of the internal commands can.
This means that internal commands could not be on the right side of a
pipe symbol if real pipes are used.
You can use MuchMore (by Fridtjof Siebert & Christian Stiens), More
from the Workbench Disk (make sure it is in your path, then use ".more"
to access it) and some other text readers and most filters.
============================================================================
Pseudo Pipes

To distinguish this from real pipes, I call them pseudo pipes.
You can switch them on by using FLAGS PIPE OFF.

Pseudo pipes use temporary files in T:, so they need T: that is usually
assigned in the Startup-Sequence to a directory in Ram Disk.

The commandline

     List | More

(List and More are internal commands) can be simulated with

     List >T:ZShellXXXX ; More <T:ZShellXXXX ; Delete T:ZShellXXXX

(XXXX is a unique number, being the same here). Note that the temporary
file has to be deleted after use. In fact ZShell does not convert the
commandline, because this would cause trouble in case of failure.
First the List command will be started and its output is written to
the file in T:, what means that this needs memory. After the List command
has been finished, More will be started. This is synchronous processing,
you have to wait for the first command to complete. The file in T: cannot
be deleted before the More command ends, so data stays in memory twice.

Internal commands that can be right to the pipe symbol:
MORE              EXECUTE ZSHELL
TYPE              HTYPE
STRINGS           SEARCH

Additional the same commands that can be used right to real pipes can
also be used right to pseudo pipes.

Comparing pseudo pipes to real pipes:
+ Internal commands can be right to the pipe symbol
+ Easier to understand (and, for me, to implement :-)
- Synchronous, so you have to wait
- Needs much memory when handling large quantities of data
  (a background shell needs only about 10KBytes)

Examples:
   dir |more          {view output with MORE}
   info |search dh    {shows the lines for DH0:, DH1: etc.}
   resident |search -3 |more   {shows all internal residents using MORE}
   list df0: |htype   {maybe this looks more interesting}
============================================================================
Filters

These filters are internal commands and can therefore only be used with
pseudo pipes: STRINGS, SEARCH, HTYPE, TYPE
(TYPE is a no effect filter, because data will not be changed.)

A fine collection of filters that support even real pipes is available
on Aminet in util/cli/0filters.lha (by Bernd "0" Noll).
============================================================================
Notes about pipes

* You can use aliases together with pipes; with these:
    alias mm MuchMore
    alias mdir %1 dir $1 \|MuchMore
  (using pseudo pipes you can use More instead of MuchMore) you can use:
    list |mm
    mdir df0:
* To see things happening, try out FLAGS DEBUG ON
* To see all tasks in system, type SHOW T
* To see even more things, you can use SnoopDOS (by Eddy Carroll)
============================================================================
Filename Completion

Filename completion (=FNC) makes typing long filenames and directorynames
easier. It does not matter if you want to type it as command or as
argument. Just type some beginning characters of the desired name
(it also works if you press TAB without typing anything before)
and then press TAB . If there is more than one possibility that
match, it will only be completed as far as all possibilities match
and there are two ways to go further:

1. Type in the next character(s) then again press TAB .
2. Press TAB again: The first match will show up. Press TAB again and
   and again to walk through all matches (I call it cycling).
   To enter a directory shown (indicated by the trailing slash) press
   cursor-right. After you type any other key than TAB, it gets out of
   this cycling mode (cursor-right is the only key that will be ignored).
   To get back the commandline before cycling you can press
   shift-cursor-down.

If a filename was fully matched, a space after it will be inserted. If
a directoryname was fully matched, a slash (/) will be inserted after.
If no partial match is found, the screen blinks (display beep).

To find out the advantage of FNC it is best to play around with it.
It is really a very convenient and powerful thing !

Maybe you do not want *.info files to be completed. This will avoid
some trouble. Use "config hide *.info" for that or see CONFIG HIDE.

If you do not want to see all files that match, you can use
FLAGS MATCH OFF.

The directory last used by FNC is remembered, so it can used comfortably
on slow floppy disks, too. See CONFIG FNCSIZE for more.

For example a directory contains:
  MegaEditExample
  MegaEditExample.info
  MegaViewer
  MoreMegaFiles               {directory}

If you want to change the current directory to MoreMegaFiles you type:
    mo
then press the TAB key. You will see the full name with a slash at the
end. Just press RETURN and you changed it.
To delete MegaViewer you type:
    delete me
and press TAB . You will see "Mega". Now type the V key and
press TAB again. You see "delete MegaViewer ". Press RETURN and
it will be gone.
You want to start MegaEditExample. Type:
    me
and press TAB. Then type E and press TAB. There is no space after the
name. This is because MegaEditExample.info also matches.
Start it by pressing RETURN.
============================================================================
Tips and Hints

* Use MORE instead of TYPE.

* Useful aliases:
        alias arexx %1 %2 putmsg $1 0 0 0 0 0 "$2"
  So 'arexx showdvi "tofront"' is the same as the example in PUTMSG.
  If you want some shortcuts like MessyDOS:
        alias md makedir
        alias ren rename
        alias del delete
        alias dc diskchange
  These are only needed for OS1.3-:
        alias setenv %1 %2 echo >ENV:$1 $2
        alias getenv %1 type ENV:$1
        alias unsetenv %1 delete ENV:$1

* From Workbench assigns are most likely done by clicking an icon:
  For example if you have the assigns below in the script
        failat 10
        assign TEX: dh0:text/pastex
        assign MF: dh0:text/pastex/metafont
        putmsg
  you need to get a PROJECT ICON for that. Now define the default
  tool as ZSH (or ZShell) and a tooltype containing
        WINDOW=
  (case sensitive). That's all. Failat 10 breaks the script if
  an error occurs. Putmsg flashes the screen to indicate that
  everything was successful. No window will be opened.

* CTRL-R and CTRL-T are for moving the cursor one word backwards/forward.
  Probably you would rather like to use Alt-Cursor-Left and
  Alt-Cursor-Right instead. This is not possible to do in ZShell, but
  you can modify your Keymap according to it, because usually Alt-Cursor
  is unused. Get yourself a keymap editor and set it to CTRL-R and to
  CTRL-T (same as hexadecimal 12 and 14).

* A script counting down from 10 to 0 (a bit complicated and slow) :
    failat 11 ; setenv helpenv 11
    lab backtohere
    copy > ENV:helpenv ENV:counter
    eval >ENV:helpenv ^ENV:counter 1 -
    echo "Current number: " ; eval ^ENV:helpenv
    if not error
       skip backtohere
    endif
============================================================================

############################################################################

============================================================================

############################################################################

============================================================================
Builtin Commands for Disk Management

Following there are descriptions of the standard DOS commands which are
builtin in ZShell (and therefore need not be loaded from disk).
Square brackets [] mean that the argument enclosed in is optional.
A vertical bar | separates multiple possibilities, choose only one.

AddBuffers drive [number_of_buffers]
Assign [logical name:] [directory] [ADD|DEFER|PATH|REMOVE]
Cd [destination]
Copy [-R] [-S] source1 [source2] ... [destination]
Delete [-R] [-Q] source1 [source2] [source3] ... [FORCE]
Delete Device devicename [name [filesystem]]
Dir [-R] [-Q] [source1] [source2] ...
FileNote file|directory comment
HType source [offset]
Info
Join [-R] [-S] source1 [source2] ... destination
List [-R] [-Q] [source1] [source2] ...
Lock device ON|OFF
MakeDir directory1 [directory2] ...
MakeIcon filename [icontype]
MakeLink linkname filename [SOFT]
More source [line_count]
Move [-R] [-S] source1 [source2] ... [destination]
Protect [-R] [-S] [file/dir1] [file/dir2] ... [+|-|=|h|s|p|a|r|w|e|d]
Relabel drive newname
Rename source destination
Resident [command1] [command2] ...
Search file search_string
SetDate file|directory [date/time]
Split [-Q] source dest length [offset]
Type source
============================================================================
ADDBUFFERS drive number_of_buffers

* ADDBUFFERS increases disk access speed on the specified drive by
  adding a number of sector cache buffers. Each additional buffer
  reduces memory by about 560 bytes. Generally, 25-30 buffers per
  floppy drive is optimal.

eg.     addbuffers df0: 25
        addbuffers df1: 30
============================================================================
ASSIGN [logical name:] [directory] [ADD|REMOVE|DEFER|PATH]

* ASSIGN will assign a logical device name to a disk directory.

eg.     assign z: df1:zshell_source
  Now if you do a DIR Z: you will get a directory of df1:zshell_source.
  Similarly, the default device names can be reassigned.
eg.     assign libs: df1:libs

* Typing ASSIGN with no parameters, will list the current device
  assignments.
eg.     assign

* Only for OS2.0+:
 "ASSIGN name: REMOVE" or "ASSIGN name: dir REMOVE" removes that assign
 "ASSIGN name: dir ADD" assigns multiple dirs to name:
 "ASSIGN name: pathname DEFER" will become a normal assign when accessed
  the first time. So you can assign to a path that does not exist yet.
 "ASSIGN name: pathname PATH" assigns to a path. Similar to DEFER, but
  will not converted into a normal assign. If you have "assign bla: df0:
  path" and do "list bla:", you will get the directory of the disk
  inserted NOW (!) in df0:.
============================================================================
CD [destination]
* Changes the current directory to "destination". If no parameter
  is given, the current directory's name is shown. It is easier to
  change the directory by simply typing its name (without CD).

eg.     cd ram:
        ram:t               {same as "cd ram:t"}
============================================================================
COPY [-R] [-S] source1 [source2] ... [destination]

* COPY copies all source files or files in the source directories to the
  destination directory. If the destination directory does not exist, it
  will be created. If no destination is given (in this case you can specify
  only one source file/dir ofcourse), the current directory will be taken.
* You can use wild cards to specify files.
* The filedate, filecomment and protection-bits are copied with it.
* With Option -R given, subdirectories and the files and
  directories in there are also copied (recursive copying).
  If you have the ALL FLAG set, you can use ALL as last
  argument instead of -R.
* With Option -S given, it sorts. But who needs that ?

Note 1: Copying will be done in 50KBytes blocks. This should be a good
  value. You can change it with CONFIG COPYSIZE.
Note 2: You can use option ALL instead of -R .

eg.     copy c:dir df1:c
        copy dir list type cd df1:c
        copy -r df0:devs df1:devs
        copy -r source:*.s ram:
        copy df0: df1:          {only copy the files in df0: to df1:}

* You can also copy a file to a file. This is like copying to a dir and
  then renaming. Date, comment and bits are not copyied with it.
eg      copy df0:fred ram:wilma
  With that you can print a file etc.
eg.     copy file PRT:
        copy CON: barney
============================================================================
DELETE [-R] [-Q] source1 [source2] [source3] ... [FORCE]

* Deletes one or more files or directories ("source1","source2",...).
* "source" can be a wild card file description.
* If you specify the -r option when deleting a directory,
  then all subdirectories are recursively deleted also. Otherwise (if the -r
  option is not given) only the files in the specified directory are deleted.
* To be safe, delete requests you to really delete a file. You can answer
  with "Y" (yes) or RETURN if you want this file to be deleted
       "N" (no) if you do not want this file to be deleted
       "A" (all) if you do not want to be asked anymore
       "Q" (quit) if you want to abort deleting.
  To avoid asking, use option -q , but be careful !
* Ever got the problem with thousands of delete-protected files ?
  Solution is simple: Use FORCE as last option.

NOTE 1: "delete RAM:BLA" (BLA is a directory) tries
  to delete the directory "BLA", not the files in there !
  Use "delete RAM:BLA/*" (deletes only the files in there)
  or "delete -r RAM:BLA" (deletes all files and directories inside,
  then tries to delete BLA itself) for that !
NOTE 2: You can use option ALL instead of -R .

WARNING 1: You can hardly get back what you have deleted !
  So be careful, especially when using the -r option !
  (Try DISKSALV for getting lost files back, DO NOT USE DISCDOCTOR!)

WARNING 2: To delete (hard- or soft-)links you have to use wild cards !
  So instead of "delete c:linkname" use with OS1.3- "delete c:linkname|"
  and with OS2.0+ "delete c:(linkname)".

eg.     delete fred wilma barney betty dino
        delete df0:devs df1:c df1:data ram:
        delete menu/* force
        delete -r devs:
        delete -r df1:  {better use "delete device df1:"}
============================================================================
DELETE DEVICE devicename [name [filesystem]]

OS2.0+ only !
* Has the same effect as "FORMAT DRIVE device NAME name QUICK NOICONS".
  devicename is something like DF0: etc., but better not DH0: !
  The name and the filesystem of the disk will be kept the same, except
  you specify new ones. See INFO on how filesystems look like.
eg.: You have an Oldfilesystem- (OFS) disk and want to get a Fastfilesystem-
    (FFS) disk out of it. No need to format the whole disk ! Use
        delete device df0: empty ffs
============================================================================
DIR [-Q] [-R] [source1] [source2] ...

* Lists the directory of the "source" to the screen. Hitting space
  will pause the listing and backspace will continue it. Files are
  shown with their size in bytes. DIR lists the current directory
  if no parameter is given. If "source" is a filename, then only
  that file is listed. If the option "-q" is not given, the filenames
  will be sorted alphabetically. With the option "-R" given
  it will list recursive.
* All files/dirs with the H-bit (see PROTECT) set, will not be shown.
  All files that are ignored by FILENAMECOMPLETION are also hidden.
* If it is a link, it shows H (for hardlinks) or S (for softlinks) after
  the filesize. See MAKELINK.

eg.     dir df0:
        dir -q devs:printers/hp*
============================================================================
FILENOTE file|directory comment

* FILENOTE creates or changes a comment of the file or directory.
  This comment can be up to 116 characters long and can be displayed
  using the LIST command. It is useful if the filename does not say
  what for this file is. Add a comment to this file and you will
  forever know what this file does.

eg.     filenote devs:mountlist "This is used by the mount command"
============================================================================
HTYPE source [offset]

* HTYPE outputs a hex listing of the file specified. Output is the
  same as the M command. SPACE pauses the listing, BACKSPACE
  gets it going again, and CTRL-C will abort the listing.

* "HTYPE source offset" starts to display the file after "offset" bytes.

eg.     htype c:list
============================================================================
INFO

* Lists lots of information about all available volumes (like disks).
  These columns mean:
  NAME: Name of the device containing the volume
  UNIT: Unitnumber, not very interesting
  SYS:  Filesystem, can be one of:
        OFS : Oldfilesystem (old fashioned and slow)
        FFS : Fastfilesystem (needs OS2.0+)
        INO/INF : International OFS/FFS
        DCO/DCF : Directory Cache OFS/FFS (needs OS3.0+)
        MSD : CrossDOS Filesystem (MessyDOS)
        ??? : Unknown
  SIZE: Maximum useable size of the Volume in KBytes (1024 Bytes)
  FREE: Free/useable size in KBytes
  FULL: Ratio between used size and maximum size
  BLOCK: Size of a single block in Bytes
  STATUS: Says if it is possible to write to that volume
  ERR:  Number of soft errors, I only saw 0 yet
  VOLUME: Name of the volume (name of the disk).
* Note: It would not make sense to show the free size in Bytes,
  because space can only be allocated in whole blocks and one
  block is at least 488 Bytes large.

eg.     info
============================================================================
JOIN [-R] [-S] [sourcefile1] [sourcefile2] ... destfile

* JOIN concatenates one or more files to form a new file (destfile).
* wild cards are supported.
* See  COPY for more.

eg.     join fred.doc roy.doc dog.doc mydocs.doc
============================================================================
LIST [-R] [-Q] [source1] [source2] ...

* Lists the directory of the "source" to the screen. Hitting space
  will pause the listing and backspace will continue it.
* LIST acts similar to DIR, but outputs more information:
  - Hidden files will be shown
  - Shows the date and time of the last change. See DATE.
  - Shows the protection-bits. See PROTECT.
  - If available, the comment will be shown. See FILENOTE.
  - If it is a link, it shows where it is linked to. See MAKELINK.
    (Note:softlinks are resolved by ReadLink(), hardlinks by simply Lock())
* LIST supports recursive listing. That means the contents of all
  subdirectories are shown. To use it, specify the -r option.
* With the -q option given, it does not sort nor print
  comments and links.

eg.     list
        list sys:system
        list -q df0:
        list -r -q *.info    {show all INFO-files in the current and
                              in the sub-directories}
        list -r ram:~*.info  {show all except *.info files in RAM:}
============================================================================
LOCK device ON|OFF

* "LOCK device ON" locks the write-access to a device
eg.     lock df0: on
  will make it impossible to write to or change something on the
  disk inserted in DF0:
* "LOCK device OFF" makes write-access to a device possible again.

eg.     lock dh0: on
        lock dh0: off
============================================================================
MAKEDIR [directory1] [directory2] ...

* Creates one or more directories of the names specified.

eg.     makedir temp
        makedir c l s libs devs fonts
        makedir devs/printers ram:c
============================================================================
MAKEICON filename [icontype]

OS2.0+ only !
* Makeicon creates a default icon for the file "filename". "icontype" can
  be one of: DISK, DRAWER, TOOL, PROJECT, GARBAGE, DEVICE, KICK or APPICON
  "filename" is without appending .info.
  Note that DEVICE and APPICON will not be available on most systems.
* OS3.0+ only: Makeicon without icontype pops up the information-window
  of Workbench.

eg.     makeicon barney tool
        makeicon sys:libs drawer  {"makeicon libs: drawer" will not work}
        makeicon sys:system/format
============================================================================
MAKELINK linkname filename [SOFT]

OS2.0+ only !
* Makelink creates a Hardlink or Softlink to the file or directory
  "filename". "linkname" must be a filename, that does not exist yet.
  You can use links like the file/directory itself, but they need nearly
  no additional diskspace. In most cases you would use Hardlinks.
* If you delete a file a Hardlink is linked to, the Hardlink will become
  the file itself. Hardlinks cannnot work accross devices, use Softlinks
  for that. (Hardlinks are resolved by the filesystem.)
* Softlinks are links to a path, that is checked every time when accessed,
  so a link to DF0: depends on the disk inserted in DF0: .
  (Softlinks are resolved by AmigaDOS)
  I wonder why Softlinks are not supported by the commands in the C:
  directory even of Workbench 3.0 ? A bit old fashioned !

!WARNING: To delete (hard- or soft-)links you have to use wild cards !
!  So instead of "delete c:linkname" use with OS1.3- "delete c:linkname|"
!  and with OS2.0+ "delete c:(linkname)".

eg.     makelink muchmore ppmore
        makelink sys:commands c:
        makelink readme df0:readme soft  {so with "more readme" you will
    see the readme-file on the disk currently inserted into DF0: }
============================================================================
MORE source [line_count]

* MORE acts as a simple (ANSI) text file viewer. By default, it will
  show some lines of a text file, then wait for some user input.

eg.     more readme

 *After pressing "H" you get some Help information.
 *To move around in the text, you can use the CURSOR-KEYS:
    UP        : Go one line up
    DOWN      : Go one line down
    LEFT      : Go one page up
    RIGHT     : Go one page down
    SHIFT-UP  : Go to the top of the text
    SHIFT-DOWN: Go to the bottom of the text
  You can also use the keys 1,2,3,7,8 and 9 of your numeric keypad.
  SPACE does the same as SHIFT-DOWN, BACKSPACE the same as SHIFT-UP.
 *The key "S" will prompt you what to Search for. If you just press
  RETURN, then the last item will be searched for. Searching begins
  at the second top line shown. If the item is found, the line, it
  is in, is displayed as the first line.
 *The key "N" searches for Next occurence of the search string
 *The key "W" Writes the text to a file. If you enter PRT: as filename,
  the text is send to the printer. Press just RETURN to cancel.
 *Press "J" to Jump to a position you can give in %.
 *Press "R" after you have Resized the window (or to Redraw the window
  for another reason).
 *Press "Q" or "ESC" to quit MORE.
 *Typing any other key will be ignored.

All keys except the numeric keypad, SPACE, BACKSPACE and ESC can be
redefined using CONFIG MOREKEYS.

* Specifying the optional line count will allow you to show more or
  less than the default number of lines, that will fit exactly on the
  window. Useful when using FLAGS CUT OFF.

eg.     more contents 12
        more super.doc 25
============================================================================
MOVE [-R] [-S] source1 [source2] ... [destination]

* This is very similar to the copy-command, but all files/directories
  copyied will be deleted afterwards. If an error happens, the source will
  not be deleted. If it was OK, you will see "... copyied"
* If source and destination are on the same device it uses rename
  instead. This is quicker and needs less disk accesses. Then you will
  see "...moved".
* Note the difference between "move dir" and "move dir/*".

eg.     move ram:a ram:b
        move -r df0:* df1:
        move c:mount devs:
============================================================================
PROTECT [-R] [-S] filename1 [filename2] ... [+|-|=|h|s|p|a|r|w|e|d] [+|...

* Allows you to alter/see the protection bits associated with a file
  or a directory. To see it, you can also use LIST.
  You can use wild cards to process multiple files.
* See COPY  how to use -r and -s.
* PROTECT filename +bits_to_set -bits_to_clear
  Sets all bits_to_set and resets all bits_to_clear.
  You can give one + or one - or both or both not.
* PROTECT filename =bits_to_be
  Sets all bits_to_be and resets all other bits

eg.     protect game +hp -rwd
        protect monitor =srwe
        protect -r df0:* -d

Bits:   "h"     hidden  V1.3
        "s"     script  V1.3
        "p"     pure    V1.3
        "a"     archive V1.3 -> is reset when file is changed
        "r"     readable
        "w"     writable
        "e"     executable   -> will be checked before executing
        "d"     deletable
============================================================================
RELABEL drive newname

* RELABEL renames the disk specified with the newname given.

eg.     relabel Empty: MY_DISK
        relabel df0: FISHMONGER
============================================================================
RENAME source destination

* Renames the file or directory of name "source" to that of
  "destination". You can use this to move files on a disk.

eg.     rename df0:c/list df0:ls        {moves and renames}
        rename ed Editor                {just renames}
============================================================================
RESIDENT [command1] [command2] ...

* RESIDENT allows you load commands into memory, such that they
  will execute immediately, rather than be loaded from disk all the
  time. The benefit of RESIDENT over saving commands on the RAM:
  disk is that only one copy of the command is in memory all the
  time. RAM: based commands will use up twice as much memory when
  the command is being executed.

* The limitation of RESIDENT is that only certain commands will
  work. Generally, all commands which have their PURE bit (see
  PROTECT) set can be made RESIDENTABLE. However, RESIDENT
  does not check whether the PURE bit is set before loading, and
  hence you can try out commands to see if they work. They'll
  always work the first time. Its only when executing the 2nd
  time that the Amiga will likely crash.
  Note: Crunched programs will most likely not work.

* Typing RESIDENT with no parameters will show the current list
  of resident commands:
    ADRESS is useful for programmers
    USECOUNT says how many times it is used right now
             ROM internal residents have negative values
    NAME means the name  (hard to guess :)

* Typing one or more command names after RESIDENT will make those
  commands resident. ZShell will search the command search path
  to try and find them.

eg.     resident c/list c/cd c/date c/avail
        resident ed
============================================================================
SEARCH file search_string

* SEARCH searches for the search_string in the file. The file can
  be a binary (eg. executable) or a text. Each occurance
  will be printed on the window with highlighted search_string.
  If the file is a text, the whole line will be printed.
  If it is a binary file, it will be printed from the occurance
  to the next NULL or LF.
* Searching is case independent (of course!).
* To search for a string at the beginning of a line (textfile only)
  put a point (.) before the search_string.

eg.     search zshell.doc "binary (eg."
        search s:startup-sequence .assign
          {show all assigns, but not "resident assign"}
        search c:mount $ver:    {show version number and date,
                            should work with all newer executables}
============================================================================
SETDATE file|directory [date/time]

* SETDATE changes the date-of-last-change (DOLC) of a file or directory.
  The DOLC can be shown by simply listing this file with LIST.
* SETDATE with no date/time given sets the DOLC to the systemtime
  (see DATE,SETCLOCK).
* If you want to set the DOLC to a special date you have to specify
  the date or time or both in a format described at DATE.

eg.     setdate ram:newthings
        setdate devs:mountlist 21.8.71      {very old}
        setdate murks 18:24:12 12-24-96     {future}
============================================================================
SPLIT [-Q] source dest length [offset]

* SPLIT is the opposite of JOIN.
  It splits up a (large) source file into several smaller pieces which
  get their name from "dest" and an automatically appended two digit
  number. The asking between the single files allow to change floppy
  disks and makes it possible to split a large file directly on multiple
  floppy disks. See delete for more about that.
  (The source file does not need to fit into memory.)

eg.     split aminet.index df0:index 750000
  {assuming that aminet.index is 2MB big, this creates df0:index01
  df0:index02 and df0:index03 }
other egs.  split -q bigfile small 10000    {does not ask}
            split bigfile small 10000 5000  {skip the first 5000 bytes}
============================================================================
TYPE source

* Prints to the screen the ASCII/ANSI text file specified as "source".
  Hitting any key will pause the listing. Backspace will restart it.
  CTRL-C will abort the listing.
* Use MORE instead of TYPE, if possible.

eg.     type readme
============================================================================

############################################################################

============================================================================
Builtin Commands for Scripts and Controlling

Following there are descriptions of the other commands which are
builtin in ZShell (and therefore need not be loaded from disk).
Square brackets [] mean that the argument enclosed in is optional.
A vertical bar | separates multiple possibilities, choose only one.

Alias [variable] [definition]
Ask [question]
Avail [-C]
Border ON|OFF [number]
Cls
Date [hh:mm:ss|dd.mm.yy|mm-dd-yy]
Echo [string]
Else
EndCLI [-C]
EndIf
Eval expression
Execute [ZSHELL] source
FailAt [failat_level]
Fault [error_number]
Help [topic]
If [NOT][WARN][ERROR][FAIL][EXISTS file]
Lab label
MemClk ON|OFF|ALARM
NewCLI [-Wnew_window] [-Sstart_script] [-Ccommand] [-N] [-Hhelpfile] [-E]
Path [-C] [path1] [path2] [path3] ...
Prompt [string]
Quit [error_code]
Review [bytesize|-C|-Sfilename]
Run commandline
SetClock LOAD|SAVE
Skip label
Stack [size]
UnAlias [alias1] [alias2] [alias3] ...
Wait timeout
Comments
============================================================================
ALIAS [variable] [definition]

* ALIAS assigns a variable name to a definition. The variable name
  can be up to 15 characters long, and the definition can be up to
  about 360 characters long.

* Typing ALIAS with no parameters at all, will generate a list of all
  current alias definitions.
  eg.   alias

* Aliasing of Function Keys
  eg.   alias f1 ed df0:s/startup-sequence^M
  This example assigns the unshifted F1 key to "ed df0:s/startup-sequence"
  with following return. Note that the ^M characters puts an auto
  carriage return in the definition.
  eg.   alias F10 cd df0:^M
  This sets shifted F10 to "cd df0:<CR>".
  You can use quotes to make it look better:
        alias f2 "cd df1:^M"
        alias f4 "genim2 "
        alias F9 "scribble df0:text/"
  If you want to use a semicolon in the alias, you need to use quotes:
        alias f1 "a68k z.a;blink z.o to z^M"
  or leave away the quotes and use a backslash before the semicolon:
        alias f1 a68k z.a\;blink z.o to z^M

* Aliasing of commands
  eg.   alias mv rename
  This allows an alternate name for rename. i.e. mv.
  So you could type
        mv oldname newname      {to rename oldname to newname}

  eg.   alias as a68k
        alias pp powerpacker
        alias go "a68k zsh.s;blink zsh.o to zsh"
        alias cped copy df0:c/ed
  You would use this last alias, if you need to copy a particular
  file a lot. So, to copy c/ed to ram: use:
        cped ram:

* You can also pass external parameters to an alias.
  eg.   alias al "%1 a68k $1.s;blink $1.o to $1"
  Typing
        al test
  will assemble test.s using a68k, then blink test.o to become test.

You can specify upto eight parameters to pass to a command alias.
At the start of the alias definition, specify the parameters to pass
with the variables %0 thru %7. These need not be in sequence. The
first %n will be assigned to the first parameter, the 2nd %n to
the 2nd parameter etc.
Insert the corresponding variables $0 thru $7 at the points in the
alias definition where that parameter is to appear.
eg.     alias disp %1 %2 %3 echo "$3 $2 $1"      {is the same as: }
        alias disp "%1 %2 %3 echo "$3 $2 $1""    {note the quotes}
        alias cram %0 %1 %2 %3 copy $0 $1 $2 $3 ram:
        alias go %5 %1 %6 %2 echo "1st-$5 2nd-$1 3rd-$6 4th-$2"

* Command aliases can be nested to nearly unlimited levels.
  eg.   alias clear echo ^L\;alias cdir "%1 clear;cd $1;dir"

* An important point about aliases, is that you can redefine the
  existing internal command names.
  eg.   alias help "type help_screen"
  This would make it so that pressing HELP or typing H E L P would
  not generate the standard help command list, but would type the
  file called  help_screen to the screen. Similarly
  eg.   alias copy c:copy       {replace copy by disk-based copy}
        alias info c:dfree
        alias list .list        {replace list by disk-based list}

* See UNALIAS for how to remove alias definitions.
============================================================================
ASK [question]

* ASK prompts the user with a question requiring a Yes or No
  answer. If the first letter of the users response is "Y", ASK
  returns code WARN. Responding "E" returns ERROR, "F" returns
  FAIL. Any other letter will result in return code OK.
  The question can include ASCII characters as well as control
  codes as per the ECHO command.

eg.     ask "Do you want commands copied to ram? "
        if warn
               copy c: ram:
        endif

Note: You can redirect the ANSWER to a file by redirecting the OUTPUT.
eg.     ask >ENV:CallIt        {The answer is written to CallIt}
============================================================================
AVAIL [-C]

* AVAIL shows the available memory as:
  1.Total chip memory free,
  2.Total fast memory free,
  3.Total memory free.

* With option "-c" given, it tries to free unused memory
  (remove unused libraries, devices and the help manual)

eg.     avail
        avail -c
============================================================================
BORDER ON|OFF [number]

* Switches the border of the window on or off. If the border is off
  there will fit some more characters in a line; this can be useful
  when viewing texts with MORE.
* If you run OS1.3-, you should do a CLS or "echo ^L" after
  using BORDER OFF.
* If you specify a number after ON or OFF, the window is resized as
  large as possible. The number means the wanted distance of the
  window top to the screen top in pixels. By specifying a negative
  value the window will just not hide the screens menu bar.

eg.     border off
        border on 0         {fills full screen}
        border off -1       {does not hide the menu bar}
        border on 10;cls    {with OS1.3-}
============================================================================
CLS

* CLS clears the window.
  It also resets the consolehandler, so if you see lots of funny
  characters on the window, try CLS.
* You can do the same by using "echo ^[c".
* CTRL L only clears the window (same as "echo ^L").

eg.     cls
============================================================================
DATE [hh:mm:ss|dd.mm.yy|mm-dd-yy]

* DATE without arguments shows the actual date and time (systemtime).
* You can specify one or two arguments to set date or time or both.
  The time format must be in HOUR:MINUTE:SECOND . Do not forget the
  colon (:) between. Give only one or two digit numbers.
  There exists two formats for setting the date. First is
  DAY.MONTH.YEAR . Second is MONTH-DAY-YEAR . Use only one or two
  digit numbers.

eg.     date
        date 14:15:00         {quarter past two PM}
        date 12.5.94          {12th of May in 1994}
        date 3-30-88 8:12:45  {30th of March in 1988 in the morning}
============================================================================
ECHO [string]

* Prints the "string" to the screen. If you want spaces in the
  string, make sure the whole string is enclosed in quotes. If you
  want to print special control characters (eg. ctrl-L clear screen)
  then prefix the control letter with a ^ character. If you want to
  print double quotes, then use the \ character before the qoutes.
  If you want to print some special characters like the CSI ($9B),
  you can put a (hexa-)decimal number after the ^ character; you can
  separate it from the next character by a point (.) . Do not forget
  the ^J at the end of a line.

eg.     echo hello^J
        echo "Hello world !"
        echo Hello world !
        echo "^Lthe screen was just cleared^J"
        echo "^Lline 1^Jline 2^Jline 3^J"
        echo "these are double quotes ->\"^J"
        echo ^*33mColor^*32mful^J
        echo ^*4mUnderlined^*0mNormal^J

* Some common control codes are:
  ^7    ^G      bell (makes a DisplayBeep)
  ^10   ^J      linefeed.
  ^12   ^L      clear screen.
  ^13   ^M      carriage return.
  ^24   ^X      clear line.
  ^27   ^[      escape.
  ^$9b  ^*      CSI (command sequence introducer).
============================================================================
ELSE

* ELSE marks the middle of an IF statement. All statements
  following it, and before the ENDIF statement will be executed
  only if the IF condition is FALSE. See IF for usage.
============================================================================
ENDCLI [-C]

* Exits you from ZShell back to the AmigaDOS CLI prompt or Workbench.
* If the option "-c" was specified, it will clear ZShell as a
  resident: only in low memory situations needed.
* Instead of using ENDCLI you can simply press the ESC key or click
  on the close gadget, if available.

eg.   endcli
      endcli -c
============================================================================
ENDIF

* ENDIF marks the end of an IF statement. See IF for usage.
============================================================================
EVAL expression

OVERVIEW
========

  Operators:
  + Add
  - Subtract
  * Multiply
  / Divide
  & Logical and
  ! Logical or
  = Poke into memory
  ? Peek out of memory

  Prefixes:
  + Positive number
  - Negative number
  % Binary number
  $ Hexadecimal number
  & Hexadecimal APTR converted to BPTR
  ! Hexadecimal BPTR converted to APTR
  ^ Filename containing number


* EVAL evaluates the "expression" as a reverse polish expression,
  and displays the answer in decimal and hex notation. Reverse
  Polish Notation (RPN) is used in Forth and in Hewlett Packard
  calculators (I have a HP48GX which has really a great functionality,
  but unfortunately is a one-way product: If something is defective, you
  have to throw it away in most cases).  It is based on how arithmetic
  is actually done at the lowest possible level. RPN allows calculating
  complex expressions without using brackets.

eg.     eval 4 5 +
  This gives the answer 9. When a number is found, it is "pushed"
  onto the arithmetic stack. The + always adds the last two numbers
  on the stack.

eg.     eval 7 2 3 + -
  This gives the answer 2. It is the same as (7 - (2 + 3)). See,
  7 is first pushed onto the stack, followed by 2, then 3. The +
  adds together the 2 and 3 and leaves the result 5 on the stack.
  Which means that the number 7 followed by 5 are left on the
  stack. The - subtracts the last entry (5) on the stack from the
  one before it (7), leaving the result 2.

eg.     12 * (3 + 9)                    > eval 12 3 9 + *
        (15 - 4) * (6 + 18)             > eval 15 4 - 6 18 + *
        (6 * ((87 + 13) / (2 * 25)))    > eval 6 87 13 + 2 25 * / *

* EVAL only performs 32 bit integer arithmetic.
  Negative numbers are prefixed with - .(hexadecimal they are
  shown as a 31 bit integer with bit 32 set, as usual)
  Prefixing positive numbers with + is optional.

eg.     eval +5 -3 +    {results in 2  hex:$00000002}
        eval -5 3 +     {results in -2 hex:$fffffffe}

* EVAL supports decimal, hexadecimal and binary  numbers.
  If you prefix the number with $, the number is hex
  If you prefix the number with %, it is binary.
Programmers: For BPTR-APTR conversion you can use & to specify
  a hexadecimal APTR when asked for a BPTR and vice versa with !.
eg.     eval $c00000 $a0 16 * +

* EVAL can also be used to perform base conversions (to dec or hex)
eg.     eval $ca
        eval %10110001
        eval 45
        eval &5a8

*  The & allows logical AND'ing. And ! allows logical OR'ing.
  The ? is similar to PEEK in BASIC.
  Conversely, = is similar to POKE in BASIC
eg.     eval $80 $21 $08 ! ! $aa &
        eval $67 %11001011 &

        eval $c00000 ?
  This prints out the long word in memory locations $c00000 - $c00003.

        eval $aa55aa55aa $40000 =
  This pokes the long word $aa55aa55aa into locations $40000 thru $40003
  and prints out what was in before.

* For environment handling you can specify the value of an
  environment variable with ^ followed by the name.
  To store the result in a variable, redirect the output.

eg.     eval >ENV:aa ^ENV:bb 1 +
  This adds 1 to the value in ENV:bb and stores the result in ENV:aa
* If the result was 0 an error (fail-level 10) will be returned.
  If it was negative, a warn (5) returns. (Not when redirecting output)
============================================================================
EXECUTE [ZSHELL] source

* "EXECUTE source" executes the AmigaDOS script file of name "source"
  using an AmigaDOS shell, so no compatibility problems should occur.
  However in AmigaDOS scripts you cannot use ZShell-internal commands.

* To execute a ZShell script you have to set the S-protection flag
  and then you can execute it treating like a normal command
  or you have to use "EXECUTE ZSHELL scriptname".
  All ZShell commands, as well as commands from disk are valid within a
  ZShell script file.

* You can break scripts by pressing CTRL-D.

eg.   execute install_hard_disk
      execute zshell s:zstart
============================================================================
FAILAT [failat_level]

* FAILAT sets the error code level at which scripts (and multiple
  commands on one line) will be aborted. The default level is 10.
  Most commands return 10 as an error, (20 for serious errors)
  while compilers returning Warning type errors will return 5.
  Hence, the default of 10 will allow Warnings to occur without
  the script (or line) being aborted. If a command returned an error
  code higher than the failat level, it will be printed out on the
  window.

eg.     failat 20       {sets failat level to 20}

* If you do not specify a failat level, the current setting is
  shown.

eg.     failat
============================================================================
FAULT [error_number]

* FAULT displays a textual error message of the given DOS-error-number

eg.     fault 103
  (says something like "no free store", go and buy some extra memory :-)
============================================================================
HELP [topic]

* HELP shows the lines of this manual corresponding to the topic.
  To see all topics available, type "HELP CONTENTS" . Make sure that
  the manual "ZShell.doc" is in the current directory or in S: !
  For some help about a command you can also type "commandname ?" .
  Type only "?" to read the manual with MORE.
Note: Instead of typing the topic you can type just some starting
      characters.
Note: The manual is only loaded once and will stay in memory till
      you use AVAIL -C or ENDCLI -C

eg.    help contents       {"help cont" will do the same}
       help copy
       makedir ?
       ?

* HELP without a topic lists the names of all available ZShell
  commands to the screen. This does not need the manual.
  HELP can also be invoked by hitting the HELP key.

eg.   help
============================================================================
IF [NOT][WARN][ERROR][FAIL][EXISTS file]

* The IF command allows conditional execution of statements
  following it.
* If the condition specified is true, then execution continues
  after the IF statement until either an ENDIF or ELSE statement
  is encountered. If it is an ELSE statement, then all statements
  between the ELSE and the closing ENDIF are skipped.
* If the condition is false, then all statements after the IF and
  before either an ENDIF or ELSE statement are skipped. If an ELSE
  is encountered, then execution continues for all statements after
  the ELSE and before the closing ENDIF.
* IF can examine the state of the return code from the last command
  execute with WARN, ERROR, and FAIL tests. You can test for the
  non existence of such a state by including the optional NOT
  parameter.

eg.     IF WARN
           echo "last command returned warnings"
        ELSE
           echo "last command did not return warnings"
        ENDIF

        IF NOT FAIL
           echo "last command did not fail"
        ENDIF

* IF can also test for the existence of a file or directory.

eg.     IF EXISTS :system/format
           echo "this disk has a format command"
           echo "you can look yourself. I'm not joking"
        ENDIF

        IF NOT EXISTS ram:ed
           copy c:ed ram:
        ENDIF
============================================================================
LAB label

* LAB specifies a destination (label) for the SKIP command.
============================================================================
MEMCLK ON|OFF|ALARM

* MEMCLK is for using a clock shown in the border of the actual
  window. The current total free and chip free memory are also
  shown. It can do a DisplayBeep (short flash on all screens) at a
  specified time. The DisplayBeep can be converted into a sound
  by using a PD-utility for that or using Workbench 2.1+ .
* Programmers: There will be only one "MemClock"-Task, even if you
  run MEMCLK on many windows  -> memory and CPU saving.
* MEMCLK ON switches the clock on or does nothing if it already
  exist.
* MEMCLK OFF switches the clock off or does nothing if it does not
  exist.
* MEMCLK ALARM shows the alarm time. If you type a time (see DATE)
  after ALARM, you set the alarm time. (You cannot set an alarm date
  or multiple times.) ( MEMCLK A is the same as MEMCLK ALARM )

eg.     memclk on
        memclk off
        memclk alarm
        memclk a 21:34:07

* The clock can also be used on non-ZShell windows, but MAKE SURE
  that the clock is switched OFF BEFORE the window is CLOSED,
  otherwise you will see THE GURU (or an ALERT with OS2.0+)
  For example, to get a clock on the Workbench, type in ZShell
        wait 5;memclk on
  and press RETURN. Now you have 5 seconds to click on the Workbench
  screen. For removing use "wait 5;memclk off" .
============================================================================
NEWCLI [-Wnew_window] [-Sstart_script] [-Ccommand] [-N] [-Hhelpfile] [-E]

* NEWCLI without arguments starts a new ZShell process.
  Things like paths, aliases and history buffer (!) will be copied to
  the new ZShell. The input/output window is created with the default
  specification. The startup script will be S:ZStart.
* "NEWCLI -Wnew_window" is used for opening a window with different
  specifications than the default. If you specify just "-W",
  there will be no window and output will be send to NIL: ; if there
  is input necessary, the ZShell process will just end (for
  example at a end of a script).
* "NEWCLI -Sstart_script" is used if the name of the startup script
  should be different from S:ZStart. If you specify just "-S", no
  script will executed.
* "NEWCLI -Ccommand" executes the command when starting. No script
  will be executed.
* See Start from CLI for more information about the options.

eg.     newcli
        newcli -wcon:30/30/400/50/Shell
        newcli -wcon:50/20/500/100/Hello -ss:shell-startup
        newcli -sram:doassigns -w
        newcli "-wcon:30/30/400/50/Great Shell" "-cecho Welcome !"
============================================================================
PATH [-C] [path1] [path2] [path3] ...

* PATH defines the command search path used by ZShell when searching
  for disk based commands (see EXECUTING COMMANDS) .
  If you give the "-c" option, the old search path will be cleared
  and the new search path consist only of the given paths.

eg.     path -c c: ram:c df0: df1:
  This example will make it so that if you type a command which is
  not internal in ZShell, the resident list will be searched for it,
  then the current directory, then the c: directory, then the ram:c
  directory, then df0:, and finally df1:

* By omitting the -c option, you can add a number of paths onto the
  existing command search path.
eg.     path df2:c
        path df1:bin df1:myprogs

* If, however, you type path with no parameters, the current search
  path will be displayed.

* When starting ZShell the paths of Workbench (if available) will be
  copied.

Note: It is a crazy thing that AmigaDOS shell always has C: as last path.
  In my startup-sequence you can find something like:
  "path ram: c: sys:utilities sys:system s: sys:prefs"
  In AmigaDOS shell the C: directory will then be searched twice if a
  command could not be found. Only having C: as last path slows down
  access, because most commands are in C:.
  That is why you have to specify C: explicite in ZShell where you want it.
============================================================================
PROMPT [string]

* If no parameter is typed, the current prompt setting will be shown.

eg.     prompt

* If a prompt string is specified, the current prompt setting
  will be changed to that string. The character "%" specifies a
  special prompt option:

    %p      Insert whole path of current directory.
    %s      Insert last part of the path of current directory.
    %n      Insert CLI number
    %l      Insert current input line number (for fun!)
    %c      Insert last command (for even more fun ! :-)

* You can use control sequences like in the ECHO command.

eg.     prompt "%p> "     {default prompt. Show current directory + ">"}
        prompt "%n.%s> "  {show CLI number, then current dir, then ">"}
        prompt Hello!     {shows "Hello!" at the start of every line}
        prompt %p^J^*32m> {Just try it!}
============================================================================
QUIT [error_code]

* QUIT forces a script file to end, and return to the shell.
  An optional error code can be passed back (ie. 5=WARN 10=ERROR
  15=BAD 20=FAIL etc).

eg.     quit 5
        quit
============================================================================
REVIEW [bytesize|-C|-Sfilename]

With the reviewbuffer you can see that again what scrolled out of the
window or was redirected. In the reviewbuffer are all outputs stored.
To see what is in the reviewbuffer just press SHIFT TAB. This activates
the MORE text reader.
* "REVIEW bytesize" (re)creates a reviewbuffer with the given size.
* "REVIEW 0" removes the reviewbuffer.
* "REVIEW" without arguments shows the adress and size of the current
  reviewbuffer.
* "REVIEW -C" clears the reviewbuffer.
* "REVIEW -S filename" saves the reviewbuffer to that file.

eg.     review 10000        {starts normal reviewbuffer}
        review 50000        {starts big reviewbuffer}
        review 0            {deletes reviewbuffer}

NOTE 1: Because it uses a circular buffer with fixed size, this is much
  faster than having a fixed number of lines. The decrease in scrolling
  speed is neglible.
NOTE 2: The Write function of the dos.library will be patched, so
  there might be problems with other programms that patch this too.
============================================================================
RUN commandline

* RUN executes a commandline in a background task. If you want to
  execute several commands, you can separate them with \; .
* By default output goes to the current window. To surpress output or to
  get it into a file or onto a different window you can use redirection
  symbols like ">" (no output), ">filename" or ">w" (to a new window).
  In case of output redirection the launched background task will be
  totally independent from the task it is launched from.
* Input will be redirected to the same window output goes to. If you
  redirect output to a file, no input is possible (redirected to NIL:).
  Input redirection symbols does not make sense with the RUN command.
* Because most things will be inherited to the new shell, you can use
  Aliases.

eg.     run copy fred.doc prt:
        run >prt: type barney.doc
        run >w dir df0:\;ask
============================================================================
SETCLOCK LOAD|SAVE

* SETCLOCK only works if you have a battery backed up clock (BBUC).
  It accesses the adresses $DC0000 and I do not know if it works
  with very old or very new (A1200) clocks.
* SETCLOCK LOAD sets the systemtime (you can see the systemtime with
  DATE or MEMCLK) to the time in the BBUC (hopefully this is the
  right time).
* SETCLOCK SAVE first resets the BBUC, then stores the systemtime
  to the BBUC.
  To set the BBUC to the right time, use DATE to set the correct
  date and time, then use SETCLOCK SAVE.

eg.     setclock load
        setclock save
============================================================================
SKIP label

* SKIP searches for the label within the current script file. If it
  finds it, execution continues from that point onwards. Labels
  are specified using the LAB command.

eg.     lab myloop
        dir ram:
        ask "list ram again? "
        if warn
           skip myloop
        endif
============================================================================
STACK [size]

* Allows you to view or alter the current stack size.

eg.     stack            {shows the current stack size}
        stack 30000      {sets current stack = 30000 bytes}
============================================================================
UNALIAS [alias1] [alias2] [alias3] [alias4] ...

* UNALIAS removes one or more alias definitions from the alias list.
* UNALIAS without arguments removes all aliases.

eg.     alias f1 "cd df0:;dir^M"
        alias f2 "cd df1:;dir^M"
        ...
        alias f10 "ed df1:s/startup-sequence^M"

        unalias f1 f2 f3 f4 f5 f6 f7 f8 f9
        ...
        unalias f10
============================================================================
WAIT timeout

* WAIT halts processing for the time given. Timeout is in seconds.
  You can abort this with CTRL-C.

eg.     echo "I'll wait a minute"
        wait 60
============================================================================
Comments

; blah blah blah blah
* etc etc etc
# hello ma

* Placing a semi-colon, an asterisk or a hash character as the 1st
  character in the line of a script file allows you to place comments
  in it.

eg.   ; This is a comment line

* If you want to place a comment at the end of a line, you have to
  put ;# before it.

eg.   info;#to see something interesting
============================================================================

############################################################################

============================================================================
Builtin Commands for Advanced Users

These commands are thought for users with a deeper knowledge of the
system. Maybe they are also useful for those not knowing of the system
internals. Just try the examples to find that out.

Break task_description [signalmask|C|D|E|F]
Config CTRLKEYS|MOREKEYS|DOT|HIDE|COLOUR|COPYSIZE|FNCSIZE
DiskChange device
Flags [CHECK|MATCH|ICON|WILD|ERRORS|DEBUG|CUT|ALL|HIDE|PIPE] [ON|OFF]
GetMsg [portname]
Kill device|taskdescription
Locate [-C] [bptr|name] [READ|WRITE]
M [start_address] [end_address]
PutMsg port_description [number1|string1] [number2|string2] ...
Show D|I|L|M|P|R|S|T|V
Strings sourcefile [count]
TaskPri priority [task_description]
============================================================================
BREAK task_description [signalmask|C|D|E|F]

* BREAK sets some signals at a given task
* task_description can be one of:
  - task/process name (case dependent !)
  - task/process adress
  - CLI-process number (one from 1 to 20)
  - zero (0) for this task
  It will be checked if the node-type field contains TASK or PROCESS
* signalmask is a longword; all bits, which should be signalled,
  must be 1 . Alternatively you can specify c,d,e or f to set
  the according signal to CTRL-C,-D,-E or -F. (CTRL-C is bit 12)
* BREAK without signalmask (and c,d,e,f) given sets all signals the
  task is waiting for.

eg.     break RexxMaster    {and it will be gone...}
        break Exchange c    {Exchange will get itself off too}

eg. If 2 ZShells are running. The one with the CLI-number 1 (get that
    out with prompt %n) lists a very large directory. You can break
    that by using the other ZShell typing:
        break 1 c
    Thats the same like you pressed CTRL-C on the ZShell number 1.
============================================================================
CONFIG CTRLKEYS|MOREKEYS|DOT|HIDE|COLOUR|COPYSIZE|FNCSIZE

This command is for changing the default settings.

* CONFIG CTRLKEYS is for command-line-editing-keys-definitions
  (great word :).  In other words: You can change the meaning of keys
  pressed with CTRL (Control) key and some other keys (TAB ^I,
  Backspace ^H, Return ^M, Shift-Return ^J, ESC ^[).

  "CONFIG CTRLKEYS" shows the current settings,
  "CONFIG CTRLKEYS WQSEIX[TYHJMLRVFP" sets the default settings.

  To change something, just change the character corresponding to
  the key pressed with CTRL. See some lines above for some CTRL-
  equivalents.
  eg. TAB is same as CTRL-I . So to use CTRL-K instead of TAB, you use:
        config ctrlkeys WQSEKX[TYHJMLRVFP
  Warning: You may get confused if you define one key twice.
  If you want to get really confused, try:
        config ctrlkeys WQSEKX[TIYMJHRVFP

* "CONFIG MOREKEYS" shows the keys that can be pressed inside MORE.
  The uppercase keys represent the cursor keys, default is: ABCDSTqsnjwrh
  It works similar to CONFIG CTRLKEYS. To use RETURN key to exit MORE use:
        config morekeys ABCDST^Msnjwrh     (see also ECHO)

* "CONFIG DOT character" replaces the dot character (.) where it has a
  special meaning (ECHO,SEARCH,PUTMSG, dir back, force disk, abbreviation)
  eg.   config dot *

* "CONFIG HIDE pattern" sets the files that are hidden by DIR
  and filename completion. The pattern must contain at least
  one wild card.
  "CONFIG HIDE" shows the current settings (by default none).

  eg.   config hide         {display current hiding pattern}
        config hide ""      {unset the hiding pattern}
        config hide *.info  {ignore *.info-files}
        config hide *.info|*.bak {hide files ending in .info and .bak}
        config hide ~*.tex|*.dvi {show only *.tex and *.dvi-files}

* "CONFIG COLOUR colours" defines the use of colours. "colours" has to be
  a 8 digit number. The digit at position x defines to what colour number
  the default colour x is mapped to. Everything clear ? (I think no!)
  Thsi is global. Do not forget to make a CLS afterwards.
  eg.   config colour 01234567   {sets the default colours}
        config colour 01111111   {switches to one colour mode, very useful
                                  with OS3.0+ to speed up scrolling}
        config colour 01233321   {if you want to use only 4 colours}

* "CONFIG COPYSIZE bytesize" sets the size of the memory block used for
  COPY, MOVE and SPLIT to "bytesize" bytes. The default setting 50000
  semms to be a good value for both harddisk and floppydisk. If you
  only use floppydisk try:
        config copysize 20000
  and to display the current setting use:
        config copysize

* "CONFIG FNCSIZE bytesize" sets the size of the memory block used to
  store the last used directory at filename completing (=FNC).
  If this memory block (=FNC buffer) is too small, FNC has to read the
  directory again every time you press TAB and TAB cycling does not work.
  To save memory you can try:
        config fncsize 2000      for 2000 bytes FNC buffer or
        config fncsize 0         for no FNC buffer at all
  and to display the current setting use:
        config fncsize
============================================================================
DISKCHANGE device

* Needed for devices which do not detect a diskchange.

eg.     mount rad:;diskchange rad:
  Makes your rad:-disk appear on the Workbench.
        diskchange ram:
  If the ram-disk does not exist yet, the handler will be started
  (and the ram-disk can appear on Workbench when done before LOADWB)
============================================================================
FLAGS [CHECK|MATCH|ICON|WILD|ERRORS|DEBUG|CUT|ALL|HIDE|PIPE] [ON|OFF] ...

* With this you can configure some things. Use FLAGS without arguments
  to see the current settings. The meaning of the keywords are:

CHECK: (default off) Activates or deactivates the programmers status line.
  It is intended to debug external commands.
  The status line (if activated) will only appear once a disk based
  or resident program has been executed. The line appears as follows:
  Result2: 0  time = 00:00:23.66  changes-> chip: 0  fast: 0  total: 0
  Result2 shows the error code that can be asked for with IoErr.
  Time shows how long the program took to execute in hours,
  minutes, seconds, hundredths (This time does NOT include the time
  it takes to load the program from disk). Changes show if the program
  has left any memory still allocated. i.e. if 200 bytes of chip
  memory were left allocated by the program, then you see "chip: -200".
  The Return code (the program returns in D0) is shown as Fail-Level.
  It also does some low memory checks on 68000 CPU systems. Be warned if
  a "Changed ..." appears. Like Mungwall it sets address 0 to $C0DEDBAD.

MATCH: (default on) By default Filenamecompletion shows all files that matches
  the given pattern. You can switch this off by using "FLAGS MATCH OFF".

ICON: (default off, OS2.0+) This enables iconifying when pressing ESCAPE
  or clicking the Close-Gadget. To exit from ZShell use ENDCLI.
  You need Workbench running and ZShell must have opened its own window
  (start from Workbench, start with newcli or used -W when started from
  CLI).  When iconifying, a icon is created on the Workbench and the
  window is closed. Double-clicking on this icon or dragging a file into
  it pops ZShell up again. Use the ToolTypes "ICONNAME", "XPOS" and
  "YPOS" to determine the name and position of the icon.
  ToolType "ICONIFY" lets ZShell start in iconifyed mode.

WILD: (default on, OS2.0+) By enabling this, you force ZShell to use
  AmigaDOS wildcard-patternmatching instead of the internal matcher.
  Switch this off if you like the internal matcher better.

ERRORS: (default off) Most external commands show their errormessages
  themselves, so you often see double error messages. Using ERRORS you can
  switch off this behaviour, but you risk to miss some errormessages !
  If you see a large errornumber, this command assumed that there will be
  no error-output and does not set the correct errorcode --- this is
  badly programmed !

DEBUG: (default off) This is for testing/debugging script-files. Switching
  DEBUG to ON, the commands from the script appear on the window as they
  are processed (you need to execute the script for that, ofcourse),
  and redirection will be ignored (so you will see even output to >NIL: ).

CUT: (default on) For MORE. If ON, lines longer than the window will be
  cutted at the end. If OFF, too long lines will wrapped to next line.

ALL: (default on) Enables the substitute ALL for the option -R.
  Note that -R must be the first argument (or second after -Q) and ALL
  must be the last argument.
  (Only in this release you can place ALL anywhere you like)

HIDE: (default on) When on the cursor will be hidden for outputting. This
  improves scrolling speed. Switching off is only thought for debugging.

PIPE: (default on) If ON, real pipes will be used, pseudo pipes otherwise.
  See Anonymous Pipes for more.

eg.     flags icon on all off
        flags errors off all off check on
        flags e. off a. off ch. on          {same as above}
============================================================================
GETMSG [portname]

* GETMSG waits for a message arriving at the process-internal
  messageport (pr_MsgPort). The message will be shown, strings
  will be tried to detected (this could cause lots of enforcer hits).
  Then you will be asked if to reply the message. "y" replies it
  and should be used normally. "e" replies and gets back to waiting
  mode again. Abort waiting is possible with CTRL-C.
* "GETMSG portname" gives the process-internal port the given name.
  Then it behaves as described above.
* See PUTMSG for examples.
============================================================================
KILL device|taskdescription

* KILL lets the handler of a device (name ending in ":") end itself.
  It seems not to work with most handlers. Works with CrossDOS
* It can remove tasks too, but this will likely crash, because it is
  NOT SYSTEMCONFORM ! See BREAK for taskdescription.

eg.     kill PC0:
        kill Exchange
============================================================================
LOCATE  [-C] [bptr|name] [READ|WRITE]

* "LOCATE lockadress" (lockadress is a BPTR) shows information about
  that lock structure. fl_Access must be -1 (write) or -2 (read).
* "LOCATE filename_or_dirname READ" gets an ACCESS_READ lock structure on
  that file/dir.
* "LOCATE filename_or_dirname WRITE" gets an ACCESS_WRITE lock structure
  (exclusive lock) on that file/dir. This cannot be shown correctly,
  otherwise it would not be exclusive.
* "LOCATE -C lockadress" unlocks (removes) the lock structure (BPTR !).
* "LOCATE" shows all locks that are in system. Since OS2.0 this cannot
  show correctly all locks on RAM: because it is some kind of hack.

eg.     locate &21f45c        {shows lock on adress $21f45c}
        locate $9f5b7         {shows lock with BPTR $9f5b7}
        locate -c $9f5b7      {removes this lock}
        locate ram:rdit read  {tries to read-lock ram:rdit}
        locate c:mount write  {tries to write-lock c:mount}
        locate                (shows all locks in system}
============================================================================
M [start_address] [end_address]

* M is a memory contents dumping command.
* Typing M with a start and end address will display the hex and
  ASCII contents of those bytes in the memory locations specified.
* Typing M with only a start address will display 160 bytes
  starting at the location specified.
* Typing M with no parameters will display 160 bytes starting
  from the current memory location.
* The current memory location is always one location higher than
  the last location shown by a prior M command.

eg.   m $70000 $77fff
      m $fc0000
      m
============================================================================
PUTMSG port_description [number1|string1] [number2|string2] ...

* PUTMSG is useful for testing programms which wait for a message,
  or to reactivate a task that waits for a message which will never
  arrive. PUTMSG sends a message to the given messageport.
* port_description can be given in 5 (!) ways:
  - Name of the messageport
  - Adress of the messageport
  - 3 ways of a task_description, see BREAK. This MUST be a Process
    because the process-internal messageport will be used.
* number|string is a longword number or a string. If it is a number,
  it will just be added to the message. If it is a string, a
  adress pointing to this string will be added to the message.
  If number1|string1 was a point (.), the message will be initialized
  as an DOS-Packet.
* After sending the message PUTMSG will wait for the reply and show
  that reply like GETMSG. Abort waiting with CTRL-C.
WARNING: Your machine might CRASH if you send a message to a
  (Process-internal) port that is not waiting for this message.
NOTE: PUTMSG without arguments makes a DisplayBeep (even without a
  window) and outputs the internal register value of A5.

eg.     putmsg testtask $21fd68 12
        putmsg testport "Hello World!"

  If you have 2 ZShells, execute in the one with CLI-number 1
  "getmsg". Activate the other shell and type
        putmsg 1 "like some chatting ?"
  The ZShell no. 1 should display that and prompt "reply ?". Answer
  "y" and the message goes back again.
  Now try "getmsg wurgutz" at one ZShell and "putmsg wurgutz $abcd"
  on the other. Do not forget to reply.

* You can use PUTMSG to use the AREXX interface of a programm. This
  works with some programms even with OS1.3- and no AREXX-Package.
eg.     putmsg showdvi 0 0 0 0 0 "tofront" {gets ShowDVI to front}
  Instead of the first 0 you sometimes must write the adress of
  this task. If available replace the second 0 with a pointer to
  the rexxsyslib.library. The third 0 is called rm_Action. I do not
  know what it is for. The fourth and fifth are results, only
  interesting in the reply.
eg.     putmsg showdvi 0 0 0 0 0 "loadnew tex.dvi"

* Specify a point as first number if you want to send a DOS-Packet.
eg.     putmsg DF0 . 0 1023 0 0 -1     {same as LOCK DF0: ON}
  If you get $FFFFFFFF as 4th longword, it was successful.
 (with OS1.3- you need to use FileSystem instead of DF0)
============================================================================
SHOW D|I|L|M|P|R|S|T|V

* Shows some information about important exec-lists:
  - Devices
  - Interrupts
  - Libraries
  - Memory
  - Ports (MessagePorts)
  - Resources
  - Semaphores
  - Tasks (and Processes)
  - Vectors for reset-resident programs
  Use the first character of one of them as argument.
* The output means:
  - Adress: hexadecimal start adress of the structure
  - Pri   : Priority, often unused
  - Ver   : Number of version  (only with D,L,R)
  - Rev   : Number of revision (only with D,L,R)
  - Name  : Name
  - State : Task state (only with T)
  - SignWait : Signals, a waiting task waits for (only with T)
  - PT    : Pr means Process, Ta means Task, Tm means Task with
            Messageport like Process     (only with T)
* If displaying the tasklist, the CLI-number (-> CLI ?:) and the
  loaded command will be shown at processes with cli-structure.
  ">" stands for output-redirected, "<" for input-redirected.
  "Bg-CLI" means background CLI.
* SHOW V displays some important execbase pointers, which give a
  good indication of whether a virus is present in your system.
  WarmCapture, CoolCapture, ColdCapture, KickTagPtr, KickMemPtr,
  and KickCheckSum are displayed. If any of these are are NOT
  zero, then either a virus, RAD, or virus protector or some
  other program that takes control of your machine when you
  reset, is present.

eg.     show d          {have a look at the device-list}
        show Devices    {same as above}
        show t          {This is REAL MULTITASKING ! :) }
============================================================================
STRINGS sourcefile [count]

* STRINGS displays all valid ASCII strings in a file which have a
  length greater than or equal to the count. If no count is given,
  a default of 10 characters is used.
* This command is very useful for finding out which libraries a
  program uses.

eg.     strings c:zshell 20
        strings c:mount
============================================================================
TASKPRI priority [task_description]

* TASKPRI sets the priority of a task, it can be displayed using
  "SHOW T". The priority must be between -127 and 128 and should
  be within -50 and 20 to avoid system-hangups. Standard is 0 .
* task_description is same as described at BREAK.
* With one argument TASKPRI sets the priority of this task.
* If task_description is given, TASKPRI sets the priority of the
  given task.
NOTE: I did not like to call this command CHANGETASKPRI, because
      this name is really too long.

eg.     taskpri 2       {This task will be preferred}
        taskpri -1 3    {affects CLI no. 3}
        taskpri 4 Workbench
============================================================================

############################################################################

============================================================================

############################################################################

============================================================================
Changes

UP TO V1.3:See the source code of the ZShell V1.3 release
           (for example on FISH disk 537).
           Author: Paul Hayter
           Source: 103 KByte, Executable: 13 KByte, Doc: 32 KByte.

V2.0:There were so many changes, I think there is no sense in listing
     them all here, because it may be longer than this document. So just
     read this document or the source code.
     All changes since V1.3 made by Martin Gierich. Released 14.10.94.
     Source: 180 KByte, Executable: 25 KByte, Doc: 72 KByte.

V2.1  11.12.94:
    * IMPORTANT FOR THOSE WHO USED ZSHELL V2.0: Do not start ZShell V2.1 *
    * if ZShell V2.0 is resident. This will crash your machine !         *
    * Do not use ZSH V2.0 with ZShell V2.1 and vice versa.               *
  - Added a review buffer to see that again what scrolled out of the
    window. A scrollbar will probably added in future.
  - Changed default CTRL-keys; added 2 new CTRL-keys (see HISTORY).
  - Changed usage of MORE (you can still use the cursor keys).
  - DIR now hides all these files that Filenamecompletion ignores.
  - Some bugs found with mungwall and scratch are fixed.

V2.2  03.01.95:
  - Fixed a REALLY NASTY BUG that trashed taskswitching when closing ZShell.
  - AmigaGuide-Documentation added !
  - RUN-Command added !
  - NEWCLI has a new argument template.
  - CTRL-J = Shift-RETURN puts the command line in History
    buffer without executing.
  - PROMPT now knows the args %s and %c :-) . Default Prompt
    changed to "%s> ".
  - Better building of the CLI-Interface when starting from WB.
  - Now the Pseudo-Assign PROGDIR: is provided (OS2.0+ only).
  - LIST -Q -R also works; DIR can also list recursive.
  - ECHO Hi There ! will now do the same as ECHO "Hi There !" .
  - Improved options when starting from CLI.

V2.3  10.02.95:
    This time there are some real new features. Because now I have my
    OS3.1 Autodocs and Includes, I have added several features that can
    only be used with OS2.0+. There will be done version-checkings before
    using OS2.0+ specific stuff, so no need to be afraid of crashes.
  - New Commands: MAKEICON, MAKELINK, FLAGS and MOVE.
  - DELETE, COPY, MOVE, PROTECT and JOIN are fully rewritten !
    They now all use the directory-lister (for LIST and DIR)
    and therefore all support wildcards and recursive processing !
  - PATH-Command is now AmigaDOS compatible.
    Paths from Workbench are duplicated on starting from Workbench.
  - Support of Hardlinks and Softlinks by MAKELINK, LIST and DIR.
  - ASSIGN supports ADD, REMOVE, PATH and DEFER.
  - Redirection improved: Can also be redirected to MORE.
  - Can be iconified to an ApplicationIcon (see FLAGS).
  - Erroroutput is done by DOS.
  - DELETE DEVICE formats a disk quick,
  - DELETE FORCE ignores delete-protection-bits.
  - Filenamecompletion can show all matching files.
  - MORE supports "more keys" and checks windowsize.
  - ALIAS can work without surrounding quotes; now you
    have to remove \ before " ,sorry for any incompatibilities.
  - CHECK is moved to FLAGS, VEC is moved to SHOW V.
  - RESET removed: It was a hack ! RECOPY removed: Has anybody needed it ?
  - First line in Command History is the last changed line.
  - You can use ^* instead of ^$9b with ECHO and PROMPT.
  - Really faaaast searching in MORE, SEARCH and HELP.
  - Bugfix and new options when starting from CLI.
  - New Tooltypes for starting from Workbench.
  - HELP only searches the current dir and S: for the manual.

  Now there is not much of the original V1.3 release left, because most
  of the old parts are totally rewritten and size has more than doubled !

V2.4  28.02.95:
    Important bugfixes made !
  - Application-Window allows dropping Workbench-Icons into ZShell-Window; OS2.0+
  - Check-Flag checks writes to low memory
  - SHOW task shows redirection/background
  - DIE task removes task
  - COPY uses dots as progress indicator
  - If an error during starting occurs, there will be an errormessage
  - Sets Wildstar-Flag in System, so you can use "*" instead of "#?"
    with all commands; OS2.0+
  - Hide-Flag added.
  - Lots of bugfixes

V2.5  11.04.95:
  - Localized most messages using the catalog of AmigaDOS, so no
    translating required (and I do not have to look for translators :-) ; OS2.1+
  - Pressing CTRL-F a filerequester pops up; OS2.0+
  - Possible to open own Public Screen on starting; OS2.0+
  - EXECUTE uses AmigaDOS Shell for executing scripts
    and therefore no longer causes compatibility problems. To execute
    ZShell-scripts: set S-protection flag and use it like a command.
  - Correct inserting of strings when pressing function-keys or dropping
    an Icon on Window/AppIcon
  - Removed C: as default path. This was a stupid idea
    I got from the AmigaDOS Shell. It is better to have C: as first path.
  - You can use textfiles/Amigaguides with E-flag set like a command.
    It will then be displayed using amigaguide.library. With OS3.0+
    this even works on everything supported by your datatypes (like pics)
  - Problems with foreign characters hopefully fixed
  - NEWCLI and RUN now copy stacksize, appiconname and windowname
  - Bugfixes: ASSIGN, DIR/LIST, DELETE DEVICE
  - ToolType ICONIFY fixed. It has NEVER worked !
  - Starting ZShell chapter improved
  Source: 217 KByte, Executable: 31 KByte, Guide: 104 KByte.

V2.6  02.06.95 (was not on Aminet):
  - Commands changed:
    HTYPE filename [offset]
    LOCATE [-C] [bptr|name] [READ|WRITE]
    CONFIG CTRLKEYS|MOREKEYS|DOT|HIDE|COLOUR|COPYSIZE|FNCSIZE
  - New Command: SPLIT source dest length [offset]
  - Filename completion now reads directory to
    memory to decrease access time. It is now fine to use on floppy disks,
    too. By pressing TAB multiple times you can cycle through the matches.
  - No more problems to delete the last used directory, because "dir back"
    (a single point as command) uses a string instead of a lock.
  - Showing files using Amigaguide does not check for the E-protection-
    flag anymore
  - Use ESC or Q key to quit MORE
  - String comparison in Filename completion and DIR/LIST is now localized
  - OS2.0+: AmigaOS wildcards are used (they are localized). They are a
    bit different. To get back the internal ones use: FLAGS WILD OFF
  - Default prompt is now "%p> " again (something has to be changed :-)
  - New Tooltype: HELPMAN , new CLI option: -h
  - Options can be overridden by surrounding them with quotes
  - Bug fixes: DEL key, FLAG CHECK -> locks, scripts ending in LF


V2.7 14.08.95:
  - Support of anonymous pipes. You can choose between
    real and pseudo pipes using FLAGS PIPE.
    Multiple pipes and aliases are also supported.
    All internal commands can be left to "|".
  - Internal commands that can take data from standard input (stdin)
    (can be right to "|" only when using pseudo pipes):
    MORE, TYPE, HTYPE, STRINGS, SEARCH, EXECUTE ZSHELL
  - EXECUTE ZSHELL scriptname executes a ZShell script
  - RUN command outputs to current window,
    RUN >filename command outputs to filename
  - Redirection >W opens a window
  - MORE: Key N searches next occurence of searchstring
  - PROTECT: You can use = similar to + or -, reduced disk access
  - FLAGS CHECK ON does not count locks anymore, use LOCATE instead
  - MAKELINK: HARD is default, SOFT must be specified explicitely
  - DELETE dirname ALL deletes contents of the directory, then tries to
    remove the directory
  - CTRL-P flushes FNC-buffer (useful on CrossDOS disks)
  - Default prompt is now "%s> " again
  - EVAL uses now different symbols
 Bugfixes (Thanks to Christian and Timothy who reported most of them):
  - Review-buffer had to be less than 64K
  - Stderr provided (GNU-C likes it :-)
  - Line ending in "\" crashed
  - NEWCLI -Wfilename crashed
  - Versionstring fixed
  - If arguments are specified, command will not be interpreted as
    directory or textfile
  - COPY: If a disk full occurs, the incomplete file will be removed
  - COPY,MOVE,JOIN,SPLIT: Current dir bug fixed
  - Spaces before aliases did not work
  - Double redirections catched
  - ALIAS stack overflow catched
  - Bug with directorynames ending in "/" fixed
  - Source rearranged to go around 32K limit
  - Probably added some brand new nasty bugs and left some ugly old bugs :)
  - And what is best: Much improved versionnumber !  ;-)
 All changes since V1.3 made by Martin Gierich.
============================================================================
Known Problems

Here are listed known bugs and odd behaviours.
* CrossDOS
  With MessyDOS being one big bug, the MessyDOS filesystem is part of
  a bug. :-) This means not all things AmigaDOS supports, is supported
  by CrossDOS, too. Especially Protection bits are different,
  and Filenotes are not supported. Not to mention the 8+3 filename limit.

  A further problem is the missing date-of-last-change of the disk.
  Without this FNC cannot determine whether something on the disk has
  been changed and even not whether the whole disk has been changed.
  So you have to update FNC manually by pressing CTRL-P after a change.

* MORE
  If you are on the last page, scroll up some lines and scroll down some
  lines again, you will notice a weird behaviour. This is hard to fix.

* ALIAS
  alias list dir ; alias dir list
  does not exchange "dir" and "list", because nested aliases are allowed.
  This is not a bug, this is a feature !

* Review-Buffer
  Some commands, especially OS2.0+ only, use other ways to output text
  than dos.library's Write(). As a result this output will not appear
  in the review-buffer. Probably this will be fixed in future.

* DELETE
  If you want to delete a link, you have to describe it with wild cards,
  otherwise the original file will be deleted, because the system
  resolves links automatically. I do not have an idea how to work
  around it.

* MOVE
  You have to make sure that the destination directory is not moved to
  itself like in "move * temp/". Maybe there are more strange behaviours
  in the MORE command, I am waiting for bug-reports. :-)

* DIR, LIST, COPY, DELETE etc.
  Directories nested very much, about more than 50 levels, and using
  recursive option to scan them, cause ZShell to crash. Still looking
  for the bug.

* If you type a command and press Return while an other command (like DIR)
  outputs on the window, it will appear after the next prompt, but it
  will just be put in the history buffer without executing it. Sorry,
  there is no way to fix this, because the Return above is treated as
  Shift-Return by the system. Two solutions:
  1.) Press cursor up (last line in history) and then press Return
  2.) Use "config ctrlkeys WQSEIX[TYHKJLRVFP". With this Shift-Return
      will be the same as Return and CTRL-K will be what Shift-Return
      was before.

* Filename completion
  If you have a filename with a space in it, you have to make sure you
  type the quotes around it by yourself, this can hardly be done
  automatically.

* PATH
  If you have multiple assigns (ASSIGN ADD) to your C: (or another)
  directory, PATH will accept only the first one. Add the other
  directories to the path by using "path directoryname".
============================================================================
Possibilities for Future Improvements

Planned for next version:
New documentation written by Timothy.
(Hi Timothy, mailing you does not work, please try to mail me.)

Other ideas/suggestions:
* Quick directory changes by using a database
* Full XPK-support
* Scrollbar for review-buffer (this will be difficult)
* Add more commands to the directory-lister (like makeicon,search)
* Make KILL a real killer (windows, screens)
* MAKEDIR can create nested dirs: If RAM: is empty "makedir ram:a/b/c"
  would create directory c in b in a in RAM: .
* HEX option for MORE.
* Applly configurable menues to the window
* More options for the LIST command (especially LFORMAT).
* Remove PUTMSG and GETMSG
* COMPARE or DIFF command

Less probable:
* COPY asks to remove incomplete destination files.
* RENAME command with wildcard support: "rename *.asm *.s" would rename
  all files ending in .asm to the same name ending in .s !
* Make it a commodity with hotkey.
* Improve internal script file execution, like passing arguments,
  allow subroutine scripts and commands like FOR.
* Include MOUNT/INSTALL command.
* Faster scrolling (jump scroll/1 bitplane scroll)
* Patch for 68000-Processors to be as fast as 68060/50MHz-Processors ;-)
* Write a stripped-down version for MessyDOS; after starting this would say:
  This is ZShell V2.x *** Fatal error: no multitasking system !  ;-)

If you want to see these or other improvements made, please write to me.
If you do not, please write to me, too :-)

Note that there is a (about) 32K limit of the executable, because I only
use relative addressing (like in small code model). So suggestions what
to remove are also welcome.


I thought about making a separate version for OS2.0+:

Command-line-editing and review stuff could be done best (most powerful)
within a console-handler; there are already several available (as I know,
the only one that is Freeware is KingCon), so I do not want to write
another one. The disadvantages of these I have seen is that you need to
change alot between mouse and keyboard and they are somehow slow on my
system (and do not work on OS1.3- systems) and memory-hungry.

Except for Command-line-editing and review, the inbuild commands are a
main advantage of ZShell. These commands could be moved to one executable
file; if this file was executed, it would create all inbuild commands
as resident commands that could be used by the normal Shell.
(This would be somehow like the MessyDOS COMMAND.COM file.)
So if you used this file and a separate console-handler, you could work
comfortably with the normal Shell.

If there are enough people asking for that, I will think about writing
such a "multi-command-file", but I will not write another console-handler.

And, last but not least, I have to invest lots of time in my studies and
I do not want to hang around all remaining time at the keyboard !
============================================================================
Distribution

Following files belong to this document:
 1) ZShell           The main executable
 2) ZSH              The small starter
 3) ZShell.doc       The documentation (and online help manual)
 4) ZShell.guide     The AmigaGuide documentation
 5) ReadMe           Short description
 6) ZStart           An example startup script (can be put in S: )
 7) ZShell.s         Source code of the main executable
 8) ZSH.s            Source code of the small starter
 9) Csh-Aliases      Some aliases to make it a bit similar to UNICS csh
 and some icons.
============================================================================
Copyright

COPYRIGHT
(taken directly from the V1.3 distribution from Paul Hayter)

 ZSHELL IS FREELY DISTRIBUTABLE. YOU CAN DISTRIBUTE THIS AS LONG AS
 THIS DOC FILE REMAINS WITH THE EXECUTABLE, AND THAT NO CHARGE IS MADE FOR
 THEM (APART FROM A NOMINAL COPYING CHARGE). IF YOU FEEL LIKE SENDING
 ME SOMETHING FOR THIS PROGRAM, SEND ME A POSTCARD!, A P.D. DISK, A
 PROGRAM YOU'VE BEEN WORKING ON ,BUT DON'T SEND ME ANY MONEY (WELL, IF
 YOU REALLY, REALLY WANT TO, I GUESS I COULD PUT UP WITH IT).

Note from Martin:

 This is an update to Version 1.3 on the Fish Library Disk 537 from
 Paul Hayter. I (Martin) tried to ask him for permission to release
 this, but he has not answered. Because the copyright notice is left
 unchanged and the original executable with documentation is included,
 I do not think that I am doing something nasty.
 (In the original distribution there was the source code included
 and there is nothing stated to distribute it only unmodified.)

 To make things easier I accept the same copyright notice for the parts
 I have written. They are marked in the source with V2.x (well, mostly).
 I estimate that about 70% of the source, executable and the documentation
 is from me.

 I would like to get your comment on ZShell to see if anybody is
 using it and what can be improved.
============================================================================
Disclaimer

DISCLAIMER

USE THE FILES OF THIS PACKAGE ON YOUR OWN RISK !
The authors are in no way responsible for what you are doing with it
or what it does to you or your soft- and hardware.

Amiga, AmigaDOS, AmigaGuide, Workbench and Kickstart were registered
trademarks of Commodore-Amiga Inc and now probably are of ESCOM AG.
MessyDOS and UNICS are not really trademarks (as I know)  :-)
============================================================================
Credits

CREDITS FROM PAUL

 Many thanks to Wayne for his invaluable help in doing the history
 and command line editing parts of ZShell. Also, thanks to
 Tim Strachan who asked for the history stuff.

 ZShell was entirely written using Wayned by Wayne Hayter (various
 versions). And was assembled with A68K V2.61 by Charlie Gibbs. And
 linked with Blink V6.7 by the Software Distillery.

CREDITS FROM MARTIN

 Many thanks go to:

 * The administrators of Aminet for their great work
 * Samu Nuojua for his great Freeware assembler SNMA
   ZShell V2.7 was assembled with V1.99: SNMA ZShell.S EXEOBJ OPTLEVEL 5
 * Ralph Babel for the System0 code (see source)
 * Martin Mares for some fine assembler programs
 * Frank for using ZShell (I persuaded him :-)
 (V2.0)
 * Laura Mahoney for trying to send me a postcard and lots of mail
 * Igor Srdanovic
 * Willem MC Hogeweg
 (V2.1)
 * Nico Max
 * Max Stouugard
 * Alexandros Loghis for good ideas
 (V2.2)
 * Christian Steigies for sending me postcards, for really long mails,
   for lots of shocking bugreports :) and for betatesting
 * Oliver Hofmann
 * Holger Jakob
 * Hans Kruse
 (V2.3)
 * Nobody !
 (V2.4)
 * Aristotelis Grammatikakis
 * Jonathan Marsh
 * Dominique Niethammer
 * Fredrik Solenberg
 * Teonanacatl
 * Chris
 * Fred Brooker for the music disk
 * David Klinect
 * Brian Myers
 (V2.5)
 * Timothy Cochran for rewriting the documentation (not finished)
 * Mark Dowe
 * Marek Petkov
 * Matthew Estela
 * Christian Hessenbruch
============================================================================
Authors

Please send any correspondence and/or bug reports referring V1.3
to me at the address below:-

      Paul Hayter
      PO Box 331
      Ballina
      2478
      AUSTRALIA

Please send correspondence, bug reports, comments, suggestions
for future improvements etc. referring V2.x to this adress:

      Martin Gierich
      Narzissenweg 7
      76297 Stutensee
      GERMANY

  (I would really like to get a picture postcard from you, even if
  you just wrote a "Hello" on it !)

  If you have EMAIL access, it would be nice if you send me one
  at one of these adresses:

           [e-mail]           (Internet)
   or to   [e-mail]   (Internet)
   or to   [e-mail]                (Bitnet)

  I will try to reply EVERY EMail I get !

  Please tell me your system-configuration, at least your Kickstart-
  Version, so that I see which kind of systems should be most supported
  in future versions. My system is an A500 with 200 MB Harddisk, 3 MB RAM,
  Kickstart 2.04 and Workbench 2.1 and a VGA-Monitor with Fickerfixer.
  Note that large parts of ZShell were developped under Kickstart 1.3 !
  (Ah yes, and I have such a Vortex ATONCE AT-Emulator; the fastest thing
  it can do is to hang itself up, and they do not make any updates !)

      /\/\            o o
     / __ \ artin      <
    (_/  \_)         `---'
============================================================================