home *** CD-ROM | disk | FTP | other *** search
/ BCI NET 2 / BCI NET 2.iso / archives / programming / arexx / autorexx.lha / AutoRexx.Doc < prev    next >
Encoding:
Text File  |  1992-10-19  |  11.3 KB  |  400 lines
  1. -----------------------------------------------------------------------------
  2.                             AutoRexx Version 1.0
  3.           Copyright (c) 1992 Mark Cassidy, Wize Productions Denmark
  4.                         Release date: 19 October 1992
  5. -----------------------------------------------------------------------------
  6.  
  7. Q: What is this then?
  8. A: An ARexx server, designed to provide the fastest possible access to your
  9.    autodocs.
  10.  
  11. Q: Ahh, this means that I don't have to wait for ages (actually seconds)
  12.    whenever I browse through a threat of functions?
  13. A: Correct!  Eventhough AutoRexx will only save you a few seconds on each
  14.    access to the autodocs database, it WILL seem like a significant gain.
  15.  
  16. Q: So how do I use it?
  17. A: That is entirely up to you.  As mentioned, AutoRexx is an ARexx server,
  18.    meaning that it is host for a few useful commands, how you use them is
  19.    up to you.  In this package, I've included the Rexx script I use myself
  20.    in CygnusEd, and this will probably be more than enough for most people.
  21.  
  22. Q: CygnusEd?  Is AutoRexx only for use with that?
  23. A: No!  However, AutoRexx DOES supply some functions which will only be
  24.    usable with CygnusEd.  These functions, however, are mainly for fast
  25.    interaction from YOUR place in CED till the docfile appears.
  26.  
  27. Q: Appears?  You mean loaded into the editor (CygnusEd in this case)?
  28. A: Correct!
  29.  
  30. Q: Why not use AmigaGuide or HyperText?
  31. A: Because I find it more convenient to have the docfile IN the editor,
  32.    editable.  This provides the opportunity of cutting and pasting.  Another
  33.    advantage is, that you can have BOTH the docfile AND your source(s) in
  34.    the editor at the same time.   Secondly, I find that CED is more
  35.    easy to handle efficiently than ie AmigaGuide.
  36.  
  37. Q: I see.  Do I need to install it in any way in CygnusEd?
  38. A: Yes!  You install it as a Dos/Rexx command (Menu: "Special" Item: "Dos/ARexx
  39.    interface" Sub: "Install Dos/ARexx command") on the function key of your
  40.    choice.
  41.  
  42. Q: OK, that sounds easy.  I should just install it as "AutoRexx" then?
  43. A: Oops no!  Sorry!   You need to install the script on the function-key.  This
  44.    means something like "AutoRexx.CED" should be installed in CygnusEd, NOT
  45.    the AutoRexx executable itself.
  46.  
  47. Q: What about the executable then?
  48. A: Well, that is the actual server.  You can launch it from your User-Startup
  49.    file.
  50.  
  51. Q: User-Startup?  What is that?
  52. A: The standard startup-file for WB2.x.
  53.  
  54. Q: But I run WB1.3...
  55. A: I'm sorry.  AutoRexx will only run on KickStart versions of V37 or higher.
  56.  
  57. [...1 week later...]
  58.  
  59. Q: OK, now I've bought the upgrade kit, it's GREAT!!!
  60. A: Correct! :-)
  61.    Well, as I was saying...  Place a line in your user-startup doing something
  62.    to the effect of: "Run >NIL: <NIL: AutoRexx AutoDocs:ADocs.REFS"
  63.  
  64. Q: ADocs.REFS?  What is that?
  65. A: An ASCII index-file of all your autodocs files.
  66.  
  67. Q: An INDEX file??  Why use AutoRexx if I already have an index file?
  68. A: Because AutoRexx will cache this file in internal binary form, providing
  69.    you with fast access (as already mentioned).
  70.  
  71. Q: OK.  How do I make this index file then?
  72. A: By using the supplied AutoRefs utility.   And don't forget to thank Matt
  73.    Dillon for this utility, he's the one who wrote it.
  74.  
  75. Q: Matt Dillon, isn't he the one...
  76. A: Yes!
  77.  
  78. Q: OK, I'll remember that.
  79. A: Thanx.
  80.  
  81. Q: Well, I guess this rounds it all up then?
  82. A: I should think so.  There's not much to it really.  The supplied script will
  83.    run nicely in CygnusEd.  If you need a script for another editor, it should
  84.    be fairly easy to write.  Just remember a VERY important thing..
  85.  
  86. Q: What is that then?
  87. A: Send me a copy for inclusion in further AutoRexx distributions :-)
  88.  
  89. Q: <*GRIN*>  Sounds reasonable, considering that AutoRexx is completely for
  90.    free.
  91. A: That's what I hoped you would say :-)
  92.  
  93. Q: Well OK, I think I'll install it then.  Thanks again!
  94. A: You're welcome!
  95.  
  96.  
  97. -----------------------------------------------------------------------------
  98.                               oO DISCLAIMER Oo
  99. -----------------------------------------------------------------------------
  100.  
  101. If you're lucky, AutoRexx will work as described in this documentation.  If
  102. not, bad luck, good you didn't waste any money.
  103.  
  104. I have tested AutoRexx on my own system, and a few people have tested this
  105. programs on their own setup.  I know that AutoRexx works on these systems,
  106. but do NOT under ANY circumstances guarantee that AutoRexx will work for you.
  107.  
  108. Should you have any problems with AutoRexx, I will most likely try to fix the
  109. problem.  If not, bad luck again.
  110.  
  111. Flames to never-never land, criticism welcome.
  112.  
  113.  
  114. All this said...  AutoRexx will most likely work on any setup, as the program
  115. itself is quite simple.
  116.  
  117.  
  118. Mark Cassidy holds ALL rights to this program at ALL times.  Under NO
  119. circumstances must this program be distributed for a fee in ANY product,
  120. commercial or non-commercial.  Resonable charges for P&P will be accepted
  121. up to the equivalent of 5US$ (7DEM, 25DKK).
  122.  
  123. This rule does NOT apply to "Det Ny COMputer", whom I hereby DENY ANY rights
  124. to USE or DISTRIBUTE this program in ANY form at ANY price.
  125.  
  126.  
  127. The copyright includes:
  128.     AutoRexx    - Binary
  129.     AutoRexx.Doc    - ASCII
  130.     AutoRexx.CED    - ASCII Rexx script
  131.  
  132. Other files in this archive cannot (and will not) be part of this copyright.
  133.  
  134.  
  135. -----------------------------------------------------------------------------
  136.                        AutoRexx Technical Description
  137. -----------------------------------------------------------------------------
  138.  
  139. Usage:
  140.  
  141. 1> AutoRexx REFS/M,P=PORTNAME/K
  142.  
  143. REFS is the name(s) of all the AutoRefs generated index files
  144. PORTNAME is the portname AutoRexx should be using.  The default for the latter
  145. is AUTOREXX, and further invocations will be "AUTOREXX.1" etc.
  146.  
  147.  
  148. Usage:
  149.  
  150. 1> AutoRefs REFSFILE/A DOCFILE/A/M
  151.  
  152. * NOTE that the actual syntax does not appear this way in the actual program,
  153. I've just 'redone' it to comform to WB2.x standards for command-templates.
  154.  
  155. Common usage will be something like "AutoRefs AutoDocs:ADOC.REFS #?/#?.Doc"
  156.  
  157. Note:  I sincerely do not hope I'm breaking any copyright rules by including
  158. Matt Dillon's program in this archive.  Proper credit and thanks for this
  159. program goes to Matt Dillon.
  160.  
  161.  
  162. -----------------------------------------------------------------------------
  163.                                    Credits
  164. -----------------------------------------------------------------------------
  165.  
  166. Michael Balzer for his great ARexxBox V1.0.  The program still has a few
  167. oddities, but it took a great workload off me when creating this program.
  168.  
  169. William S. Hawes for ARexx.
  170.  
  171. Matt Dillon for AutoRefs.
  172.  
  173. CygnusSoft Software for CygnusEd Pro. V2+
  174.  
  175. Manx Software Systems for Aztec C V5.2a.
  176.  
  177. Klaus Seistrup (2:230/119) and SUne Trudslev (2:230/415) for betatesting.
  178.  
  179. All registered users of FServ.
  180.  
  181. Prince and the NPG for  O  (Yeah! you do a better job of drawing it :-))
  182.             |
  183.               o-+-(
  184.             |
  185.             V
  186.  
  187.  
  188. Comments, bug reports and new editor scripts to:
  189.  
  190. Wize Productions Denmark
  191. Attn: Mark Cassidy
  192. Rydsaavej 101
  193. 5210  Odense NV
  194. Denmark
  195.  
  196. or you MAY get through on:
  197.  
  198. 2:230/611.0@FidoNet
  199. 39:140/103.0@AmigaNet
  200. 92:910/201.0@BadNet
  201. mark_cassidy@f201.n910.z92.badnet.bad.se
  202.  
  203.  
  204.                                      oOo
  205.  
  206.                         All that is, was and will be
  207.                         Universe much too big to see
  208.                         Time and space never ending 
  209.                    Disturbing thoughts, questions pending
  210.                      Limitations of human understanding
  211.                            Too quick to criticize
  212.                             Obligation to survive
  213.                             We hunger to be alive
  214.  
  215.                                      oOo
  216.  
  217.  
  218. -----------------------------------------------------------------------------
  219.                         AutoRexx ARexx(tm) Interface
  220. -----------------------------------------------------------------------------
  221.  
  222. TABLE OF CONTENTS
  223.  
  224. AutoRexx/AUR_AUTOGET
  225. AutoRexx/AUR_ADDREFS
  226. AutoRexx/AUR_FILETOCED
  227. AutoRexx/AUR_GETCEDWORD
  228. AutoRexx/AUR_NEWREFS
  229. AutoRexx/AUR_QUIT
  230.  
  231.  
  232. AutoRexx/AUR_AUTOGET                                  AutoRexx/AUR_AUTOGET
  233.  
  234.     NAME
  235.         AUR_AUTOGET -- Get a function from the autodocs
  236.  
  237.     SYNOPSIS
  238.         AUR_AUTOGET Function/A FileName/A
  239.  
  240.     FUNCTION
  241.         AUR_AUTOGET will parse the internal function index and extract
  242.         the function from the autodocs file.  The result is written
  243.         to FileName/A.
  244.  
  245.     INPUTS
  246.         Function/A    - Name of the function to extract
  247.         FileName/A    - Name of the filename to write the result to
  248.  
  249.     RESULTS
  250.         rc will be ~0 if the function was not available in the
  251.         autodocs.
  252.  
  253.     BUGS
  254.         None
  255.  
  256.     SEE ALSO
  257.         AutoRexx/AUR_GETCEDWORD, AutoRexx/AUR_FILETOCED
  258.  
  259.  
  260. AutoRexx/AUR_ADDREFS                                  AutoRexx/AUR_ADDREFS
  261.  
  262.     NAME
  263.         AUR_ADDREFS --    Add a new REFS file to the internal
  264.                 function table.
  265.  
  266.     SYNOPSIS
  267.         AUR_ADDREFS Refs/A/M
  268.  
  269.     FUNCTION
  270.         AUR_ADDREFS will load the specified REFS file(s) and ADD them
  271.         to it's internal list of functions.  This command is rather
  272.         CPU intensive and therefore time-consuming.
  273.  
  274.     INPUTS
  275.         Refs/A/M    - Name of the REFS file(s) to add.
  276.  
  277.     RESULTS
  278.         None
  279.  
  280.     BUGS
  281.         AUR_ADDREFS will NOT check for any duplicate function entries,
  282.         meaning that only first occurence of any function will ever
  283.         be noticed by AutoRexx, but several copies may be lying
  284.         around in the function table.
  285.         This is not a real problem though, unless you mess too much
  286.         around with the REFS files.
  287.  
  288.     SEE ALSO
  289.         AutoRexx/AUR_NEWREFS
  290.  
  291.  
  292. AutoRexx/AUR_FILETOCED                                AutoRexx/AUR_FILETOCED
  293.  
  294.     NAME
  295.         AUR_FILETOCED    - Bring a file into CED
  296.  
  297.     SYNOPSIS
  298.         AUR_FILETOCED FileName/A
  299.  
  300.     FUNCTION
  301.         AUR_FILETOCED will load the FileName/A file into CED, taking
  302.         notice to the previous autodocs file loaded by this command.
  303.         In English: If you have previously loaded an autodocs file
  304.         with this command, and the file is STILL in CED (quite often),
  305.         AUR_FILETOCED will load the NEW autodocs file at the same
  306.         'place' this previous file is loaded.
  307.  
  308.     INPUTS
  309.         FileName/A    - Filename to load into CED
  310.  
  311.     RESULTS
  312.         rc will be ~0 if CED's Rexx-port cannot be located.
  313.  
  314.     BUGS
  315.         None
  316.  
  317.     SEE ALSO
  318.         AutoRexx/AUR_GETCEDWORD, AutoRexx/AUR_AUTOGET
  319.  
  320.  
  321. AutoRexx/AUR_GETCEDWORD                               AutoRexx/AUR_GETCEDWORD
  322.  
  323.     NAME
  324.         AUR_GETCEDWORD -- Get active word in CED
  325.  
  326.     SYNOPSIS
  327.         AUR_GETCEDWORD
  328.  
  329.     FUNCTION
  330.         AUR_GETCEDWORD will get the 'active' word in CED, meaning the
  331.         word on which the cursor is currently placed (or the word to
  332.         the immediate left).  AUR_GETCEDWORD is 'smart' enough to know
  333.         about '(' chars and the likes.
  334.  
  335.     INPUTS
  336.         None
  337.  
  338.     RESULTS
  339.         The word under the cursor (if any)
  340.  
  341.     BUGS
  342.         None
  343.  
  344.     SEE ALSO
  345.         AutoRexx/AUR_AUTOGET, AutoRexx/AUR_FILETOCED
  346.  
  347.  
  348. AutoRexx/AUR_NEWREFS                                  AutoRexx/AUR_NEWREFS
  349.  
  350.     NAME
  351.         AUR_NEWREFS - Initialize a new REFS function table
  352.  
  353.     SYNOPSIS
  354.         AUR_NEWREFS REFS/A
  355.  
  356.     FUNCTION
  357.         AUR_NEWREFS will remove all internal function tables and
  358.         reload your new REFS file(s).  Due to the nature of the
  359.         internal tables, this function is very CPU intensitive,
  360.         and VERY slow in execution.
  361.  
  362.     INPUTS
  363.         REFS/A        - Filename(s) of the new REFS file(s)
  364.  
  365.     RESULTS
  366.         None
  367.  
  368.     BUGS
  369.         If you need to remove ALL internal tables without reloading
  370.         any new ones, you need to specify a 'dummy' file for
  371.         AUR_NEWREFS.
  372.  
  373.     SEE ALSO
  374.         AutoRexx/AUR_ADDREFS
  375.  
  376.  
  377. AutoRexx/AUR_QUIT                                     AutoRexx/AUR_QUIT
  378.  
  379.     NAME
  380.         AUR_QUIT -- Quits AutoRexx
  381.  
  382.     SYNOPSYS
  383.         AUR_QUIT
  384.  
  385.     FUNCTION
  386.         AUR_QUIT releases all internal function tables and quits.
  387.  
  388.     INPUTS
  389.         None
  390.  
  391.     RESULTS
  392.         None
  393.  
  394.     BUGS
  395.         None
  396.  
  397.     SEE ALSO
  398.  
  399.  
  400.