Otherware/Otherware_1_SB_Development.iso/amiga/utility/text/htext.lzh/hypertext/Documentation/TechInfo

Text File | 1990-12-23 | 8.5 KB | 233 lines

\title The Juicy Internals
\center
\ital \bold Techie Info \ital \bold

    This file covers the technical aspects of HT's Arexx port, how HT
works, and limitations of the program.    If you are a casual user, most of
this will be goobleygook.  If you are a keen eyed C programmer, you can
probably figure out how I did most of the things in HT.

\center
\underline AREXX Support \underline

    Arexx is fully supported by HT.  HT can send messages to Arexx, and can
receive messages from Arexx programs.  The three commands HT accepts \ital
from \ital ARexx programs are:

\freeformat
\indent 25
LOAD <filename>
RESIDENT
DIE

    The port name to send messages to from an Arexx macro, is HT.  To use
the above commands in an Arexx program, you could use one of these
fragments of Arexx code :


\center
address HT "LOAD  my_file_name  some phrase"

\center
or

\center
address HT "RESIDENT"

\center
or

\center
address HT "DIE"

\format
     These commands are used from within an ARexx program to talk with HT.
The commands give you a simple and straightforward way to use HT.  Inside
any ARexx program, simply use these commands to utilize the features HT
offers.  Instead of displaying a file with "more", you now have a way to
display fully linked and cross-referenced files.

     Commands names must be in all caps when sent to HT.  It's probably a
good idea to check to make sure HT is around first also, before you send
the message.  There is a script to do this called \ital startht.rexx.\ital

     In addition, you can make sure that HT will listen for Arexx requests,
with the "-r" option when you run HT.  The -r (rexx/resident) option will
tell HT to simply sit on its port and wait for commands, even if it has no
other windows open.  By typing \ital "run HT -r" \ital at a CLI prompt or
including it as part of an ARexx script, you will end up with a help server
(HT) waiting for requests, and not taking up too much memory.


\center
\underline Description of Rexx Commands \underline

\underline The LOAD Command \underline

FORMAT : address HT LOAD  <filename>  [words to search for]

EXAMPLE : address HT LOAD TechInfo AREXX

    The Load command does just that.  It instructs HT to open that filename
and display it.  You probably will want to make sure you give a full path
name for the file you would like to load, so that HT can find the file you
are looking for.

    If you specify anything after the filename, this is assumed to be a
phrase to search for and put at the top of the new window.  This part \ital
is \ital optional.

    Here is a more complete example (although a trivial one) :

\freeformat
/* This is an ARexx program to test out HT */

/* utilize the existing startht.rexx script to make sure HT gets run */
startht

/* now prompt the user for input and pass that to HT */
say "Hello young one, please enter a filename :"
parse pull var fname

if fname = "" then do
  say "You need to give me a filename to work"
  exit
end

/* now actually instruct HT to load the given filename */
address HT LOAD fnam

/* exit nicely */
exit


\format
     In the previous mini-rexx macro, we showed \bold exactly \bold what is
needed to utilize the features of HT from ARexx.  Doesn't it all work
together very nicely?


\underline The RESIDENT Command \underline

FORMAT : address HT RESIDENT

    The resident command tells HT to stay loaded even it would normally
exit.  This keeps HT waiting for messages to arrive, i.e. a Help server.
You can send as many RESIDENT commands as you like, only the first turns it
on, and the DIE command turns it off.  After HT has been put into resident
mode, it will only unload itself with a DIE command.

    What this means in English is that after having given this command, HT
will remain in memory waiting around for new messages from ARexx.  Normally
HT would simply quit when there are no more children windows.  It is useful
if you are going to be sending a lot of requests to HT, and need to make
sure it doesn't decide to quit all of a sundden.


\underline The DIE Command \underline

    The Die command tells HT you don't mind if it exits after the
last child window is closed by the user.  Although somewhat morbid, this
command is useful when you would like to unload HT.  HT will always wait
until the user has finished with all the windows before exiting.

\center
\bold Sending Messages TO ARexx\bold

    HT can also send messages to the ARexx server.  This is done via the
\link { LinkCommands AREXX } \\ARexx keyword.\endlink    When an embedded
ARexx link is double clicked on, the ARexx program contained in the link is
passed to the ARexx server (along with any options you have given) by HT.
It would be the same were in a CLI and had typed : \ital rx arexx_program
\ital



\center
\underline OverAll Structure of the program \underline

\format
    Well, there are several intriguing things going on with HT.  Probably
the most interesting is that each window is a seperate AmigaDos process.
This allows for everything to take place as independantly as possible.
Each of the window processes communicate with the main parent via an
Exec message port.  The code for window, menu, and gadget handling is 100%
re-entrant and shared by all window processes.

    Since most of the code is re-entrant, it makes all of this possible.
This design really cuts down on the amount of memory required by the
program, plus it allows each window to operate completely independant of
each other.

    The main program uses an extended Exec message structure, an Htmsg, to
communicate with the children.    The main body waits on its port for
messages from its children (and ARexx if it is up).  The main body only
does a few things - wait for children to die, wait for them to tell us to
open new files or messages from Rexx.  When there are no children left and
we aren't in \ital RESIDENT \ital mode, the main body (and everything
associated with it) exits.

    The rest of the structure of HT is fairly straightforward.    A file is
read in and parsed.  If everything has gone well, the child process that
handles the window is started.    The child process opens its window and
sends a quickie message back to the parent to tell it everything went well
(or went bad).  Then the child is on its own.  If it needs to communicate
with the parent (to open a new file or to die) it will send a message.  The
message port the children use is the same one as for Rexx.  The parent will
copy what it needs and reply right away.  This makes things as asynchronous
as possible (although a little bit more complex).

    When the user double clicks the mouse button, the program checks if the
last click was on a highlighted word or not.  If so, it executes the link
by looking it up in a table, and calling on ASyncRun() to do the job.

    That in a nutshell is how HT works.  Straightforward and simple. Just
like it always should be :-)  (echos of Mr. Alan Kay in there? :)

    There are many more details about the internals of HT, but that covers
the main parts.  The rest could probably fill several articles about the
trials and tribulations of developing an Amiga program..... :)



\b  Limitations of the program? \b

  Well.  There are a few, but I think machine limits will exhaust before
the program (but then again maybe not with the A3000 :).

\freeformat
\indent
Max # of Lines in a file : \BOLD 4 gigabytes (2^32)\BOLD
Max # of Links per file  : \BOLD 65,534 (2^16)\BOLD
Max # of Types of links  : \BOLD 256\BOLD
Max # of open files     : \BOLD amount of memory you have\BOLD
Max # of fonts styles     : \BOLD 256\BOLD

\format
    Some of the limitations aren't really limitations.  For example, the
current system software only defines 3 font styles, however more can be
supported.

    The number of link Types is 256, and only 7 are currently defined.    So
far they pretty much cover everything, but there is room for expansion.

    In terms of the max # of lines, anybody who can fit more than 4 gigs
of lines in their machine better call me quick, as I wanna see their
machine!

    The maxinum number of links per file was a serious design
consideration.    However, 65,534 links is a \it lot \it of links.  Even if
one thing per line were linked, and you had 60 character lines, the file
size would be \it 3.8 MEGABYTES! \it  If you ever write that much in one
file, let me know again 'cause I'm gonna wanna see your hands :)

    I don't like artificial limits as much as anyone, but certain
concessions had to be made for speed, space requirements, and time.  I
think everything is fairly well balanced.  If you don't (and have a good
reason) yell at me about it ;-)


    That about covers the extent of the techie information about HT.