$VER: AddTools.doc 1.20 (29.11.93)  Alessandro Sala

                    AddTools version 1.20 29-Nov-1993
                   Copyright  1993 By Alessandro Sala

             Requires AmigaOS v2.04 ( Kickstart v37 ) or later


                               ------------
                                Disclaimer
                               ------------

   This program is provided "as is" without warranty of any kind, either
expressed or implied, including, but not limited to, the implied warranty
of fitness for a particular purpose.  Though every care has been taken to
make this program system-friendly and bugs-free, the entire risk as to the
results, reliability and performance of this program is assumed by you.


                            ------------------
                             Copyright notice
                            ------------------

   This program is "FreeWare": it can be freely copied and distributed for
non-commercial purposes, provided that no file is added to or removed from the
distribution archive and no charge, beside a nominal media cost, is requested.
   Fred Fish is, of course, explicitly allowed to put this program on his
great disk library.
   Nevertheless the program remains COPYRIGHT of the Author: you cannot
patch, reverse engineer or otherwise modify the program, the documentation and
every other file found in the distribution archive.
   Compressing in executable form is only allowed for personal use, not
when the program is being distributed: LHARC'ing in an archival form is
explicitly allowed for distribution convenience.
   Furthermore you cannot embed the program in any other software without
the written permission of the author.

                     ------------------------------------
                     Contents of the distribution archive
                     ------------------------------------

    AddTools                 : The main program
    AddToolsData             : Configuration file example
    AddToolsDoc-E            : English documentation
    Catalogs                 : Drawer
      AddTools.ct            : Empty translation file
      italiano               : Drawer
        AddTools.catalog     : Italian language support file
    MTCopy                   : Example AmigaDos script for use with AddTools

    AddTools.info           \
    AddToolsData.info        |
    AddToolsDoc-E.info       |       : Related icons
    Catalogs.info            |
      AddTools.ct.info       |
    MTCopy.info             /


                             1. Introduction
                             ---------------

   AddTools is a very simple utility, written mainly to experiment with the
new applications menu ( "Tools" ) of AmigaOS release 2, but I found it very
useful so I decided to release it as Freeware with the hope that someone
else will find it convenient.
   The program allows you to add your own items to the "Tools" menu of
