Category : Pascal Source Code
Archive   : TPHYPER.ZIP
Filename : README.SRC

This software is provided with no warranties expressed or implied. Neither
the \author\, nor Indiana University will be held liable for any direct,
indirect, incidental or consequential damages resulting from the use of
this program. Your use of this program constitutes your agreement to this
disclaimer and your releasing the author and Indiana University from any
form of liability.

This \hypertext\ will explain the use of the \hypertext compiler\ and the
demonstration \browser\ which you are now using. It will also describe
\enhancements\ which have been added in version 1.2.

Note that several words and phrases such as "hypertext compiler",
"browser", "Index" and this word "\button\" appear in color different
from the remainder of the text. Note also that the word "author" is
highlighted. These words and phrases are buttons which can be pressed.
You navigate through the hypertext by selecting buttons which open windows
and display new topics perhaps with more buttons.

Press "H" (or any letter key) for help. Happy browsing!

\Index\
:Enhancements

Version 1.2 is functionally equivalent to version 1.1. The user
interface for the compiler, HTC120.EXE, is much improved. In addition,
the compiler now has the ability to create a \compiler batch file\ which
can run the compiler with the same options chosen through the front end.

The other major improvement is \MAKECFG.EXE\. This program allows you to
experimentally create a configuration file. The accompanying .CFG files
were created with this program. Try it!

The user interface for this browser, \DE120.EXE\ has been improved
slightly, although it is still intended to be run with command-line
parameters.

Path names are better supported in both HTC120.EXE and DE120.EXE.

\Index\
:MAKECFG.EXE

The \configuration file\ contains information
about the appearance of windows, information
which is embedded in the \hypertext database\
created by the \hypertext compiler\, HTC120.EXE.
The name of the configuration file is one of
the parameters which is required by the
compiler.

MAKECFG.EXE allows you to create a configur-
ation file interactively. It lets you select
color combinations dynamically, then create a
configuration file which, when made available to
the compiler, will produce the same color
combinations in the compiled database.

This program is especially useful for creating
configuration files for various \display devices\.

\Index\
:Display Devices

These programs are compatible with most
video monitors used on PCompatibles.
Different \configuration file\s (and
different compiled \hypertext database\s)
can be used on MDA, CGA, EGA, VGA, and
MCGA adaptors.

:HyperText Database

The \hypertext compiler\ produces a database
with built-in links connecting all frames as
indicated in the \source text file\. This
database can be processed and displayed by
this \browser\ or by user-written programs.

:Browser
A browser is simply a mechanism for allowing
the user to determine the display sequence
while reading a \hypertext\.
\Index\
:Button
A button is a word or phrase which identifies a topic
about which more information is available. It is used
to link the current window with another window which
contains information about the associated topic. To
select a button, move the highlighter bar to it and
press the ENTER or RETURN key. The new window will pop
up on top of the current one.
\Index\
:Hypertext Compiler
The compiler program is HTC120.EXE (HyperText Compiler
version 1.20). Its purpose is to convert a \source text file\
into a \hypertext database\. The database is accessible to any
program -- such as this one, \DE120.EXE\ -- which incorporates
the author's display routine (distributed as part of this
package).

The compiler can be invoked with \command-line parameters\
though none are required. If you simply type HTC120 and press
RETURN, the program will prompt you for all needed information.

In addition to the source text file, HTC120 requires a
\configuration file\ which tells it what colors and border style
to use for windows (\optional window information\ can be specified
for individual windows). \HTC.CFG\ is a \default\ configuration file
provided with this package.
\Index\
:Author
Steve T. Jones
Department of Math and Information Sciences
Indiana University at Kokomo
2300 South Washington Street
Kokomo, IN 46902
(317) 455-9330
[email protected]

