Short: TTX help-key macro for ARexxGuide Architecture: generic 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.