-- Xicon 2.5 --

                              December 1989


It's been more than three years since I originally wrote Xicon (July 1986),
and until last year it was essentially the only program to provide a means
of running a CLI command script from an icon.  With Commodore's own IconX,
it finally has some competition.  The previous version of Xicon -- 2.01 --
has a number of features that are missing from IconX, but, equally well,
IconX has a couple of very useful options that I had always wanted in Xicon
but never could figure out a neat way to do.  Spurred on by the example
placed in front of me, I finally got my act together and put the missing
features in.  Xicon 2.5 does everything IconX does, and still has all its
old features (including one or two -- like LOCDIR -- that are a bit
redundant now).

For many straightforward applications IconX can now supplant Xicon, but
I think Xicon is still a worthwhile alternative -- despite being twice
the size of IconX -- because it has some tricks of its own that aren't
available otherwise.  In particular, there is its unique ability to have
the icon attached NOT to a script file directly but to another type of
object, say a directory that contains -- as well as the script -- a whole
package of files.  In this case the script is referenced by a ToolType
entry in the icon itself.  Alternatively, the script to be executed could
be in some other drawer entirely; or you could run several scripts in
different drawers from one icon.  (Under WorkBench 1.3, in fact, you now
don't need anything at ALL attached to the icon, so you can control
everything with ToolTypes if you want.)

Then there is the (somewhat rudimentary, I concede...) facility for
displaying a text file directly, or even displaying some text directly from
the icon file itself. Xicon gives you a Close gadget to exit rather than a
predetermined delay, and you can take differing actions depending on
whether the user has aborted the sequence or not.  Not only can you control
the size of the window, but you can change its title; you can even dispense
with a window altogether if the script isn't going to generate any useful
output.


                        Drawer Contents
                        ===============

This package is considerably streamlined from previous releases.  I haven't
even included sources this time (though if you really want them I'm sure it
can be arranged...).  The only examples I've included are the three icons
you see -- Xicon itself and the two texts.  You might want to look at the
ToolTypes of these to see how an icon/file pair can be made to do several
things, even without any "script" at all.

The Xicon one, for example, in addition to displaying information -- if
available --, now gives you the option of installing Xicon in your C:
directory.  You will see also that it checks to see if the informational
text is available, and if not just displays a brief apology and proceeds.



                        Manual Update
                        =============

The accompanying manual has been revised to match the new features, but
for those already familiar with the program, I'm including a summary of
the new stuff here.

[++ By the way, to avoid confusion, when I refer (above and below) to the
script or other file "attached" to the icon, I mean the file in the same
directory that has the same name as the icon sans ".info". ++]



* Current Directory setting:

The most important new feature is that the "current directory" is now set
to that containing the icon clicked on, before the script (either in the
same directory or elsewhere) is executed.  This eliminates the need for
the LOCDIR ToolType hack, although it is left in this version so that
scripts expecting it don't break.

The current directory is set before each script (if there is more than one).
It is also set before executing any command line specified directly in a
"CMD=..." ToolType.



* Scripts with Conditional Commands and Parameters:

It is now possible to invoke scripts that contain conditional DOS commands
(IF, ELSE, etc).  To do this, Xicon needs to have the EXECUTE command
available in the C: directory (as well as the RUN command, which it has
always needed).  The FIRST character of a script that contains conditional
commands (at least if it is directly attached to the icon), must be a
period ".".  This may be the first character of a ".KEY..." script directive
(see below) or sometimes you can simply use a period by itself on the line.

If you intend to use EXECUTE, and don't actually have any .KEY parameters,
it will probably still save you a lot of grief to simply use a dummy
directive of the form:
                        .K ""

where the "" supplies a null parameter that EXECUTE will ignore.  Otherwise
a "<" character occurring ANYWHERE in your script (even in a comment!) will
cause EXECUTE to complain "No .K directive".  [Just one more of the Amazing
features of DOS...]

If the first character of an attached script is NOT a period, Xicon runs
the sequence of commands directly, just as it always has.

You can also invoke EXECUTE on any script through a ToolType entry:

        EXECUTE=scriptname arg1 arg2....

where 'scriptname' is the script file you wish to run (given as a full
pathname if it is not in the same directory as the icon), and 'arg1' etc
are optional arguments (parameters) to pass to the script -- if it has
a suitable '.KEY' directive to accept them (see your DOS manual under
'EXECUTE').

The "EXECUTE=..." ToolType is in addition to the old "SCRIPT=..." one, which
operates as it always has -- i.e. it NEVER uses EXECUTE (even if the script
begins with a period).  On the other hand, "EXECUTE=..." doesn't require
that initial period, so you can run Shell scripts (that might have
conditional commands but no .KEY directive, perhaps) without changing them.
In parallel to the "ABORT-SCRIPT=..." ToolType there is "ABORT-EXECUTE...".
[As an aside for the adventurous, there is no reason why a "script"
referenced by a ToolType could not in fact be a Pipe, filled by previous
actions!  Maybe you can think of an application...]



* Icons as Parameters to a Script:

It is also possible to pass parameters to the script attached to the icon
by "shift-clicking" on several icons in sequence.  The rule here is that
the FIRST icon selected must be attached to a suitable script file (with
a ".KEY" directive); the following files (and their icons) may be of any
type: only the file names (in FULL pathname form) will be passed to the
script as parameters.

Note that if the first script in a shift-clicked set does NOT have an
initial period, Xicon will simply run it and move on to the next; once it
finds one that it should pass to EXECUTE, it immediately passes all the
remaining items in the set as parameters (without trying to run them).
(It is not possible to pass shift-clicked icons to a script executed from
a ToolType.)



* Console Interaction:

Any script run via EXECUTE is also run in "interactive" mode.  In other
words a command in it that expects input from the console will wait for
it properly.  This was hard to arrange in earlier versions of Xicon: you
had to resort to tricks like opening a special input window.  [Actually a
new CLI is being created for this, and terminated when done. If the script
fails, it can dump you into this CLI (and you will see a standard prompt).
(This is also a possibility in IconX, by the way.)  If this happens, simply
type "endcli" to get out; you'll have to click on the close gadget as well,
of course, if the icon doesn't have 'MODE=closewindow'.]

Unfortunately nothing ever seems to be entirely free. If any program
invoked by the script accesses the console for input, this also diverts
access away (permanently) from Xicon, meaning that you can no longer
close the window with control-C.  You still have the Close gadget, of
course, or you can set MODE=closewindow to terminate automatically.

In some cases also it seems that programs run in this mode may not
pick up a control-C abort themselves , so you STILL may have to use
special tricks.  Sorry.

                               + + +


About the only other advance in this version is that the code is
considerably shorter.  This isn't the result of tightened up source,
but simply the much improved code generation of Lattice 5.0, especially
the direct system calls.  Thanks, JT!

[By the way, if this package is still in its original form, you will of
course have noticed the program ("Most") used to display this text.  It is
an Australian program, sent to me on "MegaDisc" -- their own, very nice,
disk magazine. You can find details in the "About" Menu of the program.

...And -- if "Most" is missing, you will be viewing the text through
Xicon's own primitive mechanism.  You might want to take a look at the
ToolTypes in the icons to see how some of Xicon's unique features are
used.  In case you were doubtful, Most can itself of course be a Default
Tool for a text's Project icon, but in this case, I wanted to demonstrate
Xicon's ability to take remedial action if the environment is not correct.]


                                        Pete Goodeve
                                        December 1989