Otherware/Otherware_1_SB_Development.iso/amiga/utility/text/ht.lha/hypertext/Documentation/Creating

Text File | 1990-12-24 | 13.1 KB | 282 lines

\help Ht.help
\center
\bold Creating Your Very Own HyperText Documents
It's easier than you think! \bold

\format
     O.k., so you want to know more about creating your own multi-media
documents.  It's fairly simple as you will soon see.  All you need is a
text editor, something to write about, and a little creativity. (It
wouldn't hurt to read this file though ;-).

\underline What will HT allow me to do? \underline

    HT is based on a simple markup language.  This means that you embed
special commands in your text and these commands let you change text styles
(bold, italics, or underline), create links, and do simple text formatting.
Obviously there needs to be some way to distinguish an HT command from
regular text.  In HT, all commands begin with a '\\' character.  Whenever
HT sees a '\\' character in your text, it assumes there is some sort of
command following.  You can override a single '\\' by putting two '\\'
characters in a row (just like was done above to get a single '\\'
character).

\underline How do I put links and style changes in a document?\underline

    The commands you embed in your text are just a '\\' character followed
directly by a keyword and a space.  For example, to turn bolded text on,
you would use the \\Bold command.  That is to say, you would put a \\Bold
keyword at the place where you would like bolding to start, and another
\\Bold command to turn off bolding.  All HT commands take the form of a \\
character followed by a single English word and a space.

    In the HT markup language, '\\' keywords can begin anywhere on a line,
but must be ended with a space.  This means that after every keyword, there
should be a space.  This is important to remember as otherwise, if you
don't follow the \\ command with a space, some of the text you want
displayed would look as if it was the \\ keyword and not be displayed.

\freeformat
\bold Here are the commands HT offers: \bold

\italic
      \\Link     \\Bold       \\Title
      \\Show     \\Italic     \\Location
      \\Anim     \\Underline     \\TextColor
      \\Sound     \\Center     \\Fgcolor
      \\Play     \\Format     \\Bgcolor
      \\ARexx     \\Freeformat     \\Help
      \\Rexx     \\Indent     \\Font
      \\Run      \\Location
\italic

    If you happen to use a text editor that supports ARexx, you are in
luck.  Provided with HT, are sets of ARexx macro programs that work with
TxEd+ and DME. The macros take away the tedium of typing in '\\' commands.
They allow you to enter most HT commands with the mouse, via hotkeys, or
from a menu.  To find out more about these Arexx macros, \Link {
Editors.txt } click here.\endlink


\center
Let's get to the meat right away.
There are three catagories of '\\' commands. They are:

\freeformat
\indent 20
\link { SetupInfo } Setup Commands \endlink
\link { TextInfo } Text Style and Formatting Commands \endlink
\link { LinkInfo } Link Commands \endlink


\format
\underline How write HT documents \underline

     The format which you type things in for HT is no different than
normal typing. HT accepts plain textfiles and will simply display them.
You can add many bells and whistles to this however to make the document a
more effective display/learning tool.

     You can use different \link { TextCommands } text styles \endlink for
emphasis.  You can use bold, italics, and underlining as needed.  Each
window can also have it's own \link { SetUpCommands FONT } font.\endlink
And it is possible to set the color of the text for each window.  These
facilities are for helping get your point across, so it's a good idea to
know about them.  The file \link { Textcommands } TextCommands \endlink has
more information on text styles and such.

     To create your first hypertext document, you need to use a standard
text editor to create a file.  \Run { /c/ed } Click here to run the
included text editor (DME).\endlink    When you have started up your
editor, arrange the windows so you will be able to work with this one and
the text editor. (You may want to just take notes on this section, and then
edit them directly).

     Now all you have to do is type in some text.  You can write about
anything, but for now we'll write about the Amiga.

     Suppose the following lines were typed into your editor:

\indent 10
The \\bold Amiga \\bold is a very interesting personal computer.  It has
many features which make it distinctive against the bland world of IBM
clones and black and white Macs.  The \\bold Amiga \\bold is \\italic The
Computer for The Creative Mind.\\italic

    That text would be displayed by HT like this:

\indent 10
The \bold Amiga \bold is a very interesting personal computer. It has many
features which make it distinctive against the bland world of IBM clones
and black and white Macs.  The \bold Amiga \bold is \italic The Computer
for The Creative Mind.\italic

    You have just begun the creation of a "hypertext" document.  We started
simple however, and only put in style changes.    As you can see, one command
turns the effect on and another turns it off.  For example, the \\Bold
keyword before the word "Amiga" tell HT to turn bolding ON, the \\Bold
command that follows "Amiga" tells HT to turn bolding off.

    Real hypertext however, requires links to be defined between words in
the current document and words that exist elsewhere.

     With HT this is easy to do.  Lets look at exactly what is needed to
add a \ITALIC real\ITALIC  hypertext link.  We'll add a sentence that
mentions the creator of the Amiga, Jay Miner, and we will link his name to
a section heading in another file (non-existant at the moment) called
Miner.txt.

\indent 10
The \\bold Amiga \\bold is a very interesting personal computer.  It has
many features which make it distinctive against the bland world of IBM
clones and black and white Macs.  The \\bold Amiga \\bold is \\italic The
Computer for The Creative Mind.\\italic   The Amiga computer was the
brainchild of \\Link { Miner.txt Section 3 } Jay Miner.\\Endlink

    That text would be displayed by HT like this:

\indent 10
The \bold Amiga \bold is a very interesting personal computer. It has many
features which make it distinctive against the bland world of IBM clones
and black and white Macs.  The \bold Amiga \bold is \italic The Computer
for The Creative Mind.\italic  The Amiga computer was the brainchild of
\link { miner.txt Section 3 } Jay Miner.\endlink

    Let's look at what was added.  The sentence we added starts out as
normal text.  Then we see a \\Link keyword.  This tells HT we are starting
to define a Text link.    An open brace ({) comes next.  The curly brace ({})
part is common to \ital ALL \ital links.  The information between the
opening '{' and closing '}' tells HT what it needs to know about the link.
Since this is a text link, we are saying to link the phrase "Section 3" in
the file "miner.txt" to the text after the closing '}'.  We need some
way to tell HT to stop linking text, and we do this with the \\Endlink
command.  All link commands use the \\Endlink command to end a link.

    Now if you were to continue elaborating on the Jay Miner topic, you
would probably put a bunch of information about him in a seperate file.
Then whenever his name comes up in your writing, you simply create a link
to the file you have written on him.

    There you have it.    You have created your first hypertext link!  Now
you can double click on the words "Jay Miner" and bring up the reference.
That's all there was to it.  Again, if you happen to use an \link {
Editors.txt } ARexx compatible editor,\endlink    you would be able to point
and click your way through defining a link instead of having to type the
'\\' commands.


    Lets do another example.  This time, suppose we are writing about
the first American Space missions.  We'll just say we are in the middle of
discussing when the first spaceship landed on the moon.  There is a famous
little snippet of digitized voice where the astronauts say "Roger Houston,
the Eagle has landed".  It would be nice to link this piece of sound
(assuming you had it on disk) into a sentence discussing landing on the
moon. Suppose you had typed :

\freeformat
\indent 10
    Finally after many tense moments, the astronauts
actually landed on the moon.  Even though their
\\Sound { eagle.sound } voices were calm,\\Endlink
you can't imagine the excitement they felt.

Which of course gets displayed by HT like this :

\freeformat
\indent 10
    Finally after many tense moments, the astronauts
actually landed on the moon.  Even though their
\Sound { eagle.sound } voices were calm, \Endlink you can't imagine the excitement
they felt.


\format
    This example links the phrase "voices were calm," to the sound
"eagle.sound".  Double clicking anywhere on "voices were calm," causes the
sound "eagle.sound" to be played.  Similar to before, we have the \\Sound
keyword which tells HT we are starting to define a link.  This time the
link is to sound, so the text in the {}'s is relevant to playing a
digitized sound.  However, the format is exactly the same as a text link.
The information between the {}'s is the object being linked \bold TO.\bold
Since this is a sound link, we put the name of a sound sample there.  The
text after the closing '}' up until the \\Endlink keyword is the linked
text (where you would click to trigger the link).

    Although that was a somewhat long-winded explanation, it does cover
exactly what is going on.  The link keywords are relatively simple, but
important to understand as they are the critical to creating effective
hypertext documents.

    Those two examples basically cover all you need to know to create true
hypertext/media links.    For example, suppose you instead wanted to link the
sentence about the astronauts to a digitized picture of the astronauts in
their space capsule.  All you would have needed to do is used the \\Show
keyword instead and the name of the picture you wanted displayed.  As you
can see, creating links is very straightforward, and all the link types are
created in exactly the same way.  This makes things easy, as once you learn
one type of link, you have learned them all.


\underline Summing up so far\underline

    So far, we have covered the beginnings of creating a hypertext
document.  You should have a general idea of what it takes to make a real
hypertext document and some of the things you can do.  We've also covered a
few of the commands and how to put them to use.

    There are more complete descriptions of the individual commands in the
files \link { Linkinfo } LinkInfo, \endlink \link { setupinfo }
SetUpInfo, \endlink \link { TextInfo } TextInfo.\endlink

    After going over the commands, you can start on your way to mastering
this new form of media.  For now, we'll cover some background on designing
hypertext documents.



\underline Hints and tips on designing Hypertext documents \underline

    When you begin creating a set of Hypertext documents, you can't just
start typing away.  Well you can, but you will probably find that after
about 20-30K of typing, that you have a large conglomeration of text that
is too linear in fashion.  Granted different people work differently, but a
little planning will save you a \ital LOT \ital of frustration.  Designing
a coherent structure to your documents will help \bold you \bold decide
where to put links and help your reader understand the content better.

    Regardless of the method you choose, one thing you should keep in mind
is that the files you create should be small.  There are several reasons
for this.  Firstly, it breaks things down nicely into individual sections
which are easy to reference and link in other documents.  Secondly it
keeps things manageable.  Third, it reduces memory requirements and disk
loading time for someone who just wants to see a small section of your
file.  This part is very important.  People are much more reluctant
to use your information if they know it takes 30 seconds to load a 300k
file from floppies.  Keeping individual sections in reasonably small files
will again, save you and your reader lots of hassle.

    A quick outline of your ideas on paper or with a paint program will
help you visualize what you are planning.  Then you can fill in the parts
as you go along.  With HT it is easy to do a part at a time and fill in
links as you go.  You can create links to files that don't yet exist, and
then when you do create the file, all your links will work as expected.

    Another method is to first create all the individual files with only
minimal HT specific information in them.  Then when you have finished a set
of documents, you can go back and fill in the link information as
appropriate.  If you work best from paper, it can sometimes be useful to
print up each of the individual files and then go back with a red marker
and indicate the links as needed.  Generally if you like to see the whole
picture at once, this is a good way to do it.


     As with anything, there are certainly lots of ways to go about
creating a set of hypertext documents. I've just tryed to share a few tips
and hints that I have come across while writing this documentation.

     At this point, you should find your way to the other documents on the
disk.  From here, probably the best thing would be to look at the file
\link { LinkInfo } LinkInfo.\endlink   You migh also want to go to view the
file \link { TextInfo } TextInfo.\endlink