Ref for TxEd with AREXX!

This set of AREXX macros were inspired by Matt Dillon's 'ref'
command in his DME editor. The idea is to supply on-line help for
any reference that you wish to set up. This feature seems to be
most helpful for getting a reference to a structure from a fully
commented set of include files or a reference to a function from
the autodocs, but is sufficiently powerful to use anyway you see
fit (perhaps a help file for TxEd?). 

Scenario: You are working on your masterpiece and you need to
declare, say, a Border structure. Well, what does that border
structure look like? You could pull out some reference work or open
up another edit window and examine 'intuition.h' directly. Or you
could use REF. Just position the cursor anywhere on the word
'border' and call the REF program (put it in a menu if you like). A
new Txed window will appear containing the border structure as
defined in 'intuition.h'.

Reality: Of course it isn't QUITE that simple, a little work will
be needed beforehand. The first thing you have to do is set up a
reference file that tells REF where to find the needed reference,
but that is not so hard. REF assumes the file will be in your 's:'
directory under the name 'TxEd.ref'. Open the 'intuition.h' file. A
nasty technicality here: TxEd will not tell AREXX what directory it
is in UNLESS that directory appears in the TxEd file requestor
directory gadget, so be sure to open the file that way rather that
changing to the include:intuiton directory, then editing. Assuming
you have done so, simply move the cursor to the first line of the
border structure definition. Now execute the AREXX macro 'markit
border'. This tells the REF system that you wish to enter a new
reference into TxEd.ref to serve as a reference for the word
'border'. Markit will write the reference word (border), the file
name and directory, and the beginning line (current cursor line) to
the file s:TxEd.ref. Now move the cursor to the last line of the
border definition and execute the AREXX macro 'endit'. Endit will
finish this entry into s:TxEd.ref' by writing the ending line to
the file. Now, whenever you execute 'ref' with the cursor anywhere
on the word 'border' in any file, you will recieve a new TxEd
window with the border definition in it (or whatever was between
the cursor positions when you executed markit and endit). This is
so easy that you will probably just go through the common include
files marking references for windows, screens, requestors, etc.

Of course you can do this for any word. So if you have the
autodocs, you may wish to do this for functions as well. The
process is quite simple. A word of warning: Markit and endit are
rather simple minded, so you could easily corrupt your TxEd.ref
file by not executing them in pairs. If this happens, don't panic!
TxEd.ref is a simple text file that you can easily fix. Each line
has the following format:

REFWORD  REFFILE @beginline@endline@

just delete the offending line or fix it by hand.

This version of ref works pretty fast, but the larger your txed.ref
file, the longer it will take the program to find your reference.
For this reason it is a good idea to enter only as many references
as necessary and to keep the most common ones near the top of the
file. Early versions of ref attempted to use AREXX to cull out
unwanted portions of the reference file and were painfully slow.
Now that I saw the light and let TxEd jump, mark, and cut commands
handle that, the program seems very fast to me. Your mileage may
vary, but the suggestions above should keep the program running
pretty fast.

Additional feature : If you specify a reference word on the command
line with ref, eg. 'REF WINDOW', then that word will be used in
lieu of the word under the cursor. This allows you to reference
words without having them appear in your file or having to move the
cursor to them, and is also slightly faster.

Needed resources:

   TxEd Plus program of course!
   AREXX program (I haven't tried this with the AREXX sample that
comes with the TxEd Plus program, but am sure it requires full
AREXX.
   ref.txed - the main macro
   lookitup.txed - called by ref.txed to handle new TxEd window.
   markit.txed - begins reference definition
   endit.txed - finishes reference definition

Endit would make a good addition to the menu or a macro key. Ref
could also be used this way, but you will need to execute if from
the command window if you wish to supply a reference word instead
of using the one at the cursor. Markit would not work as a menu
item unless you modify it to somehow pull the reference word from
the user. Lookitup should not be called directly by the user.

The programs could probably be greatly improved. This is my first
real AREXX program, so I am sure that I did a lot of things the
hard way. The program has gone through some major changes as I
found things in the AREXX manual that made my life easier. Feel
free to hack it up like you want it. I have just scratched the
surface of how powerful the AREXX/TxEd combination will prove to
be. If you aren't using AREXX and TxEd, then I highly recommend it.
WShell has also been quite helpful in developement.

These macros are freeware. If you think they are good enough to pay
for, then why not send in your money for ConMan or ASDG's
recoverable ram disk - those guys work harder than I do! Use them,
modify them, just don't sell them. If you make changes or have some
suggestions, comments, or bug reports, how about dropping me a note
at

James Gary
5202 Vassar Ave.
Louisville, KY 40258

I don't promise to support the software, but am interested enough
to take your suggestions seriously. 

Special thanks to William Hawes for producing such wonderful
products as ConMan, AREXX, and WShell and for taking time out from
SELLING his stuff at Ami-Expo in Chicago to talk to me about AREXX
programming when I had already purchased the product!

I just realized this: ref will work without txed. Just type 
'rx ref.txed REFWORD' and you will get a TxEd window with your 
reference in it. Be sure to supply REFWORD or you will get some commands
sent to the CLI that it won't understand. I just love it when
a plan comes together! -JeG