home *** CD-ROM | disk | FTP | other *** search
/ Club Amiga de Montreal - CAM / CAM_CD_1.iso / files / 498b.lha / HyperText / TechInfo < prev    next >
Text File  |  1991-04-08  |  9KB  |  233 lines
  1. \title The Juicy Internals
  2. \center
  3. \ital \bold Techie Info \ital \bold
  4.  
  5.     This file covers the technical aspects of HT's Arexx port, how HT
  6. works, and limitations of the program.    If you are a casual user, most of
  7. this will be goobleygook.  If you are a keen eyed C programmer, you can
  8. probably figure out how I did most of the things in HT.
  9.  
  10. \center
  11. \underline AREXX Support \underline
  12.  
  13.     Arexx is fully supported by HT.  HT can send messages to Arexx, and can
  14. receive messages from Arexx programs.  The three commands HT accepts \ital
  15. from \ital ARexx programs are:
  16.  
  17. \freeformat
  18. \indent 25
  19. LOAD <filename>
  20. RESIDENT
  21. DIE
  22.  
  23.     The port name to send messages to from an Arexx macro, is HT.  To use
  24. the above commands in an Arexx program, you could use one of these
  25. fragments of Arexx code :
  26.  
  27.  
  28. \center
  29. address HT "LOAD  my_file_name  some phrase"
  30.  
  31. \center
  32. or
  33.  
  34. \center
  35. address HT "RESIDENT"
  36.  
  37. \center
  38. or
  39.  
  40. \center
  41. address HT "DIE"
  42.  
  43. \format
  44.      These commands are used from within an ARexx program to talk with HT.
  45. The commands give you a simple and straightforward way to use HT.  Inside
  46. any ARexx program, simply use these commands to utilize the features HT
  47. offers.  Instead of displaying a file with "more", you now have a way to
  48. display fully linked and cross-referenced files.
  49.  
  50.      Commands names must be in all caps when sent to HT.  It's probably a
  51. good idea to check to make sure HT is around first also, before you send
  52. the message.  There is a script to do this called \ital startht.rexx.\ital
  53.  
  54.      In addition, you can make sure that HT will listen for Arexx requests,
  55. with the "-r" option when you run HT.  The -r (rexx/resident) option will
  56. tell HT to simply sit on its port and wait for commands, even if it has no
  57. other windows open.  By typing \ital "run HT -r" \ital at a CLI prompt or
  58. including it as part of an ARexx script, you will end up with a help server
  59. (HT) waiting for requests, and not taking up too much memory.
  60.  
  61.  
  62. \center
  63. \underline Description of Rexx Commands \underline
  64.  
  65. \underline The LOAD Command \underline
  66.  
  67. FORMAT : address HT LOAD  <filename>  [words to search for]
  68.  
  69. EXAMPLE : address HT LOAD TechInfo AREXX
  70.  
  71.     The Load command does just that.  It instructs HT to open that filename
  72. and display it.  You probably will want to make sure you give a full path
  73. name for the file you would like to load, so that HT can find the file you
  74. are looking for.
  75.  
  76.     If you specify anything after the filename, this is assumed to be a
  77. phrase to search for and put at the top of the new window.  This part \ital
  78. is \ital optional.
  79.  
  80.     Here is a more complete example (although a trivial one) :
  81.  
  82. \freeformat
  83. /* This is an ARexx program to test out HT */
  84.  
  85. /* utilize the existing startht.rexx script to make sure HT gets run */
  86. startht
  87.  
  88. /* now prompt the user for input and pass that to HT */
  89. say "Hello young one, please enter a filename :"
  90. parse pull var fname
  91.  
  92. if fname = "" then do
  93.   say "You need to give me a filename to work"
  94.   exit
  95. end
  96.  
  97. /* now actually instruct HT to load the given filename */
  98. address HT LOAD fnam
  99.  
  100. /* exit nicely */
  101. exit
  102.  
  103.  
  104. \format
  105.      In the previous mini-rexx macro, we showed \bold exactly \bold what is
  106. needed to utilize the features of HT from ARexx.  Doesn't it all work
  107. together very nicely?
  108.  
  109.  
  110. \underline The RESIDENT Command \underline
  111.  
  112. FORMAT : address HT RESIDENT
  113.  
  114.     The resident command tells HT to stay loaded even it would normally
  115. exit.  This keeps HT waiting for messages to arrive, i.e. a Help server.
  116. You can send as many RESIDENT commands as you like, only the first turns it
  117. on, and the DIE command turns it off.  After HT has been put into resident
  118. mode, it will only unload itself with a DIE command.
  119.  
  120.     What this means in English is that after having given this command, HT
  121. will remain in memory waiting around for new messages from ARexx.  Normally
  122. HT would simply quit when there are no more children windows.  It is useful
  123. if you are going to be sending a lot of requests to HT, and need to make
  124. sure it doesn't decide to quit all of a sundden.
  125.  
  126.  
  127. \underline The DIE Command \underline
  128.  
  129.     The Die command tells HT you don't mind if it exits after the
  130. last child window is closed by the user.  Although somewhat morbid, this
  131. command is useful when you would like to unload HT.  HT will always wait
  132. until the user has finished with all the windows before exiting.
  133.  
  134. \center
  135. \bold Sending Messages TO ARexx\bold
  136.  
  137.     HT can also send messages to the ARexx server.  This is done via the
  138. \link { LinkCommands AREXX } \\ARexx keyword.\endlink    When an embedded
  139. ARexx link is double clicked on, the ARexx program contained in the link is
  140. passed to the ARexx server (along with any options you have given) by HT.
  141. It would be the same were in a CLI and had typed : \ital rx arexx_program
  142. \ital
  143.  
  144.  
  145.  
  146. \center
  147. \underline OverAll Structure of the program \underline
  148.  
  149. \format
  150.     Well, there are several intriguing things going on with HT.  Probably
  151. the most interesting is that each window is a seperate AmigaDos process.
  152. This allows for everything to take place as independantly as possible.
  153. Each of the window processes communicate with the main parent via an
  154. Exec message port.  The code for window, menu, and gadget handling is 100%
  155. re-entrant and shared by all window processes.
  156.  
  157.     Since most of the code is re-entrant, it makes all of this possible.
  158. This design really cuts down on the amount of memory required by the
  159. program, plus it allows each window to operate completely independant of
  160. each other.
  161.  
  162.     The main program uses an extended Exec message structure, an Htmsg, to
  163. communicate with the children.    The main body waits on its port for
  164. messages from its children (and ARexx if it is up).  The main body only
  165. does a few things - wait for children to die, wait for them to tell us to
  166. open new files or messages from Rexx.  When there are no children left and
  167. we aren't in \ital RESIDENT \ital mode, the main body (and everything
  168. associated with it) exits.
  169.  
  170.     The rest of the structure of HT is fairly straightforward.    A file is
  171. read in and parsed.  If everything has gone well, the child process that
  172. handles the window is started.    The child process opens its window and
  173. sends a quickie message back to the parent to tell it everything went well
  174. (or went bad).  Then the child is on its own.  If it needs to communicate
  175. with the parent (to open a new file or to die) it will send a message.  The
  176. message port the children use is the same one as for Rexx.  The parent will
  177. copy what it needs and reply right away.  This makes things as asynchronous
  178. as possible (although a little bit more complex).
  179.  
  180.     When the user double clicks the mouse button, the program checks if the
  181. last click was on a highlighted word or not.  If so, it executes the link
  182. by looking it up in a table, and calling on ASyncRun() to do the job.
  183.  
  184.     That in a nutshell is how HT works.  Straightforward and simple. Just
  185. like it always should be :-)  (echos of Mr. Alan Kay in there? :)
  186.  
  187.     There are many more details about the internals of HT, but that covers
  188. the main parts.  The rest could probably fill several articles about the
  189. trials and tribulations of developing an Amiga program..... :)
  190.  
  191.  
  192.  
  193. \b  Limitations of the program? \b
  194.  
  195.   Well.  There are a few, but I think machine limits will exhaust before
  196. the program (but then again maybe not with the A3000 :).
  197.  
  198. \freeformat
  199. \indent
  200. Max # of Lines in a file : \BOLD 4 gigabytes (2^32)\BOLD
  201. Max # of Links per file  : \BOLD 65,534 (2^16)\BOLD
  202. Max # of Types of links  : \BOLD 256\BOLD
  203. Max # of open files     : \BOLD amount of memory you have\BOLD
  204. Max # of fonts styles     : \BOLD 256\BOLD
  205.  
  206. \format
  207.     Some of the limitations aren't really limitations.  For example, the
  208. current system software only defines 3 font styles, however more can be
  209. supported.
  210.  
  211.     The number of link Types is 256, and only 7 are currently defined.    So
  212. far they pretty much cover everything, but there is room for expansion.
  213.  
  214.     In terms of the max # of lines, anybody who can fit more than 4 gigs
  215. of lines in their machine better call me quick, as I wanna see their
  216. machine!
  217.  
  218.     The maxinum number of links per file was a serious design
  219. consideration.    However, 65,534 links is a \it lot \it of links.  Even if
  220. one thing per line were linked, and you had 60 character lines, the file
  221. size would be \it 3.8 MEGABYTES! \it  If you ever write that much in one
  222. file, let me know again 'cause I'm gonna wanna see your hands :)
  223.  
  224.     I don't like artificial limits as much as anyone, but certain
  225. concessions had to be made for speed, space requirements, and time.  I
  226. think everything is fairly well balanced.  If you don't (and have a good
  227. reason) yell at me about it ;-)
  228.  
  229.  
  230.     That about covers the extent of the techie information about HT.
  231.  
  232.  
  233.