Frozen Fish 1: Amiga/FrozenFish-Apr94.iso/bbs/alib/d5xx/d504/polysilicon.lha/PolySiliCon/SiliCon.DOC

Text File | 1991-06-27 | 52KB | 1,074 lines

                         Sili(CON:) User Manual
                         ======================


                    -- Copyright 1991 Pete Goodeve --






Concept
=======

In recent years there has been a pronounced trend toward the "Graphic User
Interface" (GUI).  In fact at times the trend has seemed more like a
headlong rush.  Despite this, experienced users seem likely to stick to the
Command Line form of interaction for a lot of their work.  This is partly a
simple reluctance to change, probably, but in many ways a command language
is plain more flexible and convenient.  How often do you give a person
instructions solely by pointing and clicking your fingers?  Or by showing
them pre-drawn pictures?

What would seem to be needed is an approach that combines the convenience
of point-and-click with the flexibility of text commands. This is exactly
the intent of Sili(CON:).   Commands, once typed in, remain available for
recall and re-execution by mouse click, and one common window acts as a
convenient central control point for all the Shell processes that you have
running (hence "Poly" Sili(CON:)).  A Shell under Sili(CON:)'s control, by
the way, is (normally) a standard AmigaDOS Shell, so all the usual commands
and facilities are available.

In typical usage, you find that you are entering the same -- or minor
variations of the same -- commands repeatedly, sometimes in the same cyclic
order, sometimes not.  With the AmigaDOS Shell, you can step back through
the history to recall previous commands, but this becomes tedious
especially when the command is more than a few lines back. Sili(CON:)
provides a VISIBLE History list in its window (with a scrollbar): recalling
a wanted line is just a matter of clicking on it with the mouse; a double
click re-executes it directly.  A single click brings the line back into
the editing gadget for possible modification; this area is an enhanced
String Gadget with all the standard Shell editing options (ctrl-U and
ctrl-K etc.) plus a few extras like cursor-to-next-space.

If you use a particular set of commands repeatedly over a number of
sessions, you can store them in a file that can be copied straight into the
history list (at startup or any time later) ready for immediate selection.

Another important Sili(CON:) policy is to separate the Command Area from
the Display windows for each process.  You can have as many Shell processes
as you like (within reason!) connected to Sili(CON:) channels, and they
all receive their commands from the single Sili(CON:) window.  When first
entered, a command is directed to the channel currently selected as active;
any re-invocation of that line goes automatically to the same channel
(whatever the selcted default at that time) unless specifically redirected.
Both the command and any resulting program output are of course displayed
in the associated Shell window as usual.

One notable consequence of this scheme is that the execution of programs
doesn't interfere with the entry of commands.  Not only can you type in the
command text at any time, however many programs are executing, but you can
transmit it to its Shell.  It will be queued to be executed when that Shell
finishes all the jobs preceding it.

As well as letting you use the mouse to save typing, Sili(CON:) conversely
often lets you keep your hands on the keyboard where otherwise you would
need to use the mouse: switching between shells is a matter of a single
keystroke -- no need to move your hand to the mouse and click in that
window.  Of course you have menu selection of the active shell, too, if
that happens to be more convenient.

With the full package (Licensed Shareware -- see the end of this manual)
you can actually connect ANY program that accepts text lines as input to
Sili(CON:).  This could be an ARexx script, for instance, set up to read an
`IP:' device channel. (Sili(CON:) doesn't have an ARexx port of its own;
this approach provides all the convenience of such a port without any extra
overhead.)

Sili(CON:)'s history list can be manipulated in ways that are not common in
such mechanisms.  For one thing, you can delete unwanted items, so the
visible area doesn't get cluttered with mistyped commands and so on.  You
can also gather all the lines associated with one channel together at the
front of the list, or just wipe them all to start afresh on that channel.
Up and down arrows also operate to move you through the history as you
would expect, of course.  All functions (except a couple of "critical"
ones, like `QUIT') can be performed from the keyboard rather than the mouse
if it is more convenient at that point.

The final important underpinning of Sili(CON:) is its modularity, based on
the ppIPC communication mechanism.  Components are kept small by doing only
what they need to, communicating with other components for their distinct
specialities.  Sili(CON:) itself, for instance, accepts no command line
options for setting window configuration and so on.  Instead there is a
module `SiliConfig' (in the Licensed Shareware package only) that accepts
and parses command lines -- or configuration files -- and sends compact
IPCMessages to Sili(CON:) to implement the requests.  The ppIPC interface
is fully documented (in the printed Licensed documentation only), so that
others can write their own utilities to work with this system.






Requirements and Components
===========================

Sili(CON:) will run on any Amiga with AmigaDOS 1.3 or 2.0.  (It may also
behave properly under 1.2, but this has not been checked.)

Some software components other than the SiliCon program itself are needed
for the system to work; they are all included with this package, and the
easiest way to install them is with the automatic installation program
also included. The InterProcess Communications library `ppipc.library' must
be available in LIBS: and the IPC pipe device `IP:' (`IP-Handler') must be
installed in L: and mounted; this means too, of course that this must have
an entry in DEVS:MountList.  Both the above are general purpose modules --
not restricted to functioning with Sili(CON:).

