<html>
<HEAD>
<TITLE></TITLE>
</HEAD>
<BODY> 


<H1>
<center><big>
                               == xicon ==
<BR>
                               -----------------
</big></center>
</H1>


This is a little utility that lets you run shell (and other) scripts from Tracker icons just as if they were regular applications.  It gives you options that are otherwise unavailable.
.<P>
First, it will open a Terminal window to run the script, so you can both see the output and interact with it.  Secondly you can drag and drop other icons onto the script icon, and the script will be invoked with the drsgged items as arguments..  (You can also, if appropriate, invoke a shell without a Terminal but still drag and drop.) 
<P>
<A NAME="contents"></A>
</UL>
<LI><A HREF="#usage">Using xicon</A>
<LI><A HREF="#changes">Version 1.2 changes</A>
<LI><A HREF="#installation">Installation</A>
<LI><A HREF="#demos">Demo Scripts</A>
<LI><A HREF="#creating">Creating Scripts</A>
<LI><A HREF="#attrib">The Attributes of a Script</A>
<LI><A HREF="#notes">Notes & Subtleties</A>
<LI><A HREF="#compile">Compilation Notes</A>
<LI><A HREF="#distribution">Distribution</A>
<LI><A HREF="#author">Author & Acknowledgements</A>
<LI><A HREF="#history">History</A>
</UL>
<BR>

<H2>
<A NAME="usage">Using xicon</A>
</H2>

