home *** CD-ROM | disk | FTP | other *** search
/ World of A1200 / World_Of_A1200.iso / programs / text / textra / docs / rexxcommand.doc next >
Text File  |  1995-02-27  |  27KB  |  864 lines
  1.  
  2.  
  3.          TREXXTRA, The TEXTRA-to-ARexx Command Interface!
  4.  
  5.             (The mother-of-all-concatenated-names!!!)
  6.  
  7.                  again, by Mike Haas  (who else?)
  8.  
  9.  
  10.  
  11.     *** Many THANX to Martin Kees, who generously contributed ***
  12.            his AREXX interface design and implementation.
  13.     
  14.        And to youse guys at Commodore-Amiga, for the obvious.
  15.  
  16.  
  17.     This document describes the TEXTRA commands that may be placed 
  18.     within ARexx scripts and launched from within TEXTRA via the 
  19.     "Utilities, AREXX..." menu item or key-equivalent.
  20.  
  21.     TEXTRA introduced its ARexx interface in v1.10.  I'll make every 
  22.     attempt to keep later versions backward-compatible and NOT break 
  23.     any existing scripts later on.
  24.     
  25.     This document describes the feature set of Textra Version 1.13.
  26.     A complete Revision History for the ARexx interface is at end
  27.     of this document.
  28.     
  29.           
  30. A Quick example...
  31.  
  32. Before trying anything, copy the provided TEXTRA ARexx script
  33. files, the ones in the provided "Scripts" directory, into your
  34. rexx: directory.  The provided Textra_Install program will do that
  35. for you automatically.  (This need be done only once and completes
  36. the TEXTRA AREXX Interface installation on your system.)
  37.  
  38. (Alternatively, you could temporarily assign rexx: to the Scripts 
  39. directory.  If necessary, refer to your Amiga System Manuals for 
  40. information about any of these operations.)
  41.  
  42. Launch TEXTRA by double-clicking on it's icon and click on the
  43. 'CANCEL' button on the file requester.
  44.  
  45. Pull-down the "Utilities, AREXX..." menu item and, if not already 
  46. present, enter  Tutorial  into one of the string gadgets and press 
  47. RETURN.  (Note: you can clear one first with Rt-Amiga-X, if 
  48. necessary).
  49.  
  50. Please feel free to use the provided scripts as a basis for developing 
  51. your own ARexx programs, if you are inclined to such things.  If you 
  52. do, and can see your way clear, please send me a copy of your stuff...  
  53. if you wish it to be included in the standard release package, include 
  54. asigned statement to that effect, OK?
  55.  
  56. Mike Haas
  57. 3867 La Colina Rd.
  58. El Sobrante, CA. 94803
  59.  
  60.  
  61.  
  62. AREXX Scripts containing the TEXTRA commands described in 
  63. this file may reside in either of 2 places:
  64.  
  65.     1. The REXX: directory (if you have one ASSIGNed)
  66.     
  67.                         OR
  68.  
  69.     2. The Textra "startup" directory...
  70.     
  71.        a. If you launch TEXTRA from Workbench, this is the same
  72.           directory that TEXTRA is in.
  73.        
  74.        b. If you run TEXTRA from CLI/Shell, this is the "current
  75.           directory" of the CLI/Shell when you launch Textra.
  76.     
  77.  
  78.  
  79. Notes about TEXTRA Command Invocations from ARexx scripts...
  80.  
  81. 1. When specifying strings in TEXTRA commands, encase them 
  82.    in double-quotes, even if there is no whitespace.  
  83.    (Otherwise, ARexx will convert all your characters to 
  84.    UPPER case.  Nice of it, huh?)
  85.  
  86. 2. Script usage is case-INsensitive for the TEXTRA commands 
  87.    and keyword-matching.
  88.  
  89. 3. TEXTRA will sometimes set combinations of 2 pre-defined 
  90.    AREXX variables, RESULT and RC (return code).  Both are 
  91.    strings, RESULT being primarily informational in nature 
  92.    and RC used for error situation return values 
  93.    ('out-of-range value' or 'not found' type error codes).
  94.    
  95.    Note that to retrieve the RESULT string, if used, the 
  96.    AREXX program must have declared OPTIONS RESULTS 
  97.    somewhere previously.  RC is always available and TEXTRA 
  98.    will return 0 in it for a SUCCESS condition or a non-zero 
  99.    value (5 is considered a minor condition, 10 is the more 
  100.    serious type, etc.).
  101.    
  102.    
  103. The remainder of this document is divided into the following
  104. sections, each describing commands related to that topic...
  105.  
  106.    Movement commands
  107.    Set Selected Area
  108.    Operations on Selected Areas
  109.    Interactive Control
  110.    File/Window Management
  111.  
  112. There is some overlap to the functionality of these sections,
  113. so if you're looking for a specific capability, scan everything.
  114.  
  115. The commands themselves...
  116.  
  117.  
  118.  ===================================================================
  119.  Movement Commands
  120.  ===================================================================
  121.  
  122.  
  123.  GOTOXY x y            move cursor to x y position
  124.  
  125.     Place the cursor to the given 'x y' coordinates, where
  126.     'x' is the decimal column position (strting with 0) and 'y'
  127.     is the decimal line number (starting with 0).
  128.     
  129.     'rc' set to:
  130.     
  131.      0 = 'x y' within range of text
  132.      5 = 'x' too large (cursor positioned to end-of-line)
  133.     10 = 'y' too large (no change in cursor/selection)
  134.  
  135.  
  136.  UP   n                cursor up n lines
  137.  
  138.     'rc' set to:
  139.     
  140.      0 = cursor position was successfully changed by at least 1 line
  141.      5 = cursor was at top line to begin with
  142.      
  143.      
  144.  DOWN n                cursor down n lines
  145.  
  146.     'rc' set to:
  147.     
  148.      0 = cursor position was successfully changed by at least 1 line
  149.      5 = cursor was at bottom line to begin with
  150.      
  151.      
  152.  RIGHT n            cursor right n characters
  153.  
  154.     'rc' set to:
  155.     
  156.      0 = cursor position was successfully changed by at least 1 column
  157.      5 = cursor was at last character in file to begin with
  158.      
  159.      
  160.  LEFT  n            cursor left  n characters
  161.  
  162.     'rc' set to:
  163.     
  164.      0 = cursor position was successfully changed by at least 1 column
  165.      5 = cursor was at first character in file to begin with
  166.      
  167.      
  168.  FIRSTLINE        cursor to beg of file (rc always = 0)
  169.   
  170.  
  171.  LASTLINE        cursor to end of file (rc always = 0)
  172.  
  173.  
  174.  TOP            cursor up to topline of visable page (rc always = 0)
  175.  
  176.  
  177.  BOTTOM            cursor to bottom line of visable page (rc always = 0)
  178.  
  179.  
  180.  CENTER            cursor to middle line (rc always = 0)
  181.  
  182.  
  183.  HOPTO next word    cursor to start of next word
  184.  HOPTO prev word    cursor to END of prev word
  185.  HOPTO next char    cursor to next non-white
  186.  HOPTO prev char     cursor to prev non-white
  187.  HOPTO next blank     cursor to next whitespace char
  188.  HOPTO prev blank     cursor to prev whitespace char
  189.  
  190.     HOPTO moves the cursor to a specific position relative to the
  191.     current cursor or selection location.  The direction and
  192.     ultimate destination position is determined by the keywords
  193.     provided.
  194.     
  195.     HOPTO observes the current setting of the PREFS attribute
  196.     'AlphanumericHops' (see the PREFS command) to determine how it
  197.     skips over characters and words.
  198.     
  199.     'rc' set to:
  200.     
  201.      0 = SUCCESS
  202.     10 = keywords supplied to HOPTO were invalid
  203.      
  204.     if 'rc' = 0, 'result' set to:
  205.     
  206.      "<number>" = cursor column
  207.     "NOT FOUND" = could not HOPTO (at one end of file)
  208.      
  209.  
  210.  
  211.  ===================================================================
  212.  Set Selected Area
  213.  ===================================================================
  214.  
  215.  
  216.  SELECTLINE n        select and display line n
  217.  
  218.     Same as the 'Go to Line...' menu item.  No effect if 'line n'
  219.     is not both a valid decimal number and in range for the file.
  220.     (rc always = 0)
  221.  
  222.  
  223.  FIND "text"        find "text", observe wrap setting
  224.  
  225.     Find and select the specified text.  The search is case-INsensitive.
  226.     
  227.     'result' set to:
  228.     
  229.            "OK" = text has been located, selected and displayed
  230.     "NOT FOUND" = could not be found
  231.     
  232.     (rc always = 0)
  233.  
  234.  
  235.  FINDNEXT
  236.  
  237.     Conducts another search for the same string, see FIND.
  238.  
  239.  
  240.  SELECTTO x y
  241.  
  242.     Used to establish or modify a select range as follows:
  243.     
  244.     - If 'x y' is below the current cursor location or start
  245.       of selection,    'x y' then becomes the new start of selection.
  246.     
  247.     - If 'x y' is after the current cursor location or end of
  248.       selection, 'x y' then becomes the new end of selection.
  249.     
  250.     - If 'x y' is within the current selection, then 'x y' becomes
  251.       the new end of selection.
  252.  
  253.     (rc always = 0)
  254.  
  255.  
  256.  HOPSELECT next word
  257.  HOPSELECT prev word
  258.  HOPSELECT next char
  259.  HOPSELECT prev char
  260.  
  261.     HOPSELECT establishes a selection relative to the current
  262.     cursor or selection location.  The direction and destination
  263.     selection is determined by the keywords    provided.
  264.  
  265.     HOPSELECT observes the current setting of the PREFS attribute
  266.     'AlphanumericHops' (see the PREFS command) to determine how it
  267.     selects characters and words.
  268.     
  269.     'rc' set to:
  270.     
  271.      0 = SUCCESS
  272.     10 = keywords supplied to HOPSELECT were invalid
  273.      
  274.     if 'rc' = 0, 'result' set to:
  275.     
  276.      "<number>" = length of selected string
  277.     "NOT FOUND" = could not HOPSELECT (at one end of file)
  278.      
  279.  
  280.  UNSELECT          make sure nothing is selected
  281.  
  282.     If there is a selection, place the cursor at the end of it.
  283.     No effect if nothing selected.
  284.     (rc always = 0)
  285.  
  286.  
  287.  ===================================================================
  288.  Operations on Selected Areas
  289.  ===================================================================
  290.  
  291.  
  292.  CUT
  293.  
  294.     Same as the 'CUT' menu item.  No effect if nothing selected.
  295.     (rc always = 0)
  296.  
  297.  
  298.  COPY
  299.  
  300.     Same as the 'COPY' menu item.  No effect if nothing selected.
  301.     (rc always = 0)
  302.  
  303.  
  304.  PASTE
  305.  
  306.     Same as the 'PASTE' menu item.  No effect if nothing has been
  307.     CUT or COPY'ed. (rc always = 0)
  308.  
  309.  
  310.  KILLSELECT
  311.  
  312.     If a select range exists, delete it.  Do NOT save it in the
  313.     TEXTRA clipboard.  (rc always = 0)
  314.  
  315.     'result' set to:
  316.     
  317.     "OK" if a select range existed.  The cursor will now reside
  318.          where the select range previously began. 
  319.     
  320.     "NO SELECT" = There is no selection.  (nothing is changed)
  321.  
  322.  
  323.  LOCASE
  324.  
  325.     Selected or next word to lower case. (rc always = 0)
  326.  
  327.  
  328.  HICASE
  329.  
  330.     Selected or next word to upper case. (rc always = 0)
  331.  
  332.  
  333.  CAPS
  334.  
  335.     Capitalize the selected or next word. (rc always = 0)
  336.  
  337.  
  338.  ===================================================================
  339.  INTERACTIVE Control
  340.  ===================================================================
  341.  
  342.  
  343.  TEXT token
  344.  
  345.     Inserts the 'token' into the current window at the current
  346.     cursor location.  If a select range exists, it is deleted
  347.     before the insertion. (rc always = 0)
  348.  
  349.  
  350.  TEXTN token
  351.  
  352.     Same as TEXT, but includes a newline after the specified string.
  353.     (rc always = 0)
  354.  
  355.  
  356.  NEWLINE
  357.  
  358.     Inserts a newline into the current window at the current
  359.     cursor location.  If a select range exists, it is deleted
  360.     before the insertion. (rc always = 0)
  361.  
  362.  
  363.  BACKSPACE
  364.  
  365.     Same behavior as the BackSpace key on the keyboard.
  366.     (rc always = 0)
  367.  
  368.  
  369.  DEL
  370.  
  371.     Same behavior as the DEL key on the keyboard.
  372.     (rc always = 0)
  373.  
  374.  
  375.  PREFS attribute action
  376.  
  377.     Perform an action to the specified Edit or Printing Preferences
  378.     attribute.  The action may be to either read and return the
  379.     current setting of the attribute, or set it.
  380.     
  381.     The valid attribute keywords are listed here, along with the
  382.     appropriate action keywords for each...
  383.  
  384.     Usage:   PREFS [AutoIndent]        [read on off]
  385.                    [AutoBackspace]     [read on off]
  386.                    [PrintLineNumbers]  [read on off]
  387.                    [PrintPageHeaders]  [read on off]
  388.                    [TabWidth]          [read <value>]
  389.                    [ConvertCRLF]       [read on off]
  390.                    [Alphanumeric]      [read on off]
  391.                    [AlphanumericHops]  [read on off]
  392.     
  393.     If the action is 'read', the returned string will either be
  394.     "ON", "OFF", or "<value>", depending on whether the attribute
  395.     is a 'state' or 'numeric' variable.
  396.     
  397.     example:   PREFS AutoIndent read
  398.                AIstatus = result    /* should be ON or OFF */
  399.                
  400.     If the action is to set the attribute, then the action keyword
  401.     will be either "ON", "OFF" or "<value>", depending on whether
  402.     the attribute is a 'state' or 'numeric' variable.  If the
  403.     attribute is successfully set, the string "OK" will be returned.
  404.     
  405.     NOTE: setting the    PREFS Alphanumeric  attribute to 'off'
  406.           automatically infers the 'Non-Whitespace" mode of selecting
  407.           text on double-click mouse events.
  408.     
  409.     NOTE: the    PREFS AlphanumericHops [read on off]   attribute,
  410.           determines how the HOPTO and HOPSELECT commands will look
  411.           at text. Turning this attribute off automatically infers
  412.           the 'Non-Whitespace" mode of parsing text.
  413.     
  414.     examples:   PREFS AutoIndent on
  415.                 AIstatus = result    /* should be OK */
  416.                 
  417.                 PREFS TabWidth read
  418.                 notify result
  419.  
  420.     'rc' set to:
  421.     
  422.      0 = SUCCESS
  423.     10 = keywords supplied to PREFS were invalid
  424.      
  425.     if 'rc' = 0 and action is "read", 'result' set to:
  426.     
  427.         "<number>" = if requested attribute is numeric in nature
  428.      "ON" or "OFF" = if requested attribute is a 'state'
  429.      
  430.  
  431.  GET item attribute
  432.  
  433.     GET is used to aquire information about a certain 'attribute'
  434.     of a particular 'item'.
  435.  
  436.     'rc' set to:
  437.     
  438.      0 = SUCCESS
  439.     10 = keywords supplied to GET were invalid
  440.     
  441.     Assuming the given keyword pairs are valid (in the following list),
  442.     'result' will be set as indicated.
  443.  
  444.     A brief summary of the available reports:
  445.     
  446.     GET cursor position    - report column & line of cursor
  447.     GET cursor char        - report character at cursor position
  448.     GET file name        - get just the filename (no path)
  449.     GET file path        - get just the file path (no name)
  450.     GET line <num>        - return text of line
  451.     GET select position    - return start and end points of select range
  452.     GET select text        - return the string that is selected
  453.     GET select next        - used after 'get select text' to get later lines
  454.     
  455.     Specific info about each command...
  456.  
  457.     GET    cursor position
  458.     
  459.         'result' set to:
  460.         
  461.         "x y" = column & line numbers, both 0-based (ex: "0 13"
  462.                 to indicate first column of the fourteenth line).
  463.                 Use "PARSE var result col ' ' line" in AREXX scripts.
  464.         
  465.         "SELECT" = There is no cursor (a selection exists).
  466.     
  467.     GET    cursor char
  468.     
  469.         'result' set to:
  470.         
  471.         "c" = a single-character string (or "-1" if on empty line)
  472.         
  473.         "SELECT" = There is no cursor as a selection exists.
  474.         
  475.     GET    file name        'result' set to "filename"
  476.     
  477.     GET    file path        'result' set to "vol:dir/" or "vol:" format
  478.     
  479.     GET    line <num>
  480.     
  481.         'rc' set to:
  482.         
  483.         10 = <num> is too large (the specified line doesn't exist),
  484.     
  485.         otherwise, 'result' set to:
  486.         
  487.         "line text" = contents of line <num>
  488.         
  489.     GET    select position
  490.     
  491.         'result' set to:
  492.         
  493.         "startx starty endx endy" = select range coordinates.
  494.         
  495.             (For example, "0 0 2 4" indicates that from the first
  496.              column of the first line to the third column of the fifth
  497.              line is selected.  From AREXX, use:
  498.              "PARSE var result ' ' startx ' ' starty ' ' endx ' ' endy")
  499.         
  500.         "NO SELECT" = There is no selection.
  501.         
  502.     GET    select text        "(num) selected text"  |  "NO SELECT"
  503.     
  504.         Used to retrieve the current selection, or at least
  505.         the component of it that is on the first line.  The
  506.         first portion of the returned string is always the number
  507.         of remaining lines that can be returned via "GET select next".
  508.         This number is always followed by a SPACE character, then the
  509.         selected text on that line.
  510.         
  511.         For example, if "0 Four score" is returned, the caller knows
  512.         that the selection does not extend over 1 line and that the
  513.         selected text is "Four Score".
  514.         
  515.         If "1 seven years ago," is returned, the caller knows
  516.         that the selected text is "seven years ago," and that
  517.         the selection extends over to the next line (see
  518.         "GET select next").
  519.         
  520.         'result' set to:
  521.         
  522.         "<num> selected text" = <num> is number of times to call
  523.                                 "GET select next" (separated by a
  524.                                 SPACE character from the text).
  525.         
  526.         "NO SELECT" = no selection currently exists.
  527.  
  528.     GET    select next        "numleft selected text"  |  "NO SELECT"
  529.         
  530.         Used to retrieve remaining lines, if the previous
  531.         "GET select text" indicated it should be called at all.
  532.         It returns the same format string as "GET select text",
  533.         but will return a 'numleft' component that decreases
  534.         by 1 each time, ultimately to zero.
  535.  
  536.         'result' set to:  same as "GET select text"
  537.         
  538.         NOTE: returns just "0" if called past end of selection.
  539.  
  540.  
  541.  WAITFOR num
  542.  
  543.     Wait for 'num' seconds, where 'num' is a decimal number of
  544.     the form "4.36" or "4".  Minimum resolution is .02 seconds,
  545.     and with the speed AREXX operates at, that should be quite
  546.     sufficient!
  547.  
  548.  
  549.  CLEAR
  550.  
  551.     Delete all text from and blank the current window.
  552.  
  553.  
  554.  NOTIFY "token"
  555.  
  556.     Presents a standard informational 'Please Note!' requester
  557.     to the user and waits for him/her to click the single 'OK'
  558.     button.  The token string is presented in the requester
  559.     and should not exceed 60 characters in length.  Does not
  560.     return a result.  rc always = 0.
  561.  
  562.  
  563.  ASK "token"
  564.  
  565.     Presents a standard 'YES/NO' requester to the user and waits
  566.     for him/her to click on a button.  The token string
  567.     is presented in the requester and should not exceed 60
  568.     characters in length.  rc always = 0.
  569.     
  570.     'result' set to:
  571.     
  572.     "YES" or "NO", depending of course on which button was clicked.
  573.  
  574.  
  575.  TEXTRAVERSION   (only in v1.12 and later)
  576.  
  577.     Returns a string describing the TEXTRA major and minor versions, 
  578.     as well as the incremental version of the AREXX interface 
  579.     (increments with each modification to the interface code and/or
  580.     command set).
  581.     
  582.     format:   major-version minor-version rexxinterface
  583.  
  584.     for example:    1            12             2
  585.  
  586.     "1 12 2" will be returned for v1.12, last 2 indicates
  587.              AREXX interface, rev2.  This should increment with
  588.              every addition, deletion, modification, or fix.
  589.     
  590.     "1 13 5" is returned for 1.13
  591.  
  592.     The 3rd digit will never be less than 2, as it was that rev
  593.     which implemted this command.
  594.     
  595.     The commands in the following list have been added since the
  596.     initial V1.10 release (which first incorporated the ARexx
  597.     interface).  For best results, you should check for the highest
  598.     relevant rexx version at the beginning of your script...
  599.     
  600.     min Rexx revision    needed for command
  601.     -----------------    ------------------
  602.             2                OPENFILE
  603.             2                FINDFILE
  604.             2                SELECTWINDOW
  605.             2                SAVEAS
  606.             3                INSERTFILE
  607.             4                CHECKCANCEL
  608.             4                CLOSEWINDOW
  609.             4                RETURNPROMPT
  610.             4                RETURNPROMPTN
  611.             5                PREFS Alphanumeric
  612.             5                PREFS AlphanumericHops
  613.     
  614.     As of V1.13, affected TEXTRA scripts will check that the
  615.     TEXTRA that is calling them is of a compatible version.  To see an
  616.     example of how to do this, refer to any of those.  Just two include
  617.     SLIDE.textra and PARAGRAPH.textra; there are many others.
  618.  
  619.  
  620.  CHECKCANCEL
  621.  
  622.     Checks whether the user wants to cancel the command.  To
  623.     respond accordingly, the programmer should put something like
  624.     this in his/her ".textra" script:
  625.     
  626.        /* Check if the user wants to cancel... */
  627.        CheckCancel; if (result == CANCEL) then exit
  628.     
  629.     Note that the script has the ability to perform specific actions
  630.     before exiting, such as flushing data for example.
  631.     
  632.     'result' set to:
  633.     
  634.     "CANCEL"     The user wants to cancel current operation
  635.     
  636.     "NO"         Do not cancel
  637.  
  638.  
  639.  RETURNPROMPT "string"
  640.  
  641.     Presents the specified string as a prompt, then waits for the user 
  642.     to press the RETURN or ENTER keys.  Until either is pressed, other 
  643.     keys are entered into the document as usual.  (If the specified
  644.     string is entered as "noprompt", none is presented).
  645.  
  646.     When the user presses RETURN, 4 values are returned as the 
  647.     'result' string.  These represent the starting x, y and ending x, 
  648.     y coordinates for the "response".
  649.     
  650.     The response is considered to be either:
  651.     
  652.        - Any selected text.   (OR, if no text is selected...)
  653.        
  654.        - The cursor position when the command was invoked is
  655.          considered the start x, y.  The end x, y is the position
  656.          when the RETURN key was pressed.
  657.  
  658.     'result' set to:
  659.     
  660.     "startx starty endx endy"
  661.     
  662.     This can be retrieved via:
  663.     
  664.        parse var result startx starty endx endy
  665.  
  666.  
  667.  RETURNPROMPTN "string"
  668.  
  669.     Works exactly as does RETURNPROMPT, but also adds a NEWLINE after 
  670.     the prompt is displayed, allowing the response to occupy an entire
  671.     line.
  672.     
  673.     See RETURNPROMPT for all other details.
  674.     
  675.     
  676.  QUITTEXTRA <exit-save-action>
  677.  
  678.     There are 3 possible forms of this command:
  679.  
  680.       QUITTEXTRA prompt   (normal shutdown, prompts if files modified)
  681.       QUITTEXTRA save     (doesn't prompt, always saves modified files)
  682.       QUITTEXTRA nosave   (doesn't prompt, doesn't save modified files)
  683.  
  684.     NOTE: The last two forms of this command have special user
  685.     interface considerations.  You or others that use a script
  686.     containing such a command may not desire to have their
  687.     files saved, almost certainly not discarded.  Use carefully!
  688.     Make sure others know if you use either of these forms.
  689.     (None of the release scripts use any form of the QUITTEXTRA
  690.     command).
  691.       
  692.     Note that Textra will not exit if a print job is active.  If an ARexx 
  693.     script is running, the exit is postponed until the script finishes.  
  694.  
  695.  
  696.  ===================================================================
  697.  File/Window Management  (only in v1.12 and later)
  698.  ===================================================================
  699.  
  700.  
  701.  Some of the commands in this section deal with a parameter called
  702.  a 'window-pointer'.  These may be saved by your program and later
  703.  used to select the active window.  They are valid as long as that
  704.  window is open.  This parameter is bound to the window, not the
  705.  file.  As a result, it always describes the same window, even if
  706.  the filename of that window changes (perhaps via SAVEAS).
  707.  
  708.  
  709.  OPENFILE "filename"
  710.  
  711.     Reads in the specified file from disk, unless the file is
  712.     already open.  TEXTRA first expands the "filename" to it's
  713.     full pathname equivalent, then checks the titles of it's
  714.     current windows for a match.
  715.     
  716.     If the specified file is already open, it is brought to the
  717.     front and the cursor is set to 0,0 (just as if the file was
  718.     freshly opened).
  719.     
  720.     If the specified file is not open, and can't be found on the
  721.     disk, an empty window is created and given the specified
  722.     filename.
  723.     
  724.     NOTE: Do not pass a string that describes a directory to 
  725.           OPENFILE.  It will create a window, then present the 
  726.           file requester on that directory,  thereby requiring 
  727.           user input via the mouse.  Currently, OPENFILE does not 
  728.           wait for the selection before returning to the AREXX 
  729.           script, which operates on the window in that condition 
  730.           (with the requester in place).  (This will be protected 
  731.           against in a future version.)
  732.     
  733.     'result' set to:
  734.     
  735.     "window-pointer"  = descriptor to later use to re-select this
  736.                         window (see SELECTWINDOW)
  737.     
  738.     "0"               = window could not be opened
  739.  
  740.  
  741.  FINDFILE "filename"
  742.  
  743.     TEXTRA first expands the "filename" to it's full pathname 
  744.     equivalent, then checks the titles of it's current windows 
  745.     for a match.
  746.     
  747.     If the filename is found, it is brought to the
  748.     front and the associated 'window-pointer' is returned.
  749.     
  750.     FINDFILE is similar to OPENFILE, except that it never
  751.     creates a new window.
  752.     
  753.     'result' set to:
  754.     
  755.     "window-pointer"  = descriptor to later use to re-select this
  756.                         window (see SELECTWINDOW)
  757.     
  758.     "0"               = filename not found as a window title
  759.  
  760.  
  761.  SELECTWINDOW "window-pointer"
  762.  
  763.     The specified window is brought to the front and made
  764.     the current window.
  765.     
  766.     The window-pointer parameter must have been aquired from
  767.     either OPENFILE or FINDFILE, and the window must still be
  768.     open.
  769.     
  770.     v1.13 and later (only)...  SELECTWINDOW returns...
  771.     
  772.     "OK"              = Window found and selected
  773.     "NOT FOUND"       = passed in value was not a valid window-
  774.                         pointer
  775.  
  776.  
  777.  SAVEAS "filename"
  778.  
  779.     The currently selected window is saved to disk under the
  780.     specified name.
  781.     
  782.     If the specified filename is a single asterisk, i.e. "*",
  783.     the file will be written under the currently existing
  784.     filename (equivalent to a SAVE operation).
  785.     
  786.     'result' set to:
  787.     
  788.     "OK"             = file successfully written
  789.     "ERROR"          = some error occured, file not saved
  790.     "NOT FOUND"      = "filename" either describes a directory
  791.                        or contains an invalid pathname component
  792.     "FILE NOT NAMED" = a "*" has been specified, but the file has
  793.                        never been given a name
  794.  
  795.  
  796.  CLOSEWINDOW  (TextraVersion must return at least 1 13 3...not
  797.                supported in some early 1 13 3's (Beta2-Beta8))
  798.  
  799.     The currently selected window is closed unless it is the
  800.     last window.
  801.  
  802.     'result' set to:
  803.     
  804.     "RANGE ERROR"    = file is the last one open (can't be closed
  805.                        via ARexx)
  806.     "window-pointer" = the selected window was closed, the returned
  807.                        "file-pointer" is for the new selected window
  808.  
  809.  
  810.  
  811.  
  812.  
  813.  
  814.     Revision History
  815.     ----------------
  816.     
  817.     v1.10 (Did not support the TEXTRAVERSION command)
  818.           - Initial ARexx release
  819.  
  820.     v1.11 (Did not support the TEXTRAVERSION command)
  821.           - Fixed GET CURSOR CHAR problem (probable crash
  822.             if cursor was at the end of a line)
  823.  
  824.     These flavors are represented by the third digit in the
  825.     TEXTRAVERSION ARexx command.  Refer to the text for that
  826.     command.
  827.     
  828.     v1.12 (TEXTRAVERSION returns 1 12 2) 
  829.           - Replace WRAPAT.textra script with PARAGRAPH.textra
  830.           - Added File/Window Management section
  831.           - Added TEXTRAVERSION command
  832.  
  833.     v1.13 (TEXTRAVERSION returns 1 13 5) 
  834.           - Select "next word"-type words will now select
  835.             Alpha-NUMERIC strings.  (Earlier versions only selected
  836.             alphabetics) (Beta2)
  837.           - If no "s:Textra.cmds" file exists, default strings are
  838.             placed in the ARexx requester string gadgets (including
  839.             one "@command"-type ARexx STRING FILE as an example).
  840.             (Beta2)
  841.           - Added INSERTFILE <filename> (Beta3)
  842.           - TEXTRAVERSION  returns "1 13 3" (Beta2 was still "1 13 2")
  843.             (Beta3)
  844.           - '.textra' ARexx scripts can now be used like normal commands
  845.             inside other '.textra' ARexx scripts.   (Beta3)
  846.           - Fixed problem in ARexx interface that would cause a deadlock
  847.             if 'address "TEXTRA"' was used within a .textra script (Beta7)
  848.           - CLOSEWINDOW command  (Beta9)
  849.           - CHECKCANCEL command  (Beta9)
  850.           - version returns 1 13 4 (Beta12)
  851.           - SELECTWINDOW was broken in Beta8... window would become active,
  852.             but all subsequent events went to previously-selected window!
  853.             (Beta12)
  854.           - Added the following attributes to PREFS command/1 13 5 (Beta14)
  855.               [Alphanumeric]      [read on off]
  856.               [AlphanumericHops]  [read on off]
  857.     
  858.     v1.14 (TEXTRAVERSION returns 1 14 6)
  859.           - Added the QUITTEXTRA command
  860.           - Fixed a possible crash in the CLEAR command
  861.           - Fixed a possible crash in the CLOSEWINDOW command
  862.  
  863.  
  864.