I would appreciate hearing about your
impressions and in particular about any useful
applications of this software.
.
. NOTE THAT THE TOPIC BELOW SEEMS TO BE OUT OF SEQUENCE (ALL REFERENCES
. TO IT ARE BELOW IT). SEQUENCE DOES NOT MATTER IN THIS HYPERTEXT SYSTEM.
.
:ASCII File
An ASCII File is one in which the text is stored as ordinary
characters with no formatting, word-wrap, printer-control or
other non-text features. EDLIN, Sidekick, and PC-Write, for
example, all work with ASCII text. Most full-blown word
processors do not. Nearly all \word processors\, however, have
the ability to save or "export" ASCII files. The source for
this \hypertext\ was written with Symantec's Q&A and saved as an
ASCII file.

Because the source is a text file, creation and modification
of the database is done with a word processor. Chunks and
links can be added and updated without disturbing the display
program. Different versions of both the source and the
compiled database can be maintained.
\Index\
:Command-Line Parameters
All required parameters can be specified at the time the compiler
is invoked:

HTC120 [parameter ...]
/S
/D
/I
/C<\default\ window configuration file name>
/P
/E
/B

You may wish to look at some sample \usages\.
\Index\
:Compiler Batch File
The compiler can be invoked with all necessary information provided
with \command-line parameters\, thus avoiding the interaction involved
with the front-end dialog. With seven parameters (six required),
typing a complete command line can be tedious. If you go through the
front end (by just typing "HTC120", for example), you will be prompted
for all necessary information. At the end of the dialog, you will be
asked if you wish to create a batch file containing all the equivalent
parameters. If you choose to do so, subsequent compiles with the same
parameters can be accomplished by simply typing the name of the batch
file.

The "/B" parameter can be used to suppress this function. If you write
your own batch file with all parameters for invoking the compiler,
include "/BN" on the command line. If you don't, the compiler will ask
if you want a batch file created and will sit and wait for you to
decide if you want one! Batch files created by HTC120 include this
directive.

:Configuration File
The Configuration File provides \default\
window specifications. It specifies the
\colors\ to be used:
Window text background
Window text foreground
Window frame background
Window frame foreground
Buttons background
Buttons foreground
Highlighter background
Highlighter foreground
and the \border style\ to use.

Various \display devices\ may require different
configuration files. This package includes a
\default\ configuration file named \HTC.CFG\ which
was used during compilation of this hypertext.
Others include MDA.CFG for IBM monochrome and
LCD.CFG which shows the highlighter bar but not
the buttons on an LCD display device. These were
created with \MAKECFG.EXE\.
:HTC.CFG
Blue
Yellow
Black
White
Blue
LightCyan
Red
White
2
These values may be changed
with any word processor which
can save or export an \ASCII file\.

\Index\
:Colors
Each of the eight window colors can be specified by
number or name (case is ignored but each name must
be a single word):
0 Black 8 DarkGray
1 Blue 9 LightBlue
2 Green 10 LightGreen
3 Cyan 11 LightCyan
4 Red 12 LightRed
5 Magenta 13 LightMagenta
6 Brown 14 Yellow
7 LightGray 15 White
:Default
The word default refers to a
value or specification which is
assumed unless otherwise
indicated. For example, in many
cities the default speed limit is
30. This is the speed limit
unless a different limit is
posted.
:Border Style
Each window can have a border around it.
Borders are specified by number:

ÚÄÄÄ¿ ÉÍÍÍ» ÖÄÄÄ· ÕÍÍ͸
0 ³ 1 ³ º 2 º º 3 º ³ 4 ³
ÀÄÄÄÙ ÈÍÍͼ ÓÄÄĽ ÔÍÍ;

(0 means no border.)

:Usages
NOTE "Accept-All-Defaults" Usage:
HTC120 /SHYPER.SRC
Will use HYPER.SRC (/SHYPER.SRC), create HYPER.HYP
(\default\) and HYPER.HYX (default) using HTC.CFG
(default), will not echo source to printer (defaults
to /PN), will display error messages on the screen
(defaults to /ES), and will not ask about creating a
\compiler batch file\ (defaults to /BN)
HTC120
Will request all needed information
HTC120 /CMDA.CFG
Will use MDA.CFG (/CMDA.CFG) for configuration and request everything
else
HTC120 /SHYPER.SRC /DTEST1.DB /ITEST1.INX /PY /EB /CHTC2.CFG
Will use HYPER.SRC (/SHYPER.SRC), create TEST1.DB (/DTEST1.DB) and
TEST1.INX (/ITEST1.INX) using HTC2.CFG (/CHTC2.CFG), echo source to
printer (/PY) and display error messages on both screen and printer
(/EB) (You might want to answer "Y" when asked if you would like to
create and equivalent batch file.)
Note that all required information will be prompted-for if not included
in command-line parameters.
:DE120.EXE
The sample browser which you are using requires the name of the
\hypertext database\, the name of the index file, and an indicator
of which frame to display first. Similar to HTC120.EXE, command-
line parameters can be used:
/D
/I

