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

Text File | 1990-12-24 | 15.5 KB | 372 lines

\help ht.help
\fgcolor 2
\bgcolor 3
\title Link Commands - Descriptions and Examples
\bold \\LINK { <somefilename> [somephrase] } \bold

\format
     This command is the \ital hypertext \ital part of the whole program.
It is \bold THE \bold '\\' command.  It creates a link between
<somefilename> and the text after the closing '}', until the \\endlink
command. If [somephrase] is given, then that will be searched for in
<somefilename> and put at the top line of the new window.  This is what
hypertext is about.

      The first word inside of the curly braces ({}'s) is considered to
be the filename you are linking to.  Anything after the first word is
considered to be the phrase/word you want to link to in the new file.
This means that if you were to specify \\link { words.txt this is a
sentence. }, then HT would open the file words.txt, read it in, search for
"this is a sentence." and display the line that contains it at the top of
the new window.  If "this is a sentence" cannot be found, HT will just
display the file as normal, with the first line of the file at the top of
the window.  \ital NOTE: \ital You cannot currently have spaces in the name
of the file you are linking to.

     You can link to a word, phrase, or sentence in any file anywhere
provided you give the file a full path name.  That file doesn't even
\ital have \ital to be a HT document (it would be nice though).  The
phrase/word you are looking for in <somefilename> must be less than 2048
characters.  I would hope that's not a problem (but hey that's what they
said about 640k as maximum memory).  In almost all cases, what you
are looking for will be unique in about 80-100 characters, so this is
really a moot point.

     Following are some examples of what you could type in to a text
editor, followed by \BOLD exactly \BOLD what HT would display.    These are
good examples of how to setup links.  Clicking on these links won't work
however, because they are just examples.  If these examples seem
complicated, remember that usually you will not have type in the link
information by hand (see the file \link { Editors.txt } Editors.txt).
\endlink

\freeformat
\it \under EXAMPLES:\under \ital
     1.)  The ancient Roman \\Link { emperors.txt Roman Emperors }
      Emperors \\Endlink tended to be a bit \\Link { df1:caligula.story
      Caligula } weird. \\Endlink

\format
     The ancient Roman \link { emperors.txt "Roman Emperors"" }
Emperors \endlink tended to be a bit \link { df1:caligula.story
Caligula } weird. \endlink

    What example 1 does is setup two (2) links.  The first link is on the
word 'Emperors', which is linked to the phrase 'Roman Emperors' in the file
emperors.txt in the same directory.  Double clicking on Emperors would
bring up another window with the file emperors.txt and the first occurence
of 'Roman Emperors' at the top of the window.

    The second link is from the word 'weird' in the current file to the
word 'Caligula' in the file df1:caligula.story.  Double clicking on 'weird'
will automagically bring up a window with the file df1:caligula.story
(assuming it exists) and the word 'Caligula' at the top.


\freeformat
     2.)  Washington D.C. is the \\Link { capitol.txt IX. What
      is a Capitol } capitol \\Endlink of the United States.

      Washington D.C. is the \link { capitol.txt IX. What
      is a Capitol } capitol \endlink of the United States.

    Pretty easy one to figure out.  The word 'capitol' is linked to the
phrase "IX. What is a Capitol" in the file capitol.txt.  This is about as
basic as a link can get, but shows how to link something in the current
file to a section heading in another file.  This works nicely for easy
cross indexing of chapters and references.

-------------------------------------------------------------------------
\format
\bold \\RUN { <someprogram and its options> } \bold

   The \\RUN command is used to set up a link between a word/phrase in
the current document and some other program.  Anything between the
opening curly brace ({) and the closing curly brace (}) is passed to the
program which is assumed to be the first word in the {}'s.  Basically it
is as if you typed the line at a CLI prompt.  The program that is run is
completely independant from the HT program, and HT does \bold NOT\bold
wait for it to complete (remember this is why you have an Amiga :).

   This function allows you to link to virtually any program.  Of course
the are other commands that may be more appropriate, but if nothing else
works, and this is your last resort, it should handle just about any
case not handled by the other link commands.

\freeformat
 NOTE:    If you are paranoid about someone doing destructive things
    without your knowing, you can set the configuration option ASKFIRST
    to "Yes/On" using the HTConfig utility. This will cause HT to pop
    up a requestor showing what is about to be run and asking you if it
    is ok.    If you say "OK", HT will execute the program, otherwise it
    will do nothing.  I'm assuming people aren't out to do destructive
    things.  If you aren't as sure about human nature, set the
    configuration option ASKFIRST to "Yes/On", and you will be asked
    prior to any programs' execution.


