This file describes the tool iconmaker version 1.0. It has been developed
using 1.2 beta 4 kickstart and has not been tested under 1.1 although
none of the new intuition or dos functions have been used.

Iconmaker builds icons for files that were created without them. Many
programs don't build icons when they create files using either a C
runtime system or the dos file primitives. This is because icon creation
requires extra program steps and it is difficult to create an in-memory
icon structure with C program statements (the icons's picture is
especially hard). However, if the program does have an icon file
available, then it is a rather simple matter to clone it. Iconmaker takes
this approach. 

Iconmaker may be invoked by the cli or workbench. If it is run from the
cli, then it accepts zero or one argument: the name of a device and/or
directory to start with.  If run from the workbench, then it also accepts
one argument (use  extended selection: hold down the shift key and click
Iconmaker (first) and then double click another object). The second
object is used to determine the  directory to begin with. Iconmaker
allows traversal up and down directory trees but cannot switch to another
device; hence, start up Iconmaker on the disk with which you want to
work. The default is to use the current directory if run from cli (with
zero args) and the directory that Iconmaker is in if from workbench. 

When invoked, Iconmaker presents a requestor to the user as follows:

+-------------+---------------+               selected:directory/name
|make project | -> Project    |       +--+ 
|-------------+---------------|       |  |   file 1
|make tool    | -> Tool       |       |  |   file 2
|-------------+---------------|       |  |     .
|make drawer  | -> (x,y)      |       |  |     .
+-------------+---------------+       |  |     .
                                      |  |     .
+-------------+---------------+       |  |
|Dir    Pick  | Info   Pick   |       |  |
|-------------+---------------|       |  |
|File   Pick  | Invert Pick   |       |  |
|-------------+---------------|       |  |
|Read    Dir  | Read Parent   |       |  |
|-------------+---------------|       |  |
|Refresh Dir  | DELETE FILES  |       |  |
+-------------+---------------+       +--+
                                
+-----------------------------+       +------+ +------+ +------+ +------+
|Pattern                      |       |quit  | | all  | | none | | quit |
| *                           |       +------+ +------+ +------+ +------+
+-----------------------------+ 
                                
+-----------------------------+ 
|Icon Template Pathnames      | 
|icons:|project|tool|drawer|  | 
+-----------------------------+ 

The gadget buttons direct the operations of iconmaker and the scrollable
file name display is used for the selection of files that are to have
icons created for them. There are also 2 text gadgets.

Iconmaker can  create 3 types of icon files: project, tool, and drawer.
In order to do this, it needs to be able to find 3 template icon files. 

The text requestor, Icon Template Pathnames, is for entering the location
of the icon files that will be used as the templates. This requestor is
initialized with the following:

	icons:|project|tool|drawer|

which has 4 text strings separated by vertical bars (|). The first
(icons:) is a logical device name that can be defined to be equal to
another device name and optionally one or more directories. For example,
suppose there is a directory df0:icon_templates on the system disk. The
following cli statement will define icons:

	assign icons: df0:icons_templates

Iconmaker would then look for 3 icon files,

		icons:project.info
		icons:tool.info
		icons:drawer.info

which when the assignment icons: is expanded, would result in the file
names:

		df0:icons_templates/project.info
		df0:icons_templates/tool.info
		df0:icons_templates/drawer.info

The easiest way to use Iconmaker is to have a directory which contains the
three template icons (and any others you want to use)  and use the
startup-sequence file to make the assignment. 

Note that if you want to use the workbench INFO option to edit the icons
tool-types, stack size, and default tool fields then you will need files
called project and tool and an actual directory called drawer. The files
and drawer may be empty since they are not used by Iconmaker. 

You may also modify any of the strings in the text requestor. For
example, if you did not assign icons at the cli level, then you could
modify it in the text requestor directly as such:

	df0:icons_templates/|project|tool|drawer|

Note the trailing slash (/). Iconmaker builds each of the three file
names by concatonating the first string with each of the following 3
strings and appending .info to form the three names. 

Changing the names of the files is fine but there is one caveat. The
order of the names corresponds to the 3 types of icons. While it is ok to
use icons for tools and projects interchangably, you may not use either a
project or a tool icon for a drawer icon. To do so will cause a crash
when the drawer icon is clicked since drawer icon files have information
about a window to build. This information is missing in other icon types
and Iconmaker does not try to construct this information. Note that it is
not necessary to enter a return in this text requestor to have its
current contents be used.

When Iconmaker builds the new icon files, it always sets up the (x,y)
location of the icon with a special code that causes the Workbench to
place the icon in a window wherever it finds room. This is usually to be
preferred (at least by me) since it always will do the equivalent of a
clean-up operation after all the icons have been read for a drawer.
However, it causes the WB to not display any icons until all have been
read so it may present a blank window for some time. If you prefer to
have icons show up as usual, then you will have to use the WB option
snapshot. However, with 1.2 of kickstart and a bit of memory allocated
for disk buffers, opening a drawer is a faster operation. There is also
an option to convert existing icon files to auto-placement icons.

Once the locations of the template files have been determined, one may
set  about to tell iconmaker which files need icons. There are 7 ways to
select files. The files in the scroll area will initially be un-selected.
When they are selected, their color is complemented. Single files may be
selected by pointing at their name with the mouse and clicking the left
button. Any file that is already selected will become un-selected when
clicked. The 7 selection methods are:

The buttons ALL and NONE will select just that. 

The buttons FILE PICK and DIR PICK are designed to select either files or
directories that -- do not --  have icons already. Thus, a file or
directory that has an associated .info file will not be selected.
However, if either of these two buttons are clicked two times in a
row, then they will select all files or directories. If selected
repeatedly, the result will toggle back to the first select.

The button INFO PICK will select all *.info files except the file .info
which is not a normal icon file. The three select buttons will first
un-select all files.

INVERT PICK will toggle all the selected and un-selected files. 

The pattern requestor takes a * wildcard (as found on most other systems)
for multiple character wildcarding and ? for single character wildcards.
The pattern selects files in addition to any already selected files. The
selection takes place when the return key is typed. Multiple selections
may be made using the pattern gadget.

Once a set of file has been selected, an operation may be performed. The
operations are:

Make PROJECT, TOOL, and DRAWER. These three operations make icon files.
Before using these operations, the corresponding files should be
selected. Do not make icon files for icon files; Iconmaker will not check
this.

Convert, denoted as   ->    , is used to change tool and project icons.
Only the icon type is changed, other information remains the same. The
option to convert (x,y) will set the icon files position to floating as
described above.

The DELETE FILES options may be used on any files, including directories,
but directories must be empty first. Deletion brings up a last chance
cancel requestor.

The remaining operations are concerned with directory lookup operations.

The operation of REFRESH DIR will cause the current directory to be
re-read  and displayed. Normally, when icons are created in the current
directory, the display is not updated for reasons of clarity and speed.
This option will make the directory display current. The button READ
PARENT will set the directory up the tree one level and read that
directory. The button READ DIR will choose the first selected directory
file and read that directory.

Some operations are invalid and will cause a requestor to appear. When
one shows up with two OK buttons then the message is informational and
the operation will be aborted once either OK button is picked. If the
requestor shows an OK button and a CANCEL button then it means that one
of the picked files is inappropriate to the action requested