AmigaOS_2.04's Workbench Screen. Unlike other menu utilities, which only add
the ability to run programs by menu, AddTools can also pass them some
parameters on "the fly" by selecting some icons ( from now on called " icon
parameters" ), before choosing the desired menu item. You can also
provide default values if no icons are selected, and you can decide if the
the program must be run in either synchronous or asynchronous mode when
multiple icon parameters are selected.

                         --------------------------
                         Changes since version 1.11
                         --------------------------

   If you already know AddTools v1.11, here are some major differences from the
previous version:

  --  New BREAK_WARN tooltype: if set, AddTools will open a requester to warn
you whenever it receives a control-c signal.

  --  New EXTRA_ITEM tooltype: AddTools will add the 'AddTools...' item to the
tools menu only if this tooltype is set.

  --  New WINDOW= tooltype, allowing you to configure the default output window
for the programs you run using the tools menu.

  --  Ability to individually configure the output window for every menu item.


                                ------------
                                Installation
                                ------------

   To install AddTools you can simply copy it in some drawer, typically
your SYS:WBStartup drawer. Then create the configuration file AddToolsData, as
explained below, and put it in your S: volume ( normally the SYS:S drawer ) or
in the same directory as AddTools. If you have OS 2.1 or later and you want to
take advantage of the localization, you must also copy the 'catalogs' drawer,
found in the AddTools distribution archive, into the same drawer as AddTools,
or you can copy the 'AddTools.catalog' file ( found in the 'catalogs/<language>/'
drawer ) into your 'LOCALE:catalogs/<language>/' drawer.
   If your language is not currently available, you can fill in the empty
translation file found in the catalogs drawer ( catalogs/AddTools.ct ) and
send it to me by E-Mail ( the address is at the end of this file ). I will
create a new '<your-language>/AddTools.catalog' file and E-Mail it to you as
soon as possible, and the next version of AddTools will support one more
language !


                         2. Configuration and usage
                         --------------------------

-2.1- Tooltypes

   You can set various tooltypes in the AddTools' icon:

      BREAK_WARN          : If set, AddTools will open a requester whenever it
                            receives a control-c signal, informing you that
                            it is quitting.

      EXTRA_ITEM          : If set, an extra item, named 'AddTools...', will be
                            added at the bottom of the tools menu. Selecting this
                            item, a requester will open, asking you if you want
                            to quit AddTools.

      WINDOW=<win_desc>   : With this tooltype you can configure the window
                            that AddTool provides to every program you run from
                            the tools menu. The default <win_desc> is:

                                CON:0/40/640/150/AddTools/auto/close/wait

                            which means: a 640 pixels wide, 150 pixels tall
                            window, located at the top of the screen, and 40
                            pixels from the left border. The window's title is
                            'AddTools', it will open only if the program
                            actually does some output, it will have a close
                            button and it will not close automatically, when
                            the program ends.
                            For more info about window descriptions, see your
                            AmigaDOS manual.
                            The window can also be individually configured for
                            every menu item: see below.

-2.2- The configuration file

   AddTools can be started from workbench by double-clicking its icon or by
placing it in your WBStartup drawer to have it activated every time you
boot; in this case remember to add the "DONOTWAIT" ToolType.
   You can also run AddTools from a CLI or from your user-startup; in this
case use the RUN command to start AddTools in the background.
   When AddTools is started, it looks in the current directory to see if a
configuration file named "AddToolsData" exists: if not, it then searches
in the S: volume (typically your SYS:S drawer) and aborts if it doesn't find
there the configuration file.
   The "AddToolsData" file contains the description of the various menu items
you want to add to the Tools menu. Every item is defined by three lines with
the following format:

      <Line 1>    Menu_item_text
      <Line 2>    Menu_item_associated_command_line_with_parameters
      <Line 3>    Synchronous/Asynchronous_mode_flag_&_output_window

these three lines are repeated for every menu item you want to add. Here
comes an explanation of every line:

   Line 1 : Menu item text :   This is the text you want to be displayed in
                             the tools menu: note that shortcuts are not
                             available at the moment.


   Line 2 : Command line   :   This will normally be the complete path and
                             name of the program you want to be run when
                             choosing this menu item, possibly followed by
                             parameters. If you want to pass this program
                             possible icons as parameters you must include
                             a special char sequence in the command line, as
                             explained below.


   Line 3 : Sync/Async&out :   This will be either an "A" or an "S" char to
                             indicate A)synchronous or S)ynchronous execution
                             mode (see below). After this first char, you can
                             optionally put a '|' character followed by window
                             description which will be used as the output
                             window for the command line of this menu item.

                             E.g. A|CON:10/30/300/200/MyWindow/close/auto

                             will give you a 300 pixels wide, 200 pixels tall
                             window, located at 10 pixels from the left border
                             and 30 pixels from the top border. The title of
                             the window will be 'MyWindow', it will have a
                             close button ('close' option) and it will open
                             only if the program prints something ('auto'
                             option). When the program ends, this window will
                             automatically close. For more info, see your
                             AmigaDOS manual.

   In the distribution archive you can find an example of the 'AddToolsData'
configuration file.

-2.3- Synchronous vs. Asynchronous mode

   If, in the third line of a menu item definition, you specified
asynchronous mode, AddTools will execute the associated command line
asynchronously ( as you might expect ! ), that is not waiting for the
completion of the program execution. This is the best way if the program has
fixed parameters, directly passed in by the command line you provided. This
mode can also be useful with icons parameters, but I will explain this later.
   On the other hand, in synchronous mode, if you select more than one icon
parameter, AddTools will wait until the program execution has completed before
handling successive icon parameters. The usefulness of this mode will come
clear in the next section when I' ll discuss of multiple icon parameters.


-2.4- Icon parameters

   If, before choosing a menu item, you select one or more icons, the
menu item associated program will be able to see them as if they were
command line parameters. To enable this feature for a particular item, you
must specify in the item's command line a string with the following format:

      [<default_params>]

where '<default_params>' is whatever string you want and '[' and']' are
simply what they seem: open and closed square brackets !


-2.4.1- Single icon parameter

   When an icon parameter is selected, its complete volume:path/name string
will be substituted to the <default_params> string, and the two square
brackets will be removed. The resulting command line is then executed.
   If no icon is selected when the menu item is chosen, no substitution will
