This ARexx macro for TurboText must be used in conjunction with
ARexxGuide, a shareware hypertext manual. It gives a quick online
reference to the syntax of ARexx functions and instruction keywords.
Pressing the help key when the cursor is positioned on any word or
character with a special meaning in ARexx will bring up an AmigaGuide
window with information about the instruction keyword, function, or
operator character.
The library rexxarplib.library may be used with this macro to open a
requester that lists information about a word that is not recognized.
rexxarplib.library IS NOT REQUIRED, however. If two comment tokens are
removed from the code, the rexxarplib requester will not be shown.
Instructions for making that alteration are included in the macro.
-------------------------------------------------------------------------
SETUP:
The macro ARx_Help.TTX should be moved to your REXX: directory. The file
ARx_Guide.xref should be moved to the directory where the other files in
the ARexxGuide archive are stored. There may already be a file of that
name in the directory (it was included in the Extras drawer of the
original archive). This version is more complete and should replace the
original.
Finally, TurboText must be told about the macro so that you can use it
easily when editing an ARexx script. That is done through one of
TurboText's definitions files, which are located by default in the
TurboText:Support directory. These files allow the user to customize the
way TurboText handles certain keys, menus, and other aspects of the
program. A macro can be attached to any key, for example.
Consult the TTX manual, Chapter 9, for more information about definitions
files.
The file that is automatically loaded when TurboText begins is called
TTX_Startup.dfn. That file should be changed if you want the ARexxGuide
help key available whenever you run TurboText. It is also possible to
install the help key only when needed. Both methods are described below:
Automatic help-key
~~~~~~~~~~~~~~~~~~~~
Add the following lines to the section labeled KEYBOARD: in the file
TTX_Startup.dfn.
HELP ExecARexxMacro "ARx_Help" SYNC
SHIFT-HELP ExecARexxMacro "ARx_Help" ASYNC
You may wish to use another qualifier-key, like CTRL or ALT. The wide
range of choices for qualifier keys are described in the file
TTX_Standard.dfn at about line 129.
The parameters 'SYNC' and 'ASYNC' determine how the macro will treat
previously opened windows under v34 of the AmigaGuide utility. If 'SYNC'
is specified, the the macro will load the current node into a window
previously opened by the macro. It will bring the window to the front of
the screen. The 'ASYNC' options causes v34 to open a new window each
time the help key is pressed.
A new window is always opened when MultiView is used as the display
utility since the macro has no way to know if a previous window is
available.
Explicit loading of help-key definition
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
If you'd rather not have the help-key defined at all times, you can use
the file TTX_ARexxHelp.dfn, to define the help key only when needed.
Place that file in the TurboText:Support directory and load it by
choosing the menu item Prefs/Open Defs. It will alter the current
definition for the Help and Shift-Help keys, but will not affect other
definitions.
To return to the standard definition, choose TTX_Startup.dfn from the
Prefs/Open Defs menu.
-------------------------------------------------------------------------
HOW IT WORKS:
In the list below the { ^ } character is used to indicate the
position of the cursor when the help key is pressed. The notes
after the { :: } characters explain what the macro will display.
-------
if abbrev(strip(upper(Info)), 'SHOW') then do
^
:: A requester will present information about the clause. It identifies
the clause as an instruction, assignment, command, comment, or null.
-------
if abbrev(strip(upper(Info)), 'SHOW') then do
^
:: The ARexxGuide node for DO will be displayed. If the cursor is located
at an end-of-line blank, it will look for a node matching the last
word in the line. It isn't necessary to enter the () after a function
name to get help for that function. Just type the name and press help.
-------
if abbrev(strip(upper(Info)), 'SHOW') then do
^
:: The ARexxGuide node for the ABBREV() function will appear.
-------
if abbrev(strip(upper(Info)), 'SHOW') then do
^
:: The ARexxGuide node explaining parentheses will appear. Generally,
when the cursor is located on a punctuation mark of some kind, the
node for that character will appear. This is useful when one wishes to
check for valid operator characters.
-------
if abbrev(strip(upper(Info)), 'SHOW') then do
^
:: A requester will identify the current clause as an instruction and
will identify 'Info' as a variable and as a function argument. If a
lookup word is not recognized as an instruction keyword or subkeyword
or as a function name, the macro will attempt to identify how the word
is used in the clause. It recognizes variables, numbers, strings,
function names, function arguments, and more. It will, however, be
confused by a clause that includes multiple levels of quotation marks.
--------
if abbrev(strip(upper(Info)), 'SHOW') then do
^
:: This would normally be identified in a requester as a string, but
since SHOW() is the name of a built-in macro, the macro won't make it
that far. It will display the ARexxGuide node for SHOW(). In general,
the macro will display the node for any word recognized as a function
or instruction name, even if the word is used in a different context
in the clause.
|
aminet net>