You don't execute xicon directly: it is invoked automatically by any script that has xicon as its "preferred app", when you either double-click on that script's icon, or drag other icons onto it.
If you drag icons onto a script icon, they will be presented as command-line arguments to the script.
A 'script' is a textual command-sequence file that would otherwise be executed by typing a command line in a Terminal window.  These are most commonly standard shell (bash) scripts, but may be in any language that has an available command-line-invoked interpreter.
<P>
The utility is intended as a convenient GUI-based mechanism for executing user-written scripts -- to perform common sequences of operations on files, for example.  The procedure for associating a script with xicon is detailed below.  [In case there's confusion, xicon is of course not concerned with BeOS 'Application Scripting' -- the BMessage mechanism used to communicate directly with running programs.  On the other hand, there is no reason why xicon scripts should not contain Scripting commands, through a shell-based program such as 'hey'.]
<P>
Although a script that runs under xicon is in essence no different from any other, you may want
to tailor it somewhat to this use..  For example the special environment variable FOLDER_PATH is made available to indicate the script's own directory.  Such considerations are discussed in more detail below.
<P>
<h6 align=right > <A HREF="#contents">Back to contents</A></h6>
<BR>

<H2>
<A NAME="changes">Version 1.2 changes</A>
</H2>

This revision simply corrects for some changes made to the R4 Tracker.  (It still works with (PPC) R3 as well.  It has not been tested against earlier revs of the OS.)  Functionally, it is identical to version 1.1.
<P>
The PPC and Intel Packages are now completely separate.  This is necessary because the
Tracker gets confused as to the correct-platform executable!  (If you get a message that
a script or xicon itself is "mistakenly marked as Executable...", you probably have an inappropriate
version of the app somewhere on your machine.  Ensure that you install only the one for
your platform.)
<P>
The Intel exeutable is now in ELF format (for BeOS R4).  For Intel R3, you can continue to use
xicon 1.1, or recompile this version yourself.
<P>
<h6 align=right > <A HREF="#contents">Back to contents</A></h6>
<BR>


<H2>
<A NAME="installation">Installation</A>
</H2>

Simply unpacking this zip archive should have been sufficient to set everything up.  You may not
see the correct icons immediately, but give the Registrar a few minutes to figure things out.  You
may speed things up if you cd to the xicon_1.2 directory and do "mimeset -f xicon"  (This is most
likely outdated advice, but I've left it in just in case..(:--).). 
<P>
A successful unzip should have given you the directory "xicon_1.2" containing some demo scripts
with identifying icons, and a PROGRAM directory containing the source  and a separate project
folders for either PPC or Intel depending on the archive you have chosen (the source is the same).   The actual xicon executable is in the appropriate platform folder (rather than at the top level as it once was in the PPC-only version).
<P>
The only file that you need to keep around for operation is xicon itself, and you can put
that anywhere convenient.  It will get activated by any script that has the right filetype,
or has it as its preferred application.  You should also be careful to keep the "convert to xicon scrtipt" file around unchanged somewhere, as it contains the "master copy" of the attributes
needed for scripts under R3 and later.
<P>
To ensure that everyting is correct, I suggest looking at xicon with the FileType add-on.
It should show  supported types: "text/x-script.xicon:", "text/x-script.xicon-bg", and
 "text/x-script.xicon-sh" (as well as  'text/x-term-script" and "text/x-sh-script" -- the obsolete
variants), each with its icon.  If you do the same with any of the demo scripts it should be of
"text/x-script.xicon" type and have xicon as its preferred application.
<P>
Any newly made script must be set up properly before it can function.  A later section details
how to do this.
<P>
<h6 align=right > <A HREF="#contents">Back to contents</A></h6>
<BR>

<H2>
<A NAME="demos">Demo Scripts</A>
</H2>

A few example scripts are included, plus one important one:
<BLOCKQUOTE>
<DL compact>
	<DT>'<tt>test</tt>'		<DD>If you just (double) click on this, it should show the complete path to 
			the folder it was invoked from.  If you select one or more other icons, 
	and drag them onto it, it will give you some details about their type and attibutes.
	<P>
	<DT>'<tt>ls -l</tt>'		<DD>Does what you'd probably expect.  If you click on it, it will list its own
			directory; if you drag other folders onto it, it will list them; single files
	will also get listed, but see the note about symbolic links below.  [You might ask
	what the point of such a script is, when you can just see it in a window anyway,
	but lt gives some information, such as mode bits and link resolution that isn't so
	easy to see otherwise.]
	<P>
	<DT>'<tt>mimeset</tt>'	<DD>This provides a convenient way of doing mimeset on a file.  Just drag the
			file onto this icon,; its current attributes and type will be displayed and
	you will be queried if you really want to mimeset it. If you answer 'y(es)', it will forcibly
	mimeset the file and report the resulting attributes.  You can do multiple files if you wish.
	<P>
	<DT>'<tt>factors.py</tt>'		<DD>This is a Python script, and so will only be functional if you have
				that interpreter installed on your machine (expected to be
	/boot/home/config/bin/python)   It was simply snitched from the Python Demo folder,
	with some slight modifications and added prompts.  It displays the factors of any
	entered integer.  (The ".py" extension isn't necessary -- it is just there to make it
	clear that it is Python.)
	<P>
	<DT>'<tt>convert to xicon script</tt>'	<DD>This is the important one... When you've created (or
						modified) your script, just drag it onto this, and it will
	take all the necessary steps to make it work under xicon.  (It is fairly verbose, and
	asks for authorization before actually doing the adjustment.)  See the section below
	for details on the process.
</DL>
</BLOCKQUOTE>

To see the actual contents of one of these scripts, drag it onto StyledEdit, or onto any editor of
your choice, or simply open a Terminal and 'cat' it (they're all short).
<P>
<h6 align=right > <A HREF="#contents">Back to contents</A></h6>
<BR>

<H2>
<A NAME="creating">Creating Scripts</A>
</H2>

First, of course, write your script, by whatever means is convenient -- e.g. StyledEdit. or any other
text editor.  When you've saved it, just drag and drop its icon onto 'convert to xicon script'.
This sets the filetype to 'text/x-script.xicon', makes it 'executable', and adds a 'supported file
types' attribute for 'all files', so that the R3 Tracker knows that you can drop files on it.
<P>
Alternatively, you can simply duplicate an existing working script with the Tracker, rename it
appropriately and then edit it as you want.  If it doesn't work afterwards for some reason (maybe
your editor changed its attributes), run it through 'convert to xicon script' again.
<P>
There are perhaps two special considerations when writing scripts.  First, you'll want to ensure
that the Terminal doesn't close the moment the script ends.  Any command that expects user
input will do: a simple  "read"  (bash command) is as convenient as any, but "sh" could also be
appropirate if you wanted the window to remain open afterward as a general shell.  Of course
if there's a command like "more" in the script, it's sufficient in itself to hold the window.
<P>
The other point is that the script always initially opens in '/boot/home', whatever folder
the script itself is in.  However, xicon sets the environment variable 'FOLDER_PATH' just like
Pierre Brua's "TermHire" add-on, so this is available for the script to access.  [It doesn't get
used automatically, because ".profile" is not run...]  To get the correct directory, start your
script with "cd $FOLDER_PATH".  (This would be language dependent for a non-bash script,
of course.)
<P>
If you want your script to be anything other than a bash one, the first line must indicate the
actual interpreter to be used, as per the usual shell standard.  I.e the script must begin with
"<tt>#! &lt;interpreter-path-name&gt;</tt>".  For example:
<BLOCKQUOTE><tt>
				#! /boot/home/config/bin/python