/F
-or-
/1 (display the first frame in the database)
All information will be prompted-for if not provided on the command
line. The user interface for DE120 is less sophisticated than the
compiler's. DE120 would normally be used in a batch file with the
necessary parameters included; this usage is recommended. If some-
thing goes wrong, the program will end with an \error code\.

This display, if run from DEMO.BAT, was initiated with the command
DE120 /DREADME.HYP /IREADME.HYX /1
To display a hypertext called HELP starting with a frame called
"Getting Help" this command would be used:
DE120 /DHELP.HYP /IHELP.HYP /FGETTING HELP
(Note that case is ignored in specifying the frame name; see the
\source text file\ frame.
:Error Code

DE120: Errors unique to DE120
51: no database specified
52: no index specified
53: database not found
54: index not found

DE120: Errors which originate in the display function:
n00-n35: window error (should not happen)(!)
1nn: not enough memory for frame index
2nn: requested frame not in index
3nn: not enough memory to show any frames
4nn: version number conflict

HTC120: 1: source text file not found
2: configuration file (.CFG) not found
3: fatal errors, compilation aborted

:Source Text File
Text is written in small chunks with each chunk covering a specific topic.
Text in one chunk can refer to any other chunk. The source text file (an
ordinary \ASCII file\) contains the text to be displayed together with
directions to the compiler which enable it to build a display frame for
each chunk. A frame consists of the following components:
þ the text (no more than 23 lines of 78 characters)
þ a frame title which can be used as a \button\ in other frames (no more
than 35 characters in length)
þ information about the window the text will be displayed in
þ information about the buttons which link the frame to other frames
in the hyptertext (no more than 125 buttons per frame)
The frame title and \optional window information\ are specified by inserting
a "frame header line" before EACH chunk of text.\*\ As the \sample text file\
shows, the frame header line consists of a colon followed by the frame
title (see also \README.SRC\). The colon MUST be the \first character\ on the
line. A button is indicated by enclosing the word or phrase (which MUST
correspond to a frame title elsewhere in the source text file) in
!backslashes ("\"). Case is ignored ("Button" matches "bUTTON") but spaces
aren't. Backslashes must be used in pairs and the enclosed button cannot
span lines. Margins can be adjusted if necessary to ensure that each
button -- each pair of backslashes -- appears on one line. There is no
restriction on the number of buttons on a line. All other information
(window size, for example) is generated by the \hypertext compiler\.
:*
This is not altogether true: The
FIRST chunk does not require a
frame header line. Its name is
null and it cannot be referred to
by any other frame. This is
probably OK for an initial frame.
\DE120.EXE\ permits a null name for
the first frame to be displayed.
See \README.SRC\.
:First Character
In addition to the colon, two other characters have
special meaning as the first character on a line:

. (period) means that the line is a comment
which should not be treated as part of the
text. \README.SRC\ has a few comments as
examples.
! means that a colon at the beginning of the
line and ALL backslashes on the line are to be
ignored. This makes it possible to include a
backslash in the displayed text. It also
means that no buttons can appear on the line.

See \README.SRC\.
\Index\
:README.SRC
README.SRC is the \source text file\ for
this hypertext and is included in the
package. It might be beneficial to
print it and refer to it while
browsing this compiled version.
:Optional Window Information
If the \default\ window specifications (\border style\ and \colors\) provided in
the \configuration file\ are not wanted for a particular frame, the defaults
can be overridden by adding another colon following the frame title and
then listing the desired numeric (not text) specifications. The order is
the same as for the configuration file. For example,
:Hypertext : 0,15,0,15,0,11,4,15,2
means that for this frame (entitled "Hypertext") only,
window text and border will be white on black
the buttons will be lightCyan on black
the highlighter bar will be white on red, and
the border will be a double line all around.
\Index\
:Sample Text File
. Note the use of ! below -- allowing the backslashes to be displayed on
. the screen.
!:Intro
!This is a sample \hypertext\. It contains
!only a few \frames\ but will illustrate the
!concepts.
!:Hypertext
!Hypertext is non-sequential text. The
!reader navigates among \frames\ by
!selecting \buttons\.
!:Frames
!A frame is a window containing text. The
!frame may or may not contain \buttons\.
!:Buttons
!A button is a word or phrase which appears
!in enhanced text. Buttons link the text in
!one frame with other \frames\.

You wish to look at a \simulated display\ of this
hypertext.
\Index\
:Simulated Display
ÉÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍ Intro ÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍ»
º This is a sample hypertext. It contains º
º only a few frames but will illustrate the º
º concepts.ÉÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍ Frames ÍÍÍÍÍÍÍÍÍÊÍÍÍÍÍÍÍÍÍÍ»
ÈÍÍÍÍÍÍÍÍÍ͹ A frame is a window containing text. The º
º text may or may not contain buttons. º
ÉÍÍÍÍÍÊÍÍÍÍÍÍÍÍÍÍÍ Buttons ÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍËÍÍͼ
º A button is a word or phrase which appears º
º in enhanced text. Buttons link the text in º
º one frame with other frames. º
ÈÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍͼ

This is a simulated display of the hypertext produced from
the sample text file. Note that the buttons are not visible
in this simulation.
\Index\
:Hypertext
Ted \Nelson\ coined the term hypertext to refer to non-sequential text.
The central idea is that "everything is deeply intertwingled" (Nelson, 87).
Every product of human intellect is related to others which influenced its
creation. Additional connections may be discovered by others. Together,
these relationships form a complex multi-layer network of ideas (nodes)
connected by associations (links).

A parallel network of documentation, the "docuverse", embodies and
describes these products. The docuverse consists mostly of text -- books,
articles, manuals, ledgers and such. Unfortunately, the rich complexity of
the links in the network of ideas is not reflected in the docuverse.
Within a single document, the ideas are arranged sequentially, with perhaps
an index and notes such as "see Chapter 3" providing links. Links to other
documents are provided by citations and references within the document and
by bibliographic data bases and indexes without.

Still, text in the docuverse is basically sequential. "Often, there are
simultaneous and interpenetrating structures which need to be understood
separately and together." (Nelson, 87) Computers and video displays offer
the promise of realizing these complex structures by enriching the links in
the docuverse. This \browser\ is an example of \basic hypertext\.
\Index\
:Basic Hypertext
Basic hypertext is a network composed of fairly
small chunks of text, each concerning a
specific fact or idea. Chunks (nodes) are
linked to other relevant chunks by keywords or
notes which enable the reader to navigate from
chunk to chunk by association instead of
following a predetermined sequence.
.
:Word processors
The word processor can help in two ways. By setting a line length of 78
characters and a page size of 24 lines (the frame header line and 23 lines
of text, the word processor can help keep text down to the desired size.
Also, the program's search function can be used to ensure that each \button\
has a corresponding frame definition.
\Index\
:Nelson
Books by Ted Nelson:

Computer Lib/Dream Machines. Tempus Books,
Redmond, Wa., 1987.

Literary Machines 5/e. Ted Nelson, Swarthmore,
Pa., 1983.
:Index

\ASCII File\ \First Character\
\Author\ \Hypertext\
\Basic Hypertext\ \Hypertext Compiler\
\Border Style\ \HyperText Database\
\Browser\ \HTC.CFG\
\Button\ \MAKECFG.EXE\
\Colors\ \Nelson\
\Command-Line Parameters\ \Optional Window Information\
\Compiler Batch File\ \Sample Text File\
\Configuration File\ \Simulated Display\
\DE120.EXE\ \Source Text File\
\Display Devices\ \Usages\
\Enhancements\ \Word processors\