occur and the square brackets will be removed, so the resulting command line
will contain the <default_params> string which will act as a default parameter
block. Note that the [xxx] can be put everywhere in the command line, even
mixed with other parameters which will be preserved after substitution.

      Example: C:Ed [temp] WIDTH=64

   this line will execute the editor Ed with a 64 columns wide display and a
'temp' filename if no icon is selected, otherwise the selected icon will
be edited.
   Note that you can also set <default_params> to a null string, i.e. '[]',
and in this case no default values will be passed if you don't select
an icon ( similar to the AmigaDOS command 'alias' ).


-2.4.2- Multiple icon parameters

   If more than one icon is selected when the menu item is activated, all
the icons will be passed in as parameters in the following way: the first
icon's volume:path/name gets substituted and the command line is executed; if
the execution mode is synchronous AddTools waits for the program execution
to complete, then it substitutes the second icon, executes the resulting
command line and so on until all icons are processed. If asynchronous mode is
set, AddTools will immediately continue substituting icons and executing
command lines: this way you will get every icon concurrently processed by
its own copy of the program associated with the menu item.
   From version 1.10 you can specify more than one [<default_params>] string
in the command line. In this way the first icon you selected will be substituted
in place of the first parameter, the second icon in place of the second parameter
and so on. If the number of icons selected is greater than the number of
parameters, this process is repeated - immediately if synchronous mode is set,
when the program returns, otherwise - on a new copy of the command line, until
all icons are processed.

                           3. Terminating AddTools
                           -----------------------

You can execute as many copies of AddTools as you want, but to remove one or
more of them (and the associated menu items) from the memory you can
select the appropriate 'AddTools ...' menu item (if enabled) and answer 'Yes'
to the subsequent requester. If you launched AddTools from Workbench or
through the WBStartup drawer, you can also terminate AddTools by sending a
BREAK signal (CTRL-C) through a task utility (such as TaskX by Steve Tibbett).
If, on the other hand, AddTools was run from a CLI you can use the
following procedure:

   1) Open a CLI
   2) Issue the 'STATUS' command and note the process number of AddTools
   3) Issue 'BREAK <n> C' where <n> is the process number noted above


                         4. Criticism and suggestions
                         ----------------------------

   I hope you will find AddTools useful, and if you have any criticism,
suggestions, bug report, ideas for enhancements in possible future versions,
you can write ( in Italian or English ) at the following address:

        Alessandro Sala
        Via A. Grandi, 16
        20014 Nerviano (MI)
        Italy

	If you have E-Mail capability you can also contact me at the following
Internet address (at least until the end of February 1994):

        tser1506@cdc835.cdc.polimi.it

                                                  Thank you

**********************************************************************************
                                    History
**********************************************************************************

------------
Version 1.20
------------

  --  New BREAK_WARN tooltype: if set, AddTools will open a requester to warn
you whenever it receives a control-c signal.

  --  New EXTRA_ITEM tooltype: AddTools will add the 'AddTools...' item to the
tools menu only if this tooltype is set.

  --  New WINDOW= tooltype, allowing you to configure the default output window
for the programs you run using the tools menu (Doug Hart inspired me with
this and the following feature).

  --  Added the ability to individually configure the output window for
every menu item.


------------
Version 1.11
------------

  --  Corrected various mistakes in English inside this file ( further
corrections in the next version !!! ).

  --  In version 1.00 there was a limit of 10 menu items: now it has been
removed.

  --  Using synchronous items no longer locks AddTools until all parameters have
been processed. Now there is an independent task handling synchronous items.

  --  Now supports localization if you have OS 2.1 or later; currently
supported languages are:
                         English (built-in)
                         Italian

  --  If you choose an item with less than 2 icons selected ( that is 1 or
none ) it will now run in asynchronous mode regardless of the sync/async
flag.

  --  New menu item, named 'AddTools...', automatically added at the end of user
items to allow simpler termination of AddTools.

  --  Fixed a bug in icon parameters handling code: if an item had default
parameters inside the '[]', the command line after the ']' was ignored.

  --  Added support for multiple '[<default_params>]' strings in a single
command line.


------------
Version 1.10
------------

     Internal beta version ( never released ).


------------
Version 1.00
------------

     First release!