Sili(CON:) itself has two essential components: the `SiliCon' program that
provides the main Control and History window, and `InShell', which links
this to the Shell processes that you want to control.  In addition, you
will want some scripts in your path (usually in the `S:' directory) for
convenient opening of new Shell windows and so on.  Basic ones are supplied
in this package, but you may want to tailor them or create your own.

With the Licensed Shareware package (obtained by sending in the requested
contribution -- see the end of this manual) you get three more utility
programs: SiliConfig, SiliDump, and SiLink.

SiliConfig lets you configure the window and history under program control.

SiliDump creates a configuration file from the current state and contents
of the window -- and also provides a mechanism for "circulating" individual
command lines from older parts of the history to the front.

SiLink allows you to make connections to processes other than Shell
windows (and has some other subsidiary convenience functions).  Any program
that accepts lines of text as input can be connected to Sili(CON:) -- via
an `IP:' channel (or even a suitable direct IPCPort) -- provided that
Sili(CON:) is instructed to open that channel.  InShell does this
automatically for itself, of course, but SiLink is the command-line-driven
equivalent for other occasions.






Compatibility
=============

Sili(CON:) was written to function with the standard AmigaDOS Shell and
CLI. It has not been tested with other shells, but if they use standard
Console (not `RAW:') Input for their commands it will probably work with
them also. (I would be interested in any experiences in this area.)

It should be compatible with any program that runs under the CLI or Shell.
If a program itself requires standard console input, this can come from
either Sili(CON:) or the Shell window it is running in (by redirection, as
explained in `Keyboard Input to Programs').  In fact you can use a Shell
window's own (Console) history, separate from Sili(CON:)'s, for program
input, if you wish.  If a program takes raw keystrokes as input (`more' for
example) it must come from the Shell window rather than Sili(CON:).

Many -- probably most -- utilities work well with Sili(CON:).  No real
incompatibilities have yet been found.  If you have any problems please
let me know.





System Installation
===================

For most people, the most convenient way of installing the system will be
simply to use the supplied `Install SiliCon' icon.  Double-clicking on this
initiates a complete installation sequence, with your permission being
asked each time before any change is made to your disk.  The following
paragraphs detail the steps involved, so that you can see what the
installation program is doing, or so that you can do the installation
manually if you prefer.

One option in the automatic sequence is to do a trial installation.  This
makes NO changes to your disk, loading everything it needs from the
installation directory, and putting pieces that may be needed later into a
RAM: directory.  To try it this way, just click `Yes' in the first
requester presented to you; in a few moments the Sili(CON:) window and an
attached shell should appear; you can use `NewSili' to attach more shells.
This is a fully functional copy of the program, and you can try out all its
features.  To perform a full install instead, just click on the `Install'
gadget of the requester, rather than `Yes'.

The full automatic installation sequence assumes that your environment is
fairly standard.  DOS commands should be the 1.3 or 2.0 standard ones and
have standard names, so that the script can use them.  There must be
sufficient room in your system directories, particularly in the C:
directory, to hold the required additions -- a total of about 30K is needed
for the Freely Distributable package, 20K more for the licensed extras.
See the previous Requirements and Components section (and below) for
details of the pieces to be installed.

The installation sequence begins at the `foundation level' and works up.
First, `ppipc.library' is placed in `LIBS:', then `IP-handler' is copied to
`L:'.  Next, the executable modules are copied, and finally changes are
(carefully!) made to `DEVS:MountList' and `S:Startup-Sequence' so that
Sili(CON:) is started automatically when the system starts.  You needn't
permit the last step (or in fact any of the others) if you don't want it.

The installation process is managed by an Xicon script.  The "Install
SiliCon" icon is actually attached to a directory of that name, rather than
directly to a script; the main script is actually `.script' within that
directory; it in turn uses sub-scripts within the `.work_scripts'
subdirectory to do the pieces of the job.  All the modules that will be
copied to your disk during installation are also in the `Install SiliCon'
directory, except that the User scripts are in an `S' subdirectory of this
(and the licensed modules if present are in their own subdirectory too).


ppipc.library:

This module must be installed in the `LIBS:' directory for normal use of
Sili(CON:). (For the trial installation, a judicious temporary switching of
assignments avoids this.)  The original released version is still the
current one, so that if you already have it installed you don't have to do
it again.


IP-Handler:

The `IP:' device is used to connect to shell processes, so this handler
must be available in `L:' (and must be mounted -- see later).  The original
release has a bug that could occasionally cause problems with Sili(CON:)
(though not for other uses), so it should be replaced with this version.
There are no differences in the two versions aside from the bug fix.
If a version exists in L:, the program will show you the comparative
directory entries, so you can decide whether you need to replace it.
If for some reason there is absolutely no room in `L:', you could put the
handler somewhere else, and modify the MountList entry yourself to match.


SiliCon:

This is the main program that manages the user interface and history
window.  You probably will want it in `C:' -- which is where the
installation sequence will put it -- but you can place it anywhere that it
is convenient for you to execute it from. (It will probably only be
executed automatically by a suitable command in the startup sequence.)


InShell:

This is executed to make the connection between a shell and Sili(CON:).
It also should normally be in `C:', but can be anywhere on the standard
path.  Note that if you wish, this program may be made resident; the
installation sequence doesn't add any automatic instruction to do this,
however.


Scripts:

There are two scripts that will be put in the `S:' directory -- which, by
the way, should be in your path, as is usually the case since DOS 1.3 was
introduced.  These are `NewSili' and `Sili-Startup'.  If for some reason
`S:' is not normally in your path, you can put NewSili in `C:' or anywhere
else on the path.  Sili-Startup should, however, always be in `S:' -- it is
always referred to directly, so it doesn't need to be in the path.  These
two scripts are in the `S' subdirectory of the main installation directory.


Extended modules:

If you have the licensed package, there are three more programs that the
installation sequence will copy to `C:' -- `SiliConfig', `SiliDump', and
`SiLink'.  These are simple utility programs that could be put anywhere
else accessible that you prefer.


MountList:

The `IP:' Handler must be mounted before Sili(CON:) is used, and so it must
have an entry in `DEVS:MountList'.  The installation program looks for an
appropriate entry there, and if it doesn't find one asks permission to
insert it.  If allowed to it simply appends the entry to the current list.
By the way, it is careful to do the modification on a copy!  The original
MountList is then renamed as a backup BEFORE the copy is put in its place.
If you prefer to make the change yourself, the necessary lines are in
`IP_MountList' in the installation directory.


Startup-Sequence:

There are two separate additions that the program will make to
`S:Startup-Sequence' if so allowed.  First it inserts a `mount IP:' command
to ensure that this device is available, and then adds automatic startup of
Sili(CON:) and one connected shell before the `endcli'.  It first checks to
see if such lines appear to have already been added, though, so that the
file doesn't get modified twice.

There are some subtleties here that you should be aware of.  A 1.3 system
often has the major part of the startup in `S:StartupII', rather than in
the main sequence, so the program first checks for the existence of this
and for other `mount' commands within it; if it is successful it will offer
to put the new line there also.  If it doesn't find it, or is told not to,
it will then request permission to modify Startup-Sequence itself; it will
put the new line with other mounts if there are any, or otherwise after the
LoadWB line; if it really gets lost it will give up and let you edit the
file yourself.

The automatic startup text will be put immediately before the usual
`endcli'.  Again, if the program can't find this it will pass the job on to
you.  And of course once again all this editing is done on a copy, which
only replaces the original after it is backed up.

If you allow all these steps, the next time you boot your machine,
Sili(CON:) will be started automatically.


startup:

Finally, the program asks if you want to start Sili(CON:) immediately.
If you answer `Yes' it does essentially the same startup that would occur
from the Startup-Sequence (except that the current directory is still the
installation directory).


Custom installation:

If you prefer not to use the automatic sequence, or for some reason you
cannot in your machine, you can find all the pieces referred to above in
the `Install SiliCon' directory, and copy them yourself to the appropriate
places.  You will also have to know how to edit the MountList and Startup
Sequence.  If you wish to do this, or to change anything in the default
installation, please read the relevant sections of this manual first, and
back things up before you change them.






Starting Sili(CON:)
===================

Once you have all components properly installed, as detailed in
`Installation', you need to do two things to begin using the program.
First you need to start the control and history module, and then connect
one or more Shell processes to it.  You will probably want to do both of
these things either automatically from your startup sequence or at least
from a script, but they can be done directly from a Shell window.  For
clarity, this last alternative will be described first.

To start the control module, just give the (CLI or Shell) command:

        silicon

The control/history window will appear.  There is no need to use "RUN",
because SiliCon immediately detaches itself and runs in the background.
The SiliCon window does, however, become the active one, so for the next
step you need to click in the Shell window to reactivate it.  (If you type
commands into the SiliCon window at this point, nothing will happen because
as yet no Shell is connected.)

If you want to connect the AmigaDOS Shell you are working in to SiliCon,
use the command:

        inshell

This runs momentarily to make the connection between the Standard Input
of the Shell and SiliCon and then exits, freeing the Shell for other
commands.  (Do NOT use "RUN" here!)  From this point, the Shell will
get its command input from one of SiliCon's channels; the channel name
assigned by InShell appears in the SiliCon window title bar when the link
is made, to indicate that commands will be directed there (until the
channel is changed).  By the way, once linked, there is no way to break
SiliCon's thrall except by killing the shell (`ENDCLI', or from the SiliCon
`SHUT' menu).  The InShell command is described more fully in its own
section.

If you do not want to link the currently running Shell or CLI to SiliCon
(or if it is already linked and you want to open more channels), you can
start another shell that is immediately linked to SiliCon by using the
supplied shell startup script `Sili-Startup' (normally in the `S:'
directory):

        newshell from s:sili-startup

This script simply executes InShell itself, and sets up some aliases and so
on; edit it to suit your needs.

There is an executable script `NewSili' that conveniently performs the
above command (with a default window specification).  Note that the
supplied Sili-Startup redefines `NewSili' as an alias.  This is faster, but
not as flexible (and of course doesn't work if Sili-Startup wasn't used for
the current shell).  Whichever version is used, `NewSili' becomes the
equivalent of `NewShell' for starting another Shell process that is
controlled from SiliCon.

The most convenient way to start up SiliCon is from the Startup-Sequence
at boot time, launching one or more linked Shells at the same time.  Simply
include whatever versions of the above commands suit your needs immediately
before the terminating EndCli in the S:Startup-Sequence file.  (You CAN
replace the EndCli with an InShell, but it is probably not a good idea, as
this initial window -- under 1.3 at any rate -- is a CLI, not a Shell, so
you won't be getting the features that you would otherwise expect.)  This
is the sort of thing:

        .....
        .....
        SiliCon
        NewShell "NEWCON:0/0/300/200/Sili Shell" from S:Sili-Startup
        endcli >NIL:

Some other things you may also want to do before the endcli.  If you have
the full system you can invoke SiliConfig (not included with the Freely
Distributable version) to dimension the control window and so on, and
install some initial lines in the history for quick access.  You can even,
in fact, copy lines into the history from a file if you only have the basic
FD package, as explained in a later section, but you have fewer options
that way.  Advanced users may even want to link in other utility processes
that are not Shells (ARexx programs perhaps) -- again, the full system is
needed for this.






The Sili(CON:) Window
=====================

Sili(CON:) opens just a single window, with a number of functional areas.
At the bottom there is the Command Entry Line; any characters typed while
the window is active will appear there.  The main area of the window above
that is the History Display, showing the list of commands previously
entered.  On the right is the scrollbar that lets you move directly to the
point of interest in the history if it is off screen.

When first started (and at occasional times later) the title bar just says
`Sili(CON:)', but most of the time it gives information on the channels
currently selected.  See the later section on `Channels' for details.

The window has the usual front/back and sizing gadgets, and of course can
be dragged by its title bar, but there is no `quit' gadget.  A menu item is
used to close Sili(CON:) down.


Activating the Window
=====================

An important feature of Sili(CON:) is that there is a `hot key' combination
that will activate the window immediately, whatever else the Amiga is doing
at the time.  Hold down the LEFT Amiga key and type the return key, and the
control window will be brought to the front of the Workbench screen and
activated.  (Note well that this key combination ALWAYS activates
Sili(CON:), whatever screen is active at the time, but it does NOT bring
the Workbench screen to the front.  You can type `blind' if you wish after
doing this, but it is probably wiser not to!  Note also that there is an
apparent Intuition glitch that very occasionally prevents the window from
coming to the front when activated; if this happens, it WILL come to the
front when the return key is next pressed; if you are worried about
possible accidental execution of a command, use shift-return to prevent
this.)






Using Sili(CON:)
================

Once you have started Sili(CON:) you will normally leave it running
continuously until you shut the machine off -- although you can remove it
with the `QUIT' menu item if you so wish.  Usage is mostly just a matter of
typing commands into its entry line or selecting previous ones from its
history area for re-execution.  Freshly entered commands are transmitted
out the currently selected channel; re-executed ones go to the channel they
were originally associated with, unless you specify otherwise.

In general, the destination of a command is a perfectly standard AmigaDOS
shell, so all the facilities it provides (such as aliases, command
redirection, and directly executable scripts) are available as usual.
The only real difference is that if you want to open a new shell connected
to Sili(CON:) you should use `NewSili' rather than `NewShell' (see below).

A command is actually transmitted when the return key is typed.  Sili(CON:)
normally remains active after transmission, so you can immediately continue
entering further commands.  However, if you execute a command with the
Right-Amiga key held down as you type return, keyboard activity is
transferred to the shell window itself (see below for more details).  This
lets you control output with the space bar, for instance.  If you want to
interact with the program itself in the shell window, rather than through
Sili(CON:), you should redirect its input in the command line.  See
`Keyboard Input to Programs' for details.

You can change the current channel -- to transmit to any of the connected
Shells -- via either menu selection or keyboard.  Other actions you can
select from either menu or keyboard include gathering all the commands
associated with the current channel at the front of the list, wiping all
the commands on that channel from the history, changing a command to a
different channel, or fixing the channel temporarily so that all commands
are directed there, whatever their original destination.  From the menu
only, you can shut down a channel (and close its Shell) when you are done
with it; you can also flush all the shut channels (i.e. remove them from
the menu and discard their command lines) or quit Sili(CON:) entirely --
shutting down all its associated shells as well.  (see `Menu Operations'.)

New Shell processes are created for Sili(CON:) in an analogous fashion to
the AmigaDOS `NewShell' command.  In this case the command is `NewSili'.
This is in fact either a script or an alias and does not have NewShell's
options, but you can easily tailor it to your needs (or create
alternatives).  See the section below on `NewSili'.







Entering commands:
==================

While the Sili(CON:) window is the active one, characters typed at the
keyboard go straight into the Command Entry Line at the bottom of the
window. The return key is used to actually execute the command (or more
precisely transmit it to the shell on the current channel for execution).

A number of special keys and control characters are also active to give you
convenient editing amd other controls:

        left-arrow                  move cursor one character left
        right-arrow                 move cursor one character right
        shift-left-arrow            move cursor to beginning of text
        shift-right-arrow           move cursor to end of text
        ctrl-left-arrow             move cursor left to next space
        ctrl-right-arrow            move cursor right to next space
        ctrl-K                      erase from cursor to end of line
        ctrl-U                      erase from before cursor to start of line
        ctrl-X                      erase whole line
        R.Amiga-Q                   restore initial contents of line
                                       (only on lines from history)
        up and down arrows          move through the history -- see later
                                    (the current edited line is NOT
                                    preserved -- be careful!)

        return                      transmits command for execution
        shift-return                enters command in history only
                                    -- does NOT transmit it
        alt-return                  transmits command, but adds it to
                                    the history as a "floating command"
                                    not associated with any channel
                                    (see the section on `Channels')
        Right_Amiga-return          as return, but pushes the Sili(CON:)
                                    window to the back and activates the
                                    shell window that the command is sent
                                    to.

    Note that the Right_Amiga modifier remains associated with that command
    line: the Sili(CON:) window will be deactivated (and the shell window
    activated) each time that command is reinvoked.

    The above modifiers for the return key may be combined if you wish, and
    will usually do something rational.  Thus:

        shift-alt-return            enters command in history only
                                    as a "floating" one.
        R_Amiga-shift-return        command to history only, and Sili(CON:)
                                    remains active, but the `background'
                                    modifier gets asociated with the
                                    command, and will take effect on future
                                    invocations.

Other special keys, such as menu shortcut commands, are described in their
own sections.







The History List
================

Each new command typed into Sili(CON:) goes into the History as it is
transmitted (or even without transmission, as described under `Entering
Commands').  It can be retrieved from there when needed, for immediate
re-execution or re-editing.  Re-executed commands are NOT added again to
the list, though re-edited ones are.  You can access the history either
through mouse or keyboard.

At the left of each line in the history is a space for a marker that
indicates something about the channel associated with that command. All the
commands that are associated with the `selected' channel -- i.e. the
channel of the currently selected command, or the default channel if there
is no selected command -- show a `bullet within a rectangle' mark.
Commands belonging to the `default' channel, if this is different from the
selected channel, show a `bullet' only.  `Floating' commands, that always
go to the current default channel, will show a rectangle only at all times.
Commands associated with other channels have no marker.

You can select a particular command and bring it back to the entry line
simply by clicking once on it with the mouse left button.  If it is not
visible in the window, you can scroll through the entire history with the
scrollbar on the right of the window.  (Note that this will be a reasonably
smooth scroll if the window is the frontmost one known to Intuition; if it
is not, the scroll flickers rather more.  If this annoys you, click on the
"to-front" gadget, or use the Left_Amiga-return combination.)  A selected
command is highlighted, and remains so as long as it is the selected one.
Only one line may be selected at a time; executing any command -- from the
history or keyed in -- unselects all lines.

If you want to execute the command immediately, rather than bring it back
for editing, double-click on that line in the history area.  (You can't
execute a command by clicking in the entry line area -- you must use the
return key in that case.)

You can step through the history with the up and down arrow keys if you
prefer (while the window is active, of course).  If the step would take you
out of the currently visible area, the text will scroll to compensate.

The list is not immutable as displayed.  In a sense it is not a true
"History" as seen in other situations (the Shell for example), because it
is not an exact and complete record of all the commands in the order they
were given.  For a start, commands executed unchanged from the history are
not re-entered: only new or edited ones go in.  Further, you can delete
unwanted lines from the set; this helps to avoid clutter, and guards you
from choosing a badly entered one accidentally.  To delete a line, first
select it -- by mouse click or with the up/down arrows -- and then type
Right_Amiga-Del.  You can delete a set of adjacent lines backwards through
the list by repeating that key combination an appropriate number of times.

You have other manipulations available to you as well, both from the menu
and by keyboard shortcut command.  You can wipe (delete) all the lines
associated with the current default channel, or gather them at the front of
the list.  See `Menu Operations' for details.

The default maximum number of entries in the history is 50; when that
number is exceeded, the oldest entries are discarded.  Using the SiliConfig
module (from the full package) you can reset this to any desired value.





Channels
========

When you enter a command to Sili(CON:) it is sent out through a "Channel"
to the desired shell (or other) process.  Each connected process has its
own channel, and each channel has its own name and its own item in the
`Channel' menu tagged with that name.  When a new channel is connected
(`opened') it is added at the bottom of the menu list.  It may later be
`shut', in which case its menu item is disabled, and after that may be
completely `flushed', at which point the item is removed from the menu.
(See `Menu Operations'.)

A channel name may be any appropriate string of characters, and is
determined by the connecting process at the time the connection is made.
The program that links a shell to a channel -- `InShell' -- will accept a
command line argument for this if the user provides one; otherwise it
generates a default one of the form `CLI_n', where `n' is the AmigaDOS
CLI-Process number.

At any time, one of the channels is Sili(CON:)'s `Selected Default
Channel'.  There is also a `Current Channel', which is the channel that the
current command will actually be sent out on; for new commands this is just
the default; for a reselected one it is the channel associated with it in
the history.

You select a particular channel to be the default by picking it from the
`Channel' menu, or with one of the shortcut key combinations
`Right_Amiga_1', `Right_Amiga_2',... `Right_Amiga_9'.  These key
combinations correspond IN ORDER to the items in the channel menu, but bear
well in mind that there is no FIXED relation between the items and the
keys, because items may be added and deleted at any time (as channels are
opened and discarded).  However there is little difficulty, as you get
immediate feedback from the titlebar (see below).

It is possible for NO channel to be the current default (when no shells
have yet been linked, when the default channel has been flushed, or when
you deliberately select `NO Channel'); in this case new commands don't get
sent anywhere except into the history, where they become `floating'
commands (see below).

When a channel is shut, its commands don't disappear from the history
unless it is actually flushed as well.  Invoking a command for a shut
channel does nothing at all.  If the same channel is later opened again,
the commands once again become active.  (Note: in the current version,
although a shut channel has its menu item disabled, you can still select it
from the keyboard!  Also, if it was the default channel at the time it
was shut it remains so.  This does no harm, but might confuse you.)

The title bar of the Sili(CON:) window shows both the Current Channel (the
leftmost), and the Selected Default (within brackets).  If there is no
current channel (i.e. there is neither a default nor one from a currently
selected command) it will just show `Sili(CON:)'.  If there is a current
channel but no default, the brackets will be empty.

A marker on the left of each history line indicates whether that line is
associated with the current channel, the default channel, or is floating;
see the section on `History' for details.  This, together with the
titlebar, gives you a convenient way of checking the association of
commands with channels and with each other.  You can see at a glance which
commands will go to the current channel, and which to the default.  By
clicking on a particular line, you immediately see all the other commands
linked to the same channel.

A newly typed command is normally associated with the current default, and
remains associated with it in the history unless later changed with a `Set
to Channel' operation.  The only exceptions to this are if the alt-return
key combination is used to end the command, in which case it is entered as
floating, or a previously entered command is edited, in which case it
retains the channel of the original command.  This last may be overridden
by selecting a new default channel sometime AFTER the original command has
been selected, but before the terminating return; this sequence will also
temporarily redirect an unedited command to the default channel, but does
not change the association in the history.

A `floating' command line in the history is not associated with any
particular channel.  It will be always go out the current default channel
when invoked.  This is often useful for preventing multiple copies of
commonly used commands (such as DIR) littering the history area.  A
floating line can be entered either with the alt-return combination
mentioned or by entering it when there is no current default channel. The
`Set to Channel' operation may also be used (with no default) to make a
previously entered line floating.

For completeness it should be pointed out that channels are actually just
(ppIPC) IPCPorts passing messages with IDs suitable for an `IP:' device
data stream.  Hence any program that takes serial input (at least as long
as it doesn't need raw console keystrokes) can be linked to a channel via
an IP-device `pipe', or specially-written programs can even connect to a
channel port directly.  However, to complete the connection, Sili(CON:) has
to be requested to open that channel; for a shell, this is done automatically
by the linking program InShell, but a suitable message has to be sent in
other cases; another utility `SiLink' is available with the full package to
do this.

`Shutting' a channel is slightly more complex than it might at first
appear.  Just as Sili(CON:) only opens a channel when it is requested to do
so by a message, so it only actually shuts it (disables its menu item)
when it receives a message requesting this; such a message is normally sent
by the connection that is shutting down.  Selecting a channel from the
`SHUT:' menu simply sends a closedown request to the channel; it is up to
the channel itself to send the `SHUT' message in return before actually
going away.  A shell connection will always do this, but a channel opened
by `SiLink' for example may not.

Whether the menu item is disabled or not, however, has no direct bearing on
whether the channel is flushable.  A channel may be flushed only when there
are no other connections remaining to it.  In normal use, when a channel
has been opened by InShell, the menu item is disabled at the same time as
the connection is closed, so there is no confusion.  If you have connected
a channel via SiLink, however, you may need to be aware of the distinction.

Sili(CON:) WILL disable the channel menu item if you send a shut request
from the menu and it finds that the channel is already actually closed.
SiLink -- if you are using that -- has a SHUT option to send the
appropriate message, from a closedown script for example.





Menu Operations
===============

Sili(CON:) has four menu lists, positioned along the menu bar in a way that
should make them most convenient for most users, at least when the History
window is close to its default position.  At the far left is the `Sili(CON:)'
menu, only used for quitting the program and flushing shut channels.  Next
to it is the `SHUT:' menu, used for closing down individual channels.
On the right, above the normal position of the window, are the `Actions:'
and `Channel' menus.

The `Channel' and `SHUT:' menus contain the same list of currently known
channel names -- ghosted (disabled) if they have been shut.  Selecting an
item from the `Channel' menu makes this the default channel to which new
commands will be sent and on which most actions are performed.

Selecting from the `SHUT:' menu sends a closedown message out that channel;
if it is connected to a shell, an ENDCLI will be issued, the shell window
will close, and Sili(CON:) will disable that channel; if it is some other
program the result may be different -- in particular the menu item may NOT
get disabled.  For more on this see the `Channels' section.  Nothing
happens to the command lines in the history for that channel at this point,
nor does the default channel change if it happens to be the one that is
shut.

The `Actions:' menu contains a number of possible operations on the history
list and channels:

        `Gather Channel'    -- collects all the history lines pertaining
                            to the current default channel at the front of
                            the history; their order is otherwise unchanged.

        `Wipe Channel'      -- deletes all the history lines pertaining
                            to the current default channel.

        `Fix Channel'       -- forces ALL commands -- whether newly entered
                            or selected from the history -- to be sent out
                            the current default channel.  This coercion
                            remains in effect until another selection is
                            made from the Channel menu (this may be a
                            reselection of the same channel if you wish).
                            It has no effect on the associations in the
                            history, which will resume when the coercion
                            is ended.  You are reminded that this is in
                            effect by there being no default (bracketed)
                            channel shown in the title bar.

        `Set to Channel'    -- functional only when a history line is
                            currently selected: changes the association of
                            that command to the current default channel.

        `NO Channel'        -- sets the current default channel to null;
                            as well as making any newly entered commands
                            floating, this allows you to use the `Gather',
                            `Wipe', and `Set' operations on all the
                            floating history lines.

The `Sili(CON:)' menu has only two entries (separated by a blank space for
safety):

        `Flush Channels'    -- removes ALL unconnected channels completely
                            from Sili(CON:)'s control.  The associated
                            lines are wiped from the history, and the
                            channel names are removed from the menus.  Note
                            that there is no way of removing a channel
                            completely while there are other processes
                            connected to the port.

        `QUIT'              -- closes down Sili(CON:) completely.  All
                            channels and their associated shells are
                            closed, and the history discarded.

The `Actions:' and `Channel' menus have equivalent keyboard shortcut
commands; the less commonly used (and more protected) `Sili(CON:)' and
`SHUT:' menus don't.  For `Actions:', the key equivalent is the Right_Amiga
key combined with the initial letter of the item, except for `NO Channel'
which uses `Right_Amiga-0' (zero) by analogy with the channel selection
shortcuts.  The combinations `Right_Amiga_1' through `Right_Amiga_9' are
associated with the corresponding lines in the `Channel' menu.  It would be
possible (though rare) to have more than nine channels open, in which case
the later ones would only be accessible from the menu.






NewSili and Sili-Startup
========================

In the same way that you would type `NewShell' to open a new `standalone'
shell window, you use `NewSili' to open a new shell connected to
Sili(CON:).  This is actually a single name for a couple of different
mechanisms.  There is a short script -- expected to be in `S:' -- that will
do the job, but once you are running from a shell started in this way, it
will normally be an alias created by the startup script.

Whichever of these NewSili is, it simply performs the command

            newshell from S:Sili-Startup

Sili-Startup is a short script, analogous to `Shell-Startup' for a standard
shell except that it MUST contain the `InShell' command line that actually
makes the link to Sili(CON:).  The version supplied with this package can
simply be regarded as a base from which to tailor your own.

If your shells are virtually always connected to Sili(CON:), you may prefer
to add `InShell' directly to `S:Shell-Startup'.  In that case, the
`NewShell' command will make the connection itself if Sili(CON:) is
running.  (If it is not, the shell would continue as normal.)

Remember that the instant a new shell is started up, that window
momentarily becomes the active one (as always with a new shell), and
Sili(CON:) doesn't regain control until the InShell is executed.  You
should avoid typing anything in this short interval so that you don't get
unwanted characters (and blocked output!) in the new window.

Note that as supplied both NewSili and Sili-Startup refer to the `CON:'
device, rather than the `NEWCON:' that would be slightly preferable under
1.3 (in case you should ever want to make use of the Console Device history
as well).  This is very seldom needed, and the NEWCON device is not
recognized under 2.0, so to avoid having different versions for the two
systems the basic `CON:' has been used.  If you are running under 1.3 and
you wish to change it, please do so.





InShell -- Shell Linking Module
===============================

A standard AmigaDOS Shell or CLI, once running, is connected to Sili(CON:)
by invoking the program `InShell' (either directly or through a startup
mechanism such as NewSili). This opens a new `IP:' device channel, connects
it to the Standard Input of the shell, and informs Sili(CON:) that it is to
open (and switch to) that same channel.  It also ensures that the device is
set up to close down the shell and its I/O properly when eventually
requested to do so.  It then exits, leaving the shell free to accept
commands on its new input channel.

If InShell is executed without any command line argument, it forms a name
for the new channel by appending the number of the CLI process (assigned by
AmigaDOS) to the prefix `CLI_', so that each channel has a unique name.

If you are starting up a new shell for a particular purpose (working on a
project, perhaps) you may want to have a more specific name for the
channel.  To do this, simply provide the desired name as a command line
argument, like:

            inshell "my project"

You will probably want to do this from a script (similar to Sili-Startup
invoked by NewSili) that does any other initialization required for the
project at the same time.  You can then start it as:

            newshell from my-startup

or simply create a script or alias (like NewSili) to do the job.

Because InShell must be run in the newly started Shell, there is no easy
direct way to pass it an argument from the process in which the actual
`NewShell' is issued.  This can be done with pipes (IP or standard) or even
via a temporary file, but is cumbersome.  It doesn't seem worth including
examples; experiment if you feel like it.

The first time InShell is run after Sili(CON:) has started, it displays the
version number of Sili(CON:), and probably a little advertising message (!).
Thereafter, only a short identification is displayed.

InShell may be installed as a Resident command, if you wish, to speed up
its action somewhat. (For a description of the RESIDENT command see your
Amiga documentation.)





Keyboard Input to Programs
==========================

When Sili(CON:) is connected to a Shell process, it becomes the normal
Standard Input for that process, and therefore for all the programs run
under it.  This is often convenient, as it makes for a uniform keyboard
input mechanism.  However there are cases in which you might rather
interact with the program in the shell window itself, and if the program
happens to need RAW keyboard input (as opposed to the more usual
line-by-line mode) it MUST come from that window.

It is easy to arrange this, because Sili(CON:) does not affect the Console
Device for that window at all, and the special command line character `*'
will refer to this in the usual way.  Simply include the input redirection
argument `<*' in the command line immediately after the command name
itself and the program will take its input from the window rather than
Sili(CON:).

So to run the standard DOS program `more' (which does expect raw input)
from Sili(CON:), you can use:

            more <* mytext

If you do use such redirection, you will usually also want to transmit the
command with the Right_Amiga-return combination (see `Command Entry'), so
that the shell window is immediately activated for input.  This code
becomes associated with that command in the history, and the window
activates again each time the command is reinvoked. (You can also give the
Right_Amiga-return afterwards, of course, but it then is not associated
with the command.)

Unless the program being run does require raw keystrokes, there is usually
no need for redirection.  Sili(CON:) passes on the attention characters
`control-C;, `-D', `-E', and `-F' directly to the currently selected Shell
process. It also will pass on an end-of-file (`control-\') and a `lone'
return (even though this is not added to the history).

One thing Sili(CON:) does not provide is any direct way to pause scrolling
in the shell window.  If you are expecting this to be necessary, it is wise
to again use Right_Amiga-return as the command terminator, so you get
immediate access to the window and can pause scrolling with the spacebar
as usual.





The `Sili(CON:)' Input Port
===========================

As has been mentioned in passing several times, Sili(CON:) uses the ppIPC
communication mechanism for interacting with other processes.  Not only
does it send commands to the channels it is connected to, but it receives
information and commands of its own on an IPCPort named `Sili(CON:)'.
(If you are addressing this port, be sure you use EXACTLY the characters
within the quotes (but not the quotes themselves); case is important, too.)

InShell and SiLink open new channels by sending messages to this port,
and SiliConfig and SiliDump send their instructions and requests there.
The exact protocol of these messages is detailed in an Appendix to the
printed manual.

One thing it may be useful to know, however, is that it can receive lines
of text in the same form as it sends out as commands, and the same as the
`IP:' device receives and transmits.  Incoming lines are added directly to
the history (attached to the currently selected channel).

It is therefore easy -- even without SiliConfig from the full package --
to load Sili(CON:) with a convenient set of commands, at start up time
or later.  Create a file of the desired commands, one to a line.  Then copy
this (at start up time or later) to the history display with the command:

            type >IP:Sili(CON:) cmdfile

You may find this useful even if you have SiliConfig available, because the
current version of this always specifies the channel that each entered line
is to be associated with.  If you prefer to have the commands loaded into
the current default channel, whatever that may be, you may want to use this
mechanism.  If you do this often, you may even want to define an alias such
as:

            alias get type >IP:Sili(CON:) []







Distribution of this Program
============================

Sili(CON:) is not public domain.  The `Sili(CON:)' program, its associated
modules, and manual are copyrighted -- All Rights Reserved.

Sili(CON:) is distributed as ShareWare.  If you find it useful, please
send a license fee of $25 (US) to:

            Pete Goodeve
            3012 Deakin Street #D
            Berkeley, CA 94705
            USA

(Preferably use the `reg_form' included as a file in this directory, or an
approximate copy of it.)   In return you will receive a complete version of
the system (including all the ancillary utility modules omitted from this
Freely Distributable version) and a 40-page printed manual.

This version may be distributed without restriction as long as no charge
other than a reasonable disk duplication fee is made.  The Licensed version
provided for the $25 fee is licensed to one user only, and is not
distributable.

Please do not use this program without paying for it.  Every effort has
been made to produce a useful, bug-free product and documentation, and this
hasn't been cheap on my time!  Thanks for respecting the ShareWare Ethic!

                                        Pete Goodeve

                                        June 1991

                        --------------------------