/*----------------------------------------------------------------------*/
                             VerCtrl.rexx v1.4

                An AREXX development environment for Opus5

              by Dave Freeman (dfreeman@icecave.apana.org.au)

/*----------------------------------------------------------------------*/


Description:
~~~~~~~~~~~~

The contents of this archive form the basis of my own AREXX development
environment.  It provides a method for creating new projects and for
managing projects under way such that version information is maintained in
an AmigaDOS compliant way (i.e. the AmigaDOS 'Version' command works on my
AREXX scripts).


Requirments:
~~~~~~~~~~~~

To fully install and use the contents of this archive you will need the
following:

         AREXX - part of AmigaDOS since release 2
         DirectoryOpus v5 - I use v5.11
         CygnusEd Text Editor - I use v3.5

While I list these as requirements it would not be difficult to modify the
contents of this archive to suit just about any environment with the
exception of the need to have AREXX to write AREXX scripts.  :)


Installation:
~~~~~~~~~~~~~

I will describe my own setup here.  It should make it fairly obvious what
you will need to change to suit your own particular needs on your own
machine.

1.  Create a directory to store your AREXX projects.  Sub-directories will
be created as required.  i.e.  Work:RexxDev

2.  Move VerCtrl.rexx and RexxProg.rexx to the directory you have just
created.

3.  Copy Images/EdRexx.small to DOpus5:Images (I know, it's not much of an
image - perhaps some artist out there can improve it).

4.  Edit your Lister ToolBar (Menu -> Lister -> Edit Lister Toolbar...) and
add a new button (Add gadget).

5.  Edit the new button you just created.  Add the EdRexx.small button as
the image.

6.  On the LMB I use the following:

    Function:
    ARexx          Work:RexxDev/VerCtrl.rexx (ou) Work:RexxDev
    AmigaDOS       Work:CygnusEd/Ed {f}

    Flags:         CD source
                   No file quote

7.  On the RMB I use the following:

    Function:
    ARexx          Work:RexxDev/VerCtrl.rexx {RsEnter New AREXX Project
                                               name...:Test.rexx} Work:RexxDev
    AmigaDOS       Work:CygnusEd/Ed `GetENV RexxDev.File`
    AmigaDOS       UnSetENV RexxDev.File

    Flags:         CD source
                   No file quote
                   Rescan source

8.  That's pretty much it for my standard installation.


What it does:
~~~~~~~~~~~~~

VerCtrl.rexx is the main control script.  It takes two arguments.  The
first argument is the name of the file to edit (it does not _have_ to end
in '.rexx' but '.rexx' will be added to it automatically).  The second
argument is the path that you setup to store your AREXX projects (I am
going to refer to this as Work:RexxDev for the rest of the document for
ease of explanation - anywhere you see 'Work:RexxDev' just substitute your
own path).

When VerCtrl.rexx is invoked it will first look for a file in Work:RexxDev.
If a file of the correct name is not found in that directory it will then
look for a directory in Work:RexxDev of the name you requested (without any
'.rexx' extension if you provided it that way).  If it finds the directory
it will work on the arexx script in that directory (at the moment, the
directory and AREXX script _in_ that directory will have the same name with
a '.rexx' extension on the AREXX script - I'm working on a usefull way of
chainging this).  If a relevant directory is not found then a new project
will be created using the name you gave for the dir name and a new AREXX
script will be created in that directory.

It is the creation of this new AREXX script that Work:RexxDev/RexxProg.rexx
is used for.  This is the script that forms the basis for most of the AREXX
scripts that I write.  It contains elements that I like to have in all of
my AREXX scripts.  If you always want to include other items in your AREXX
script then add them to this file.  You can change anything you like in the
script except the following line:

 *  $VER: 

In the provided example, this is line 3.  It should also be noted that if
you change anything in the comments section you should ensure that the
overall commented nature of the section from line 1 to line 7 is not
effected.  i.e.  While line 3 is not a commented line of it's own nature,
it exists within a section of commented lines and should remain that way.

In general I would suggest that you make any changes to the comment block
at the start of the program at a point after line 3 and leave line 1 and
line 7 in their current format (just copy line 6 and add comments on a line
similair to that one as required).

When used from Opus5 the final result will be that you can click on an
AREXX script in your development directory tree (and only in the
development directory tree at the moment) and VerCtrl.rexx will search out
the AmigaDOS version string and increment the revision number and set the
date to today's date (assuming your system clock is correct).  It will then
load that file into your text editor ready for you to continue development.

If you want to create a new AREXX project just click on the toolbar button
with the right mouse and it will prompt for a new project name to create.
VerCtrl.rexx will then create the new directory and place a new AREXX
script of the required name in that directory.  The new script will have a
valid AmigaDOS version string and will contain whatever you have in the
'shell' AREXX script 'Work:RexxDev'RexxProg.rexx'.

Limitations:
~~~~~~~~~~~~

The current setup requires a fairly strict hierarchy of directories within
your development directory path.  I am working on a way to improve this at
the moment.  I see it as a 'good thing' (tm) to keep development scripts in
a directory of it's own anyway since this helps to keep bits together and
leaves a logical point to create a distribution archive or store
documentation and development notes or other ancilliary files associated
with that project that may change regularly while development continues.

There is currently no allowance made for AREXX scripts that do not have a
'.rexx' extension or that have some other extension.  I am working on a fix
for this as well.


Feedback:
~~~~~~~~~

If you have any suggestions or ideas on this project please feel free to
get in touch.  I'll implement anything that looks like a good idea to me.
<grin>  Development work is ongoing as this is the environment that I
currently use to write my own AREXX scripts and as and when I see a way to
enhance the setup I make the required alterations.

I can be reached in the following ways:

      Usenet:    dfreeman@icecave.apana.org.au (Preferred)
                 dfreeman@peg.apc.org (If the above does not work)

         IRC:    dfreeman (If you happen to see me - I'm not on all that
                           often)

     FIDONet:    3:640/535  - Dave Freeman
    AmigaNet:    41:450/533 - Dave Freeman


Distribution:
~~~~~~~~~~~~~

This project is currently freely distributable but I maintain the rights to
the scripts included.  If you alter the function of these scripts in any
way please forward a copy of your changed script to me via one of the above
methods.


History:
~~~~~~~~

v1.6  - Added 'VersStr' variable to provide a way to output a copyright notice.
v1.10 - Added new procedure 'GSay' to provide error responses via a requester.
v1.11 - Changed Date string handling to be more StyleGuide compliant