Club Amiga de Montreal - CAM/CAM_CD_1.iso/files/164.lha/ARexx/RefMacro_ARexx/README.ref

Text File | 1988-04-28 | 5.4 KB | 107 lines

                REFERENCE - An ARexx macro for TxEd Plus
                ========================================
                    (if it looks icky set tabs to 4)
        ( THIS MACRO PACKAGE REQUIRES THE COMPLETE AREXX SYSTEM )

    Reference will add an online lookup facility to TxEd Plus.  The
command structure and execution is functionally similar to the REFS
command in Matt Dillon's DME editor.  It allows the selective viewing
of text based on a keyword specified in the file currently being edited.
The macro will extract the current word (the one under the cursor) and
attempt to look it up.  If the keyword is found, another TxEd window will
be opened to allow viewing of the associated text.  If it is not found,
an error message will be presented for your perusal.

The referencing macro consists basically of three parts:
1) the ARexx code, which drives the system,
2) the C program GetRefs which extracts the text, and
3) the reference file TxEd.refs which specifies the location of
    the referenced text.

1) ARexx code:
    The ARexx part of the referencing system comes in two parts,
    reference.txed and startup.txed.  Reference.txed is a standalone
    macro, while startup.txed must be added to your TxEd startup macro.
    At a glance, these work as follows: you assign a macro to execute
    reference.txed.  Reference.txed begins by copying the word at the
    current cursor location to the macro +X (which is essentially a
    scratch buffer) and then retreives the text (by a status call).
    This is the key to search on.  It then executes the c program GetRefs
    which will extract the desired text if it exists.  If GetRefs
    succeeds, Reference.txed will define the constant Reference in the
    cliplist and start another TxEd process.  The new process checks to
    see if Reference is defined (in it's startup macro).  If Reference
    exists, the new process replaces the value of Reference with it's
    own ARexx port address.  Meanwhile, Reference.txed has waited a
    sufficient (?) amount of time for it's child to come to life.  It then
    retreives the child's address from the Cliplist and undefines the
    variable Reference.  Then it sends several messages to both the
    child and the original TxEd process, moving windows, loading text
    etc.  Then the ram scratch file is deleted (to be nice and neat).
    The macro then exits, leaving the original TxEd as the active
    window.

2) GetRefs
    This is a fairly simple C program that accepts one command line
    argument, which is the keyword to search for.  It attempts to open
    the text file TxEd.refs in df1:s,df0:s,ram:s in that order.  If it
    succeeds, it searches for the keyword.  If the keyword is found, it
    gets the search file name and the start and end text from the .refs
    file.  Then it opens the search file, searches for the start text
    and (if it exists) copies all text between the start text and the
    end text to a scratch file in ram.  (Specifically, to ram:extract.txt)

    There is much room for improvement in this program which is why I
    included the source code.  I have taken very little time to optimize
    it, but then, I started out writing it in ARexx which was much slower
    than C.  Currently, a worst case reference extraction takes about
    30 seconds, but there is a lot of text to search (about 15K of
    TxEd.reference, then who knows how much in the search file).  I have
    not benchmarked this extensively, it's fast enough for the moment.

3) TxEd.refs
    This is an ascii text file which defines the valid keywords.  It has
    a format like this:
    Keyword        "end string"    search-file-name    "start string"
    where search-file-name is the file (complete path please) that contains
    the explanatory text for keyword.  This text is located in the file
    between the start and end strings inclusive.  As an example, I have
    included two TxEd.refs files, one from my autodocs disk and one from
    my commented includes disk.  It is possible to have more than one
    TxEd.refs file, but currently they must be on different disks (logically
    enough, I put them in an S directory on the disk that contains the
    search files)

    The start string must be a regular printable ascii string, no control
    characters or newlines are allowed.  The quotes are optional, but if
    the string contains any whitespace they must be included.  The same
    rules apply for the end string, except that an end string of "^L"
    will be taken to mean 'stop at the next formfeed'.  This is handy for
    referencing the autodocs.


To run the system, rename the file refer.txed -> reference.txed and
put it in the REXX: directory.  Add the lines in startup.txed to your
TxEd startup macro.  Put getrefs in the C: directory.  Make your
TxEd.refs file in the appropriate form and put it in the s directory
of the reference disk.  (Feel free to use mine, just rename the appropriate
file as TxEd.refs and be sure that the filenames agree with those on
your autodocs or includes disks - then put the .ref file in the s directory
of the appropriate disk).  You can change the macro assignment for
referencing if you wish, I currently have it assigned to F3.
When all this is done, just run txed, move the cursor to the word that
you wish to reference and hit the F3 key.  Away you go...

Well, that's about it I guess, change what you want, keep the rest
or chuck the whole mess.  Hope you find it useful, I certainly do.
It adds a very nice feature to a marvelous editor and ARexx is a
pleasure to use (Thanks cheath and whawes).

If you have any problems, please let me know. (suggestions also)

John Hardie
BIX: jhardie
USENET: [e-mail]