home *** CD-ROM | disk | FTP | other *** search
/ Club Amiga de Montreal - CAM / CAM_CD_1.iso / files / 164.lha / ARexx / TXed_ARexx / readme < prev    next >
Text File  |  1988-04-28  |  6KB  |  125 lines
  1. Ref for TxEd with AREXX!
  2.  
  3. This set of AREXX macros were inspired by Matt Dillon's 'ref'
  4. command in his DME editor. The idea is to supply on-line help for
  5. any reference that you wish to set up. This feature seems to be
  6. most helpful for getting a reference to a structure from a fully
  7. commented set of include files or a reference to a function from
  8. the autodocs, but is sufficiently powerful to use anyway you see
  9. fit (perhaps a help file for TxEd?). 
  10.  
  11. Scenario: You are working on your masterpiece and you need to
  12. declare, say, a Border structure. Well, what does that border
  13. structure look like? You could pull out some reference work or open
  14. up another edit window and examine 'intuition.h' directly. Or you
  15. could use REF. Just position the cursor anywhere on the word
  16. 'border' and call the REF program (put it in a menu if you like). A
  17. new Txed window will appear containing the border structure as
  18. defined in 'intuition.h'.
  19.  
  20. Reality: Of course it isn't QUITE that simple, a little work will
  21. be needed beforehand. The first thing you have to do is set up a
  22. reference file that tells REF where to find the needed reference,
  23. but that is not so hard. REF assumes the file will be in your 's:'
  24. directory under the name 'TxEd.ref'. Open the 'intuition.h' file. A
  25. nasty technicality here: TxEd will not tell AREXX what directory it
  26. is in UNLESS that directory appears in the TxEd file requestor
  27. directory gadget, so be sure to open the file that way rather that
  28. changing to the include:intuiton directory, then editing. Assuming
  29. you have done so, simply move the cursor to the first line of the
  30. border structure definition. Now execute the AREXX macro 'markit
  31. border'. This tells the REF system that you wish to enter a new
  32. reference into TxEd.ref to serve as a reference for the word
  33. 'border'. Markit will write the reference word (border), the file
  34. name and directory, and the beginning line (current cursor line) to
  35. the file s:TxEd.ref. Now move the cursor to the last line of the
  36. border definition and execute the AREXX macro 'endit'. Endit will
  37. finish this entry into s:TxEd.ref' by writing the ending line to
  38. the file. Now, whenever you execute 'ref' with the cursor anywhere
  39. on the word 'border' in any file, you will recieve a new TxEd
  40. window with the border definition in it (or whatever was between
  41. the cursor positions when you executed markit and endit). This is
  42. so easy that you will probably just go through the common include
  43. files marking references for windows, screens, requestors, etc.
  44.  
  45. Of course you can do this for any word. So if you have the
  46. autodocs, you may wish to do this for functions as well. The
  47. process is quite simple. A word of warning: Markit and endit are
  48. rather simple minded, so you could easily corrupt your TxEd.ref
  49. file by not executing them in pairs. If this happens, don't panic!
  50. TxEd.ref is a simple text file that you can easily fix. Each line
  51. has the following format:
  52.  
  53. REFWORD  REFFILE @beginline@endline@
  54.  
  55. just delete the offending line or fix it by hand.
  56.  
  57. This version of ref works pretty fast, but the larger your txed.ref
  58. file, the longer it will take the program to find your reference.
  59. For this reason it is a good idea to enter only as many references
  60. as necessary and to keep the most common ones near the top of the
  61. file. Early versions of ref attempted to use AREXX to cull out
  62. unwanted portions of the reference file and were painfully slow.
  63. Now that I saw the light and let TxEd jump, mark, and cut commands
  64. handle that, the program seems very fast to me. Your mileage may
  65. vary, but the suggestions above should keep the program running
  66. pretty fast.
  67.  
  68. Additional feature : If you specify a reference word on the command
  69. line with ref, eg. 'REF WINDOW', then that word will be used in
  70. lieu of the word under the cursor. This allows you to reference
  71. words without having them appear in your file or having to move the
  72. cursor to them, and is also slightly faster.
  73.  
  74. Needed resources:
  75.  
  76.    TxEd Plus program of course!
  77.    AREXX program (I haven't tried this with the AREXX sample that
  78. comes with the TxEd Plus program, but am sure it requires full
  79. AREXX.
  80.    ref.txed - the main macro
  81.    lookitup.txed - called by ref.txed to handle new TxEd window.
  82.    markit.txed - begins reference definition
  83.    endit.txed - finishes reference definition
  84.  
  85. Endit would make a good addition to the menu or a macro key. Ref
  86. could also be used this way, but you will need to execute if from
  87. the command window if you wish to supply a reference word instead
  88. of using the one at the cursor. Markit would not work as a menu
  89. item unless you modify it to somehow pull the reference word from
  90. the user. Lookitup should not be called directly by the user.
  91.  
  92. The programs could probably be greatly improved. This is my first
  93. real AREXX program, so I am sure that I did a lot of things the
  94. hard way. The program has gone through some major changes as I
  95. found things in the AREXX manual that made my life easier. Feel
  96. free to hack it up like you want it. I have just scratched the
  97. surface of how powerful the AREXX/TxEd combination will prove to
  98. be. If you aren't using AREXX and TxEd, then I highly recommend it.
  99. WShell has also been quite helpful in developement.
  100.  
  101. These macros are freeware. If you think they are good enough to pay
  102. for, then why not send in your money for ConMan or ASDG's
  103. recoverable ram disk - those guys work harder than I do! Use them,
  104. modify them, just don't sell them. If you make changes or have some
  105. suggestions, comments, or bug reports, how about dropping me a note
  106. at
  107.  
  108. James Gary
  109. 5202 Vassar Ave.
  110. Louisville, KY 40258
  111.  
  112. I don't promise to support the software, but am interested enough
  113. to take your suggestions seriously. 
  114.  
  115. Special thanks to William Hawes for producing such wonderful
  116. products as ConMan, AREXX, and WShell and for taking time out from
  117. SELLING his stuff at Ami-Expo in Chicago to talk to me about AREXX
  118. programming when I had already purchased the product!
  119.  
  120. I just realized this: ref will work without txed. Just type 
  121. 'rx ref.txed REFWORD' and you will get a TxEd window with your 
  122. reference in it. Be sure to supply REFWORD or you will get some commands
  123. sent to the CLI that it won't understand. I just love it when
  124. a plan comes together! -JeG
  125.