\freeformat
Examples:
     1.)  This is some really insipid text, but it is linked to a really
      jazzy \\Run { coolprogram -c -h arg1 arg2 } program \\Endlink.

     This is some really insipid text, but it is linked to a really
jazzy \run { coolprogram -c -h arg1 arg2 } program \Endlink.

     This example sets up a link between the word program, and the program
     called 'coolprogram'.  Coolprogram is passed as parameters "-c -h
     arg1 arg2".  Clicking on the word 'program' causes HT to execute the
     program called 'coolprogram' and pass it the parameters.

     2.)  This \\Run { df1:nifty/neeto arg1 } program has a full
      pathname\\Endlink , but isn't really a problem.

\format
This \run { df1:nifty/neeto arg1 } program has a full pathname,\Endlink but
isn't really a problem.

\freeformat
     What we have here is a program called "neeto" in the directory
     df1:nifty/ which is to executed with the single argument arg1. when
     someone clicks on the phrase "program has a full pathname".

--------------------------------------------------------------------------

\bold \\SOUND { <soundfilename> } \bold

\format
    This command will create a link between a word/phrase and any sound
file you want.    Double clicking the linked phrase triggers the sound you
have specified to be played.

    The default program to run is SSP, somewhere in your path.    You can
change this with HTConfig program.  You would change the SOUND option to
the name of the program you want to use.

Examples:

\freeformat
This first example will play the sound boink.sound whenever the words
"boink sound" are double clicked on.

      1.)  The \\sound { boink.sound } boink sound \\endlink is a strange
       one.

       The \sound { boink.sound } boink sound \endlink is a strange one.

Next, assuming that you are using the SSP program to play these sounds, you
can also pass options to SSP like this:

\indent
This is a slow \\sound {  -p200 boink.sound } boink sound
\\endlink because it is played back at a much slower rate.

\format
\indent
This is a slow \sound {  -p200 boink.sound } boink sound
\endlink because it is played back at a much slower rate.

Which plays the same sound as above, but at a much slower rate.

\format
    Of course to end the link you should have an \\Endlink command at the
end of your linked text.  This is important to remember or else the link
will continue until an \\Endlink command is found.

--------------------------------------------------------------------------

\bold \\SHOW  { <iff picture name> } \bold

    If you would like a word or phrase to be linked to an IFF picture, you
can use this command.  When the word or phrase is clicked on, the picture
will be displayed (if possible).

    The default program to be run is SHOW, which should be in your path.
If you would like to change this, use the HTConfig utility to change which
program is used.

Examples:

\freeformat
     This first example simply will display a picture called babylon.pic
(which is in the current directory) when the user double clicks on the
phrase "Hanging Gardens of Babylon".  Pretty straightforward.

\indent
The \\show { babylon.pic } Hanging Gardens of Babylon \\endlink
were one of the wonders of the ancient world.

\format
\indent
The \show { babylon.pic } Hanging Gardens of Babylon \endlink
were one of the wonders of the ancient world.

\format
    Of course to end the link you should have an \\Endlink command at the
end of your linked text.  This is important to remember or else the link
will continue until an \\Endlink command is found.

--------------------------------------------------------------------------

\bold \\ANIM { <anim name> } \bold

     Use of the \\Anim command will set up a link to the specified anim
file.  When the user double clicks the highlighted text, the animation
will be played.  This can be very useful for demonstrating concepts being
read about in the document.

    The default program to be run is SHOWANIM, which should be in your
path.  If you would like to change this, use the HTConfig utility to change
which program is used.

Examples:

\freeformat
    Here we will setup a link between an animation, atom.anim, and the word
"electron" in the following sentence.  We will also pass some options to
the ShowAnim program.

\indent
In the atom, \\anim { -c -j3 df1:anims/atom.anim } electrons
\\endlink whiz around the nuclues.

\format
\indent
In the atom, \anim { -c -j3 df1:anims/atom.anim } electrons
\endlink whiz around the nuclues.

\format
    Of course to end the link you should have an \\Endlink command at the
end of your linked text.  This is important to remember or else the link
will continue until an \\Endlink command is found.

--------------------------------------------------------------------------

\bold \\PLAY { <smus filename> } \bold

     The purpose of this command is to link words/phrases to music.  When
double clicked on by the user, the corresponding <smus filename> will be
played with any options you have specified in between the {}'s.

    The default program to be run is PLAY, which should be in your path. If
you would like to change this, use the HTConfig utility to change which
program is used.

Examples:

\freeformat
   Here, assuming you use the Play program, it is almost essential to pass
parameters.  You simply place the parameters you would have typed on the
command line in between the {}'s.  These are passed to the play program
which sees them as if you had typed them in a CLI.

\format
\indent
Jimi Hendrix wrote the song \\play { i=df1:instr df1:songs/purple
haze.smus } Purple Haze.\\endlink

\indent
Jimi Hendrix wrote the song \play { i=df1:instr df1:songs/purple
haze.smus } Purple Haze.\endlink


\format
    Of course to end the link you should have an \\Endlink command at the
end of your linked text.  This is important to remember or else the link
will continue until an \\Endlink command is found.

--------------------------------------------------------------------------

\bold \\AREXX { <Arexx program, options, and arguments> } \bold

    This is a pretty neat keyword.  The \\Arexx keyword will start an Arexx
program along with any options whenever the linked text is double clicked.
If need be, the Arexx program can then talk back to HT through the main
body port (HT).  This command is asynchronous.  Arexx replies to these
messages \bold right \bold away, without waiting for the ARexx macro to
finish executing.  What normally would happen is that your document would
be "frozen" until the ARexx macro finished.  The \\Arexx keyword returns
control to your document almost immediately.  The Arexx command you
launched continues to run concurrently with your document.  Therefore the
user is able to continue using your document without having to wait for the
rexx program to exit.  If you want synchronous behavior, where the
document is "frozen", use the \\REXX command (see down below).

\link { TechInfo AREXX Support } To find out more about HT's ARexx port and
the commands it supports, click here.\endlink

    Any text that falls between the {}'s is passed directly to ARexx.  If
you would be able to type it in the CLI, you are able to do the same thing
here.  You specify the command name, options, and arguments, and ARexx
takes care of the rest.  You should remember that ARexx must be able to
find the command you would like to run.  Therefore it is usually best to
make sure the command is reachable or that you specify a full path name.

    Via the \\AREXX and \\REXX keywords, you have a \ital very \ital
powerful mechanism when creating documents.  Since ARexx is a standard
language for inter program communication on the Amiga, it is possible to
have your hypertext documents control your spreadsheet, your communications
program, or your word processor.  Think of the help facility you can make
with this!

\freeformat
Examples:

     1.)  It is also possible to have the database program XYZZY sort by a
      different field.  \\ARexx { sort_by_name.rexx } Click here to see
      this done. \\endlink

    In this example we have a hypothetical database program, XYZZY, which
has an ARexx port.  The documentation is describing how to sort on various
fields, and an ARexx program is linked in which will actually demonstrate
how to do this operation.  After double clicking the link, the user will
immediately get control of the document back, and the Arexx macro will run
to completion simultaneously, possibly opening its own windows etc.

     2.)  There is an \\Arexx { do_job.rexx -h some options } ARexx macro
      \\Endlink to accomplish this complicated process.

    This example sets up a link with the words "ARexx macro" and the actual
macro do_job.rexx.  We are also passing some options to this Arexx program.
The options are arbitrary, and merely for display, but show you that the
information in the link is as if you had typed it into a CLI.  When the
users double clicks on the word "ARexx macro", the do_job.rexx program will
be executed in parallel with the current document.

\format
    Of course to end the link you should have an \\Endlink command at the
end of your linked text.  This is important to remember or else the link
will continue until an \\Endlink command is found.

--------------------------------------------------------------------------

\bold \\REXX { <Arexx program, options, and arguments> } \bold

     This is a synchronous version of the \\ARexx keyword.  When using this
command, the message will be sent to Rexx, and the user will have to wait
until the Arexx program finishes.  This can be a little disconcerting for
the user if they don't get any feedback from the Rexx program.  What is
meant by synchronous is that your document will not be able to be
manipulated by the user \ital until the Arexx macro finishes.\ital   This
is very important to keep in mind when planning how things should work.
For more information, see the above lines on the \\AREXX keyword.

\freeformat
Examples:

     1.) If you would like to see this process step by step, simply
     \\rexx { show_steps.rexx -slow } click here.\\endlink

    This example will cause an ARexx macro to be executed (show_steps.rexx)
when the user double clicks the phrase "click here".  This could be useful
in that the user now has their attention directed on the new program, and
cannot go back and follow other links.    This is helpful if you would have
problems with multiple ARexx macros modifying shared data, or something
similar.

    Of course to end the link you should have an \\Endlink command at the
end of your linked text.  This is important to remember or else the link
will continue until an \\Endlink command is found.