home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Black Box 4
/
BlackBox.cdr
/
editors
/
hypsh40c.arj
/
HYPDOC.LZH
/
CHAP3.TXT
< prev
next >
Wrap
Text File
|
1991-04-27
|
25KB
|
661 lines
HyperShell Users Guide Producing a hyperfile
Producing a hyperfile
3. Hyperfile Production
This chapter is an introduction to hypertext authoring using the
HyperShell system. Guidelines for the style and structure of
hyperfiles, and of the different application approaches are provided.
3.1 Authoring
Hypertext has introduced its own `jargon' into the language. As
hypertext material requires the same skills as conventional published
material, creating hypertext documents is known as `authoring'. The
process of creating an effective hypertext document is similar to
producing a reference book, although the structure is different, and
it needs new skills of visualisation to structure the material so that
the reader (or `user') can gain the most advantage from the material
and get to the information they are seeking. A great deal of planning
is necessary before a hyperfile is created. The information has to be
broken down into `units of display' called frames, and reference links
created to bind these frames together.
HyperShell files, known as `hyperfiles', consist of the text to be
read by the `user', and control information. In its simplest form, a
HyperShell document has to be split into `frames' of a certain size
and each frame needs to be identified. Some means of moving from a
frame to related frames is also necessary, even if it is just to
permit stepping through the frames sequentially. HyperShell provides
some standard commands to provide selection from a table of contents,
searching for a string etc. The real power of hypertext, however, is
provided by embedded references in the text to other frames or sources
of information. HyperShell provides these in a straightforward and
powerful way, and also provides popup menus and paged displays, as
well as a whole range of generic actions.
HyperShell applications may also make use of graphic screens from
other software. Selection areas can be set up on these so that a
mouse or the keyboard can be used to select objects in the graphic
display. So, for instance, components in a circuit diagram, parts in
an exploded view of some apparatus, towns on a map, or rooms in a
floorplan can be linked to further information about the object
chosen.
3.2 Different approaches
The creation of the hyperfile can be performed using one of a number
of methods.
- 19 -
Producing a hyperfile HyperShell Users Guide
The HyperShell integrated environment provides a ready means of
producing and editing material, and is suitable for small to medium
size hyperfiles (up to 500k). The integrated environment has the
advantage that immediate feedback can be obtained of how the hyperfile
will look and work. Also the mechanics of constructing the hyperfile
are taken out of your hands, to a certain extent. The integrated
environment will meet the requirements of many HyperShell application
areas.
As the hyperfile is of textual content, it is possible to use a
conventional text editor to produce the files. It is also possible to
use certain word processors, provided that they are capable of
producing output as a text file without pagination. Using a text
editor, larger hyperfiles can be produced in more manageable parts,
and combined using the HyperShell checking component.
This approach also has the advantage that the preprocessing phase of
the checker component can be used to translate hyperfiles written
using the verbose HyperShell Source Language into the terse HyperShell
specification language (known to some as `hyperglyphics'). This
approach does require that the author is familiar with the structure
of a hyperfile.
3.3 Overview of authoring tools
HyperShell provides a number of tools to assist with the authoring
process.
3.3.1 Material Preparation
Text fill
Raw text can be formatted with text fill and margins prior to having
HyperShell flags and directives added. Text fill allows rough text to
be gathered together into paragraphs between specified margins.
Text breakdown
Raw text can be split into frames if some identifiable break condition
can be defined. Thus different indent levels can be used to signify
frame breaks. Frame names can be added later, or could be obtained
from heading text.
Graphics capture and preparation
Graphics and text screens can be captured from other programs, and can
be set up with selection zones for use in HyperShell.
3.3.2 The integrated development environment
The integrated environment provides much more than an editor. It is
really a configurable applications environment which is as much a
freetext database as it is an editor for authors.
- 20 -
HyperShell Users Guide Producing a hyperfile
Editing control files
Ready made control files are provided to enable existing hyperfiles to
be edited, and to enable new files to be created from ready made
templates.
Types of editing
The editing environment can be used without configuration (although
this needs a knowledge of the language), with an environment control
file, or with configuration built-in to a hyperfile.
3.3.3 The preprocessor / checker
The preprocessor
The preprocessor allows HyperShell language to be specified using a
verbose macro language.
It also allows a number of files to be combined to form a hyperfile.
This can be used to glue a large application together, or to build
hyperfiles from libraries of pre-configured sections.
The preprocessor is itself configurable, allowing different and
additional macros to be specified.
The checker
The checker performs a full checkout of your hyperfile, including all
cross references, syntax and sizes. It produces a summary of items,
and can also produce reference and cross reference lists.
3.3.4 The formatted print
The formatted print program provides many different types and levels
of detail of printout of the hyperfile.
Printouts for users
A paginated printout with optional glossary and index is available for
the user to use as hard copy of a reference hyperfile.
Printouts for authors
Full item printouts with reference summaries for each note and frame
are possible. These provide printed documentation for a complex
hyperfile.
- 21 -
Producing a hyperfile HyperShell Users Guide
3.4 Developing a hyperfile
Before producing a hyperfile, it is advisable to decide what form it
is to take, what fixed information is to appear on the frame display,
whether any changes to the control menu are necessary, whether any
keys are to be mapped globally or locally, and whether any special
highlighting schemes are to be used. These factors can then be taken
into account when producing the main text.
The structure of the hyperfile can be designed using an outliner, or
sketched out on paper.
3.4.1 Original material
The HyperShell integrated development environment provides the ideal
environment for entering new material. Immediate feedback is
available on how the application will appear and interact.
Template hyperfiles, and other examples, can be used for the basic
skeleton of the application. These can be adapted to fit the specific
requirements of the application.
3.4.2 Using existing material
Existing textual files, provided they are not special format Word
Processor files containing control characters etc., can be adapted
fairly readily. A text editor or word processor can be used to break
the file into sections, inserting a .FRAME section header before each
frame, with a suitable topic name.
The HyperShell integrated environment can then be used to alter the
layout of the frames, to split the frames into further frames or local
notes, to add references using autoreferencing, and to restructure the
hyperfile.
The hyperfile checker can also be used to add cross references to
existing material, using the autoreference facility, and to check the
cross reference integrity of the hyperfile. The checker also has a
preprocessor phase which can accommodate compound document structures
by bringing together parts of documents from other sources.
Small text files can be inserted into frames by use of the insert file
facility in the editor.
Captured text screens can be inserted into the text using the insert
screen feature in the editor.
Small text files can be used as popup notes, although it is preferable
to integrate these with the main hyperfile, as global notes.
- 22 -
HyperShell Users Guide Producing a hyperfile
3.5 Guidelines
3.5.1 Naming
The names of frames and other items in the hyperfile are a very
important ingredient of the file, and careful naming will contribute
both to the setting up and to the use of the hyperfile. The names of
items are not limited to single words, and can contain spaces. It is
preferable to avoid multiple spaces, and you must ensure that no
trailing spaces are added to the name. The name, when used as a key,
is not case sensitive, so the most appropriate case mix can be used
for the name. Names of items must not exceed 30 characters, but it is
hoped that the majority will not exceed half of this. Names should be
as simple as possible, whilst retaining sufficient text to be
meaningful and distinguishable.
Frame names
The choice of suitable frame names is most important, and the names
should be chosen as part of the planning activity, rather than as and
when you need to supply them. As the names are used in references
from other frames, they could be chosen to match the words or phrases
used in the text. This is very much a chicken and egg situation, as
you may well want to enter the text after setting up the skeleton
file.
One way of achieving this is to produce a list of temporary names for
the frames to act as place holders. Once you have entered the text
for all the frames, and before you have added any references, you
could study the text to see what form the references would take. You
can then make the references consistent, change the frame names to
reflect these, and autoreference the frames. This will help you to
see if sufficient references have been flagged.
Frame Titles
The frame title text is almost as important as the name. It appears
in the contents list and search list, and is used in the fast search.
It is therefore important to choose a title which will give a good
indication of what the frame is about.
Other items
The note, menu and script names are important only if they are
directly referenced from the frame or note text, but it is obviously
helpful to keep these names short and meaningful for all cases. The
menu name and the note name will be displayed at the top of the
respective popup displays, so should be kept to a length commensurate
with the options or text lines.
- 23 -
Producing a hyperfile HyperShell Users Guide
3.5.2 Style
The hyperfile should be clearly laid out to permit ease of
maintenance.
The single control items should come at the start of the hyperfile.
The INDEX specifier should come first, followed by the HEADER and
FOOTER sections. Global notes, menus and scripts should come next in
the file, and should be grouped by purpose. The frame specifications
come next. Each frame specification contains the FRAME section,
followed by any local notes, menus and scripts.
The format and content of the information should be consistent. The
frames and notes should be written in plain, simple to understand
language, and technical terms should be confined to the vocabulary of
the intended user. Global notes should be used to explain any
technical term which the user might not understand. Terms should be
consistent in use.
Text should be presented in short paragraphs, and should have a
consistent left hand margin and a balancing ragged right hand margin.
The justification of text by inserting extra spaces throughout the
line to give a uniform right hand margin is not recommended, as it may
cause references to become inaccurate, and is now widely recognized as
not being of any help when viewed on a screen in this form.
The information held within a frame or a note should be complete, and
capable of being read on its own. A frame should not present more
than half a dozen different concepts, and a note should only present
one new concept. The information must be as accurate as possible as
any inaccuracies will reduce the users confidence.
Unlike a book, hypertext material is usually read in a non-linear
fashion, so no part of the text can assume that other parts of the
text have been read. Cross references can, of course, readily be
added.
3.6 Different application structures
3.6.1 Narrative Hypertext
For narrative hypertext, the frames should be organised so that a
logical thread can be followed. Supporting threads then form
offshoots from this main thread. The resultant structure will
probably be a network structure, based on a linear or hierarchical
backbone. Global and local notes can be used in support of the main
text.
- 24 -
HyperShell Users Guide Producing a hyperfile
3.6.2 Help systems
For a help system, each frame can relate to a particular command name,
command mode or technical term. Each frame should provide a complete
packet of information, and supportive frames need only be produced and
referenced as required. The structure for a help system is usually a
hierarchy, with occasional cross-references forming network links.
Global and local notes can again be used to explain odd terms used in
the main text. For context related help, a number of `entry' frames
can be created, each supporting a hierarchy of further information,
breaking down the detail of a topic; a top level frame providing a
menu of these entry frames is also useful as a general entry point.
HyperShell can be used as a context related help facility from your
own programs. Your program needs to execute the HyperShell program,
specifying the hyperfile name and the `entry' frame name as
parameters. HyperShell can set its exit status to pass numeric
information back to your program on exit, if required, by use of a
numeric parameter on the Q action.
3.6.3 Menu systems
For a menu system, each frame forms a menu node in a hierarchy,
although a hierarchy is not strictly necessary. Input fields can be
used to supply parameters to programs. Dynamic menus formed from
wildcard directories can be used to select a file to be used as a
parameter, the resultant value being placed in a variable prior to
program invocation. Scripts can be executed to perform sequences of
programs, and to do limited validation on input parameters. The
HyperShell exit status can be set by use of a numeric parameter to the
Q action, and this may be tested in a batch command file to influence
the control flow.
3.6.4 Expert Systems
For an expert system, a hierarchy of frames can be set up to reflect
the nodes in a decision tree. Hierarchies of menus can be used as
well as, or instead of frames in this decision process. Local notes
can be used as `help' about choices. Scripts can be used to perform
limited processing and decision making using control flow and
expression evaluation.
3.6.5 Computer Aided Instruction
For computer aided instruction, a sequence of frames can present
information about a topic, then offer a multiple choice answer frame.
Correct answers move on to next topic frame, incorrect answers move
back to original topic frame. Variables can be used to monitor
progress and record error levels.
- 25 -
Producing a hyperfile HyperShell Users Guide
3.6.6 User Interface Prototyping
For user interface prototyping, a number of different frames can be
set up to present alternative layouts for an application input screen.
Input fields, menus, notes and scripts can be used to simulate
interaction style. Programs can be executed to provide substance to
the application.
3.6.7 Directory browser
For a DOS manager, or directory browser, a basic script running
extended directory listings should be set up to allow browsing of
directory structures and examination of text files. Actions to take
against a particular file can then depend on file type, or could be
selected from menus. Use of system variables < and > permit file name
and extension to be accessed within the script.
3.6.8 Text file viewer
For a general text file viewer, with supporting `topic' hyperfile, a
hyperfile should be set up with topic frame names chosen to pick up
topics mentioned in the general text files. Autoreferencing should be
switched on in the setup script using the action `O41'.
3.6.9 Adventure
For an adventure system, the network of frames can be made as complex
as possible, and menus, notes and scripts can be used to good effect.
Variables can be used to hold the state of play. The `ghost'
highlighting scheme is effective in an adventure, as the text
highlighted in this manner is not visible until the mouse cursor is
moved over it. A new wave of adventures, known as `hyperware', is due
to arrive shortly, and will use hypertext principles, albeit in a
graphic context.
3.7 Master hyperfile
Where a number of hyperfiles are used together, it is useful to bind
them with a master hyperfile which describes each and references the
introductory frame in each. More complex structures are, of course,
possible, and the structuring then depends on the application.
The concept of a controlling file is also supported with the HOME
hyperfile. If a hyperfile name is not supplied on the command line to
HyperShell, a default hyperfile name of HOME.HYP is assumed. The HOME
hyperfile can be thought of as a `home base' which provides routes to
the other hyperfiles in your system. It is therefore generally a
small menu system, with some frames in a hierarchy. It could be a
small hyperfile which displays a graphic screen with icons on it
representing the various hyperfiles which are available.
- 26 -
HyperShell Users Guide Producing a hyperfile
3.8 Alternative structure
An alternative hypertext structure is possible which permits existing
text files to be more readily adapted to a hypertext system. With
this structure, a small controlling hyperfile may be set up, which may
provide a set of supporting frames and switch on autoreferencing. The
main hypertext material will be held in a number of simple text files.
These files will contain cross references to other such files in the
form:-
~Areference~PTfilename.txt~E.
These cross references could occur anywhere in the text of the file,
and would be highlighted when the file is browsed. Other forms of
highlighting can be chosen by using ~F, ~N, ~M etc. as introductory
flags. The autosearch feature can be used with this form of cross
referencing, as a string can be given with a text file name, which
will be automatically located when the file is typed. This means
simply adding a `/search string' suffix on the T action (with or
without a filename supplied). Thus an embedded reference with an
action string of `Tfilename.ext/search string' would move to
displaying `filename.ext' and immediately locate `search string' in it
- or stop at the end of the file if the string is not located.
The control hyperfile could provide an action in its header or footer
text, or on its control menu, which will have the action T@d*.TXT (or
T@L*.TXT if there are more than 20 text files). This will enable a
menu of these files to be presented for initial selection. Of course
the files could be grouped by initial letter and a number of actions
of the form T@dA*.TXT, T@dB*.TXT etc. could be provided, possibly
from a menu. Also the popup notes can be made available from a menu
in a similar fashion using the action t@D*.NTE.
The MSDOS subdirectory facilities provide a convenient means of
structuring sets of text files in a hierarchy. The `C' action allows
selection of a subdirectory, and the same set of dynamic menus can be
used at each level. The original directory path is always available
via a system variable for when a return to `base' is required. The
intermediate levels of directory pathname can be stored in a list to
permit `backtracking'.
Other forms of reference can be used in the text files, and the text
file display will be reentered after a Note display, and after DOS
command execution. Explicit reentry can be achieved by including `;T'
at the end of any action strings in other forms of reference.
It is not strictly necessary to have a controlling hyperfile at all.
If a simple text file with embedded references etc. is named instead
of a hyperfile when HyperShell is invoked, then that file will be
treated as a hyperfile with one frame containing the text in the file.
- 27 -
Producing a hyperfile HyperShell Users Guide
The `file as note' reference is particularly applicable to this form
of hypertext structure, and permits a set of supporting popup notes to
be supplied from small text files. These can contain references to
further note files, or to further text files to be `typed'.
The degree of integration of the two hypertext approaches is variable,
and it is quite possible to have a hybrid approach offering
substantial material from both hyperfiles and text files.
The alternative approach has the advantage that the text files and
notes can be produced `on the fly' using a text editor possibly driven
from the controlling hyperfile. This offers a number of attractions
to those gathering information for cross referencing.
- 28 -