</tt></BLOCKQUOTE>
<P>
<h6 align=right > <A HREF="#contents">Back to contents</A></h6>
<BR>

<H2>
<A NAME="attrib">The Attributes of a Script</A>
</H2>

To function correctly under xicon, a script needs a few specifics:.  It should have xicon as the
<i>Preferred App</i>, of course, and it should have the ('posix-side') <i>executable mode</i> bit set.  Normally
it should also have filetype '<tt>text/x-script.xicon</tt>'  (see below for alternatives).  In order to be able to accept dropped files under R3 or later, it also needs to specify '<i>Generic File</i>' as a <i>Supported Type</i>.
All these items are set up by '<tt>convert to xicon script</tt>'.
<P>
In detail:
<BLOCKQUOTE>
<DL compact>
	<LI>The <i>Preferred App</i> --  attribute '<tt>BEOS:PREF_APP</tt>'  -- must be '<tt>application/x-xicon</tt>'.  (This is
	required for xicon to be able to process the script.)
	<P>
	<LI>The (shell) command '<tt>chmod +x ...</tt>' must have been applied to the script.
	<P>
	<LI>The <i>File Type</i> -- attribute '<tt>BEOS:TYPE</tt>' -- will normally be '<tt>text/x-script.xicon</tt>'.	this gives
	the default behaviour -- provides the standard icon, opens a Terminal window and passes
	arguments as a single "command line".  Setting it instead to '<tt>text/x-script.xicon-bg</tt>' will
	cause it to run in the "background" without a Terminal window; the icon is different to
	indicate this,.  There is a third specific possibility that most likely is completely unneeded,
	but has been provided "in case"; this is '<tt>text/x-script.xicon-sh</tt>', and discussion is deferred
	to the "Notes & Subtleties" section.  Aside from these standard choices, you can use any
	filetype you want, if there is good reason to, as long as xicon is set as the preferred app,
	and of course you can set a custom icon too if you wish, via the 'FileType' Add-On; any
	such setup will behave exactly the same as the default.
	<P>
	<LI>The <i>Supported Types</i> attribute -- '<tt>BEOS:FILE_TYPES</tt>' -- should be "<i>Generic File</i>" (actually
	'<tt>application/octet-stream</tt>' internally).  However there is no easy way for a user to set
	this attribute on any file that is not an "Application".  The most convenient method seems
	to be to use the '<tt>copyattr</tt>' command to get it from a 'template' file; this is what '<tt>convert
	to xicon script</tt>' does (using itself as the template)  And, for those who might worry about
	a resulting proliferation of items in the "<tt>Open With...</tt>" Tracker menu, fortunately -- as scripts
	are not "Applications" -- the Tracker ignores them in this case!
</DL>
</BLOCKQUOTE>
<h6 align=right > <A HREF="#contents">Back to contents</A></h6>
<P>

<H2>
<A NAME="notes">Notes & Subtleties</A>
</H2>

One important note regarding symbolic links: If you drag an icon that is a link onto your script,
the path you get as an argument is to the actual file, not the link!  This is not the behaviour I would
prefer or expect, but it seems to be unavoidable at the moment [even if I set 'traverse' to FALSE,
fo those of you who've read the book....].  The Tracker resolves the link beforeit passes it on, so
there is no way of getting the link itself..
<P>
Enabling the use of other scripts than simple bash ones, entailed changing the way the script is
invoked, and the way arguments are passed to a script.   Originally, the script was passed
directly to the shell, and each dropped file was a separate (null-terminated) argument string;
this is accepted syntax for shell scripts only -- in fact even the "#!..." mechanism is ineffective.
Now, however, a complete "command line" is built and passed to the shell, allowing full functionality.
However, there are disadvantages.  Maximum command line length is fixed, so if you select a lot
of files to drop on the script, some may not get passed.  (It does check before adding each name,
though, so you won't get partial ones in the set.)   Further, it has to quote each name, in case it
contains spaces and so on;  This means that you can't in turn use any filename with quotes in
it (unlikely, but BeOS doesn't care...); the old method would accept any name.  Just in case you
have a bash script that you would prefer to invoke via the old mechanism, the filr type
'text/x-script.xicon-sh' is provided.  This is the same as 'text/x-script.xicon', except  for the
limitation to bash, and the unrestricted arguments.
<P>
I should probably whisper this bit, because I think it breaks a few otherwise admirable conventions,
but you not only can now invoke any type of script directly,... you can also invoke any shell command
line program!  Just use 'convert to xicon script' on it.  It will no longer be 'application/x-be-executable'
but that's actually not important for a command-line-only app.  As you can achieve the same effect
with a one line script that invokes the app, converting the app itself has little value, but the facility
is there if you need it.  (I suggest you don't mess with anything in /beos/bin: if you want to play,
make a copy!)
<P>
BTW, If the name 'xicon' seems familiar to any old Amigans out there... yes it is in memory
of a program with some slight resemblance that I wrote many years ago for that machine.
<P>
<h6 align=right > <A HREF="#contents">Back to contents</A></h6>

<H2>
<A NAME="compile">Compilation Notes</A>
</H2>

As noted above, there are two separate arcives, one for PPC and one for Intel.  The project file itself is in the 'PPC' or 'Intel' folder within the 'PROGRAM' folder.  Both projects reference the same source file, in the PROGRAM directory.  The Intel side is set up for the ELF binary format, as required for R4.
[John Ashmun has the credit for compiling and checking the ELF version.]
<P>
The source now includes the specific headers it needs, rather than relying on precompiled headers.    A suitable Resource file is included in each version, altough as of R4 the same file should be applicable to both platforms..
<P>
<h6 align=right > <A HREF="#contents">Back to contents</A></h6>

<H2>
<A NAME="distribution">Distribution</A>
</H2>

xicon may be freely distributed, and the source may be used or modified as desired. Please
keep the credits intact, though.  (As noted in the source, I've derived some major parts of the
code from Pierre Brua's TermHire.)
<P>
<h6 align=right > <A HREF="#contents">Back to contents</A></h6>


<H3>
</H3>

<H2>
<A NAME="author">Author & Acknowledgements</A>
</H2>

xicon was written by:
<br>
<ADDRESS><center>
<BLOCKQUOTE>
		Pete Goodeve<br>
		email:  pete.goodeve@computer.org
</BLOCKQUOTE>
</center></ADDRESS>
<br>

with some parts of the code borrowed from Pierre Brua's "TermHire"
<P>
Many thanks go to John R. Ashmun for the Intel compilation, and for checking things out on that
platform.
<P>
<h6 align=right > <A HREF="#contents">Back to contents</A></h6>


<center>
                                             =   =   =
</center>



<H2>
<A NAME="history">History</A>
</H2>

<H3>
Version 1.1 changes:
</H3>

The 1.1 revision had a couple of slight modifications to give it a little more versatility, and conform better to a suggested standard.  In addition, it was the first release compiled for Intel as well as PowerPC.
<P>
Under the R3 version of BeOS, there were some changes to the Tracker that prevented scripts created for xicon v1.0 from accepting dropped files.  Adding 'xiconability' to scripts became a little less straightforward, so a simple mechanism for creating them  (using a xicon script, of course!) was included in the package.
<P>
Most important of the new features was to allow xicon to execute any kind of script, such as
Python or perl, directly.  Previously it could only handle bash syntax.
<P>
The Mime-types used to indicate the desired action also changed, to better agree with a suggested standard for script types under BeOS.  The old  (v1.0) type names are still valid, but I suggest
you avoid them.
<P>
<h6 align=right > <A HREF="#contents">Back to contents</A></h6>
<BR>


</body>
</html>

