home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Black Box 4
/
BlackBox.cdr
/
editors
/
hypsh40c.arj
/
HYPDOC.LZH
/
CHAP6.TXT
< prev
next >
Wrap
Text File
|
1991-04-27
|
36KB
|
925 lines
HyperShell Users Guide Operation
HyperShell Operation
6 The HyperShell Reader
This chapter describes the operation of the HyperShell reader program.
As HyperShell is very configurable, this chapter concentrates on the
non configurable aspects, and on operation using the minimum default
configuration.
6.1 MSDOS environment
To use certain features of the HyperShell components, it is necessary
to have the COMSPEC environment variable and the PATH environment
variable set up correctly. Refer to your machine instructions for
details of how to check this. The PATH environment variable needs to
include the disk and directory where the programs to be run reside. If
a number of applications are to be run using HyperShell as a menu
system, the FILES statement in the CONFIG.SYS file may need extending
to cover all files that could be open at once.
To access hyperfiles from another directory or device, you can set up
a DOS environment variable called HSPATH, which can point to the
location of your hyperfiles and their indexes. This is done from the
DOS command line as follows - e.g.:-
SET HSPATH=B:\hypshell\
This tells the components that the hyperfiles can be found on drive B:
in directory `hypshell'. The HS,HL,HE,HC and HP components all check
for this environment variable, and default to the current directory.
6.2 Runtime files
The following files need to be present to use HyperShell to read a
hyperfile:-
HS.EXE or HL.EXE HyperShell program
yourfile.HYP The hyperfile
There may be other files present, depending on what the hyperfile does
and how you have configured the HyperShell system. For example:-
HYPSHELL.CFG To configure HyperShell
yournote.NTE \
yourmenu.MNU \ Miscellaneous
yourscript.HSF / support files
yourfile.TXT /
- etc -
- 97 -
Operation HyperShell Users Guide
6.3 Command line
To invoke HyperShell from the DOS command line, type
HS {options} {hyperfile} {frame}
- or -
HL {options} {hyperfile} {frame}
The hyperfile parameter is the name of the file to view using
HyperShell. It can have an extension if needed (the default is .HYP).
If not supplied, a hyperfile called HOME.HYP is assumed. If your
hyperfiles are in a special directory elsewhere on the same or another
disk, you should set up an environment variable using the SET command
(See your DOS manual) of the form:-
SET HSPATH=C:\HYPER\
The bracketed parameters are optional.
{options} are one or more of the following:-
Command line options
+---------------------------------------------------------+
|-n | Create restart file for notes |
|-r | Create restart file for notes, variables, frame |
|-s | Save screen for redisplay during session and on exit|
|-m | Force use of mouse emulator |
|-f | Display guide symbols on menus |
|-b | Suppress the retention of backtrack information |
|-a | Switch on autoreferencing |
|-u | Display available memory on exit |
|-x | Suppress filename suffix on frames in reference list|
|-t | Trace labels in scripts |
|-h | MDA/Hercules highlighting scheme |
|-g | CGA/EGA highlighting scheme |
|-z | Flash mouse cursor |
|-l | Don't highlight refs when using Type file option |
|-k | Don't highlight refs and strip 8th bit |
|-d | Use BIOS for display |
|-q | Stop Ctrl-C and Ctrl-Break |
|-v | -vVstring Set variable V to string |
+---------------------------------------------------------+
{frame} is the name of a frame to display initially. The first frame
in the hyperfile is otherwise displayed.
The -n and -r options indicate that any notepad information should be
saved on exit to a file called RESTART.HSF. Also, if this file already
exists at start-up, read it into the notepad store. If the -r option
is used, single character variables and the current frame name are
also saved and restored.
- 98 -
HyperShell Users Guide Operation
The -d option causes the BIOS routines to be used for text screen
display, and should only be used on those machines that are not
sufficiently compatible to work with direct screen display. Also use
with Desqview.
The -u option displays the amount of memory remaining, when the
program exits, and is used to see if the file is near the limit.
The -v option is used to pass information into the program, as it sets
the named variable to the named string (the string cannot have any
spaces in it).
The -t option is used to trace the labels in a script that is
misbehaving, and causes the script to stop and display a label
whenever it meets one.
The display adapter will be automatically sensed and an appropriate
highlighting scheme adopted. The scheme can be forced to the colour
schemes using the -g option, or to the monochrome schemes using -h.
The -z option, default for monochrome displays, can be used with
colour displays for flashing the mouse cursor to make it more visible
(in emulation mode only).
The -l and -k options permit files listed using the `T' action (Type
file) to be listed verbatim without the references expanded. The -k
option also strips the 8th bit for typing WordStar(tm) format files.
Note that tab characters appear as small circles in this mode.
6.4 Which program to use
The HS.EXE program provides for the reading of small to medium size
hyperfiles, and can be used for most applications where large media
files are not required, the limit being around 500 frames, depending
on total frame and title sizes. The HS program offers the advantage of
being smaller, and constrained in its use of memory if it is used as a
menu system. It also offers an option to swap itself out to disk when
running other applications, occupying just 1.5k of memory. It is
therefore ideal for menu systems, help systems and general
applications.
The HL.EXE program provides the same functionality as the HS.EXE
program, but permits all of the computers memory to be used for the
storage of index details. This permits very large hyperfiles, or a
cumulative collection of large hyperfiles, to be accessed.
If an `out of memory' error occurs whilst using HS, it is an
indication that you should change to using the HL component. If space
limitations mean that you cannot fit the HL component on a disk with
your hyperfile, you can compress the hyperfile, or possibly reduce the
length of the frame titles, or make some of the global items local to
a frame, or into external file based items.
- 99 -
Operation HyperShell Users Guide
The Hypop program provides a very small subset of HyperShell hyperfile
specification, in a small popup program able to handle fairly large
hyperfiles.
+------------------------------------+-----------------+
| Feature |HyPop|HS |HL |HI |
|------------------------------------+-----+---+---+---|
| Small program size | * | * | * | |
| Limited memory usage | * | * | | |
| Ability to swap to disk | | * | | |
| Ability to handle large hyperfiles | * | | * | * |
| Editing capability | | | | * |
| Resident (popup) capability | * | | | |
+------------------------------------+-----------------+
6.5 Interaction
Interaction with HyperShell may be performed using the keyboard or the
mouse, or possibly both. A typical hypertext application of HyperShell
would only require occasional use of the keyboard, but more advanced
uses will require substantial use of the keyboard. Whilst it is not
essential to use the mouse cursor for selection, there is a `mouse
emulator' provided, to allow you to use the cursor keys to move the
mouse cursor around the screen if you don't have a mouse.
6.6 The Mouse
If you have a Microsoft compatible mouse driver installed, it will be
used automatically, otherwise a `mouse emulation' mode will be used.
Any Microsoft compatible mouse should work satisfactorily. Genius and
other three button meeces can make use of the middle button, which
functions as the INSert key.
Specifying the -m option on the command line forces the mouse
emulation mode to be used, if the mouse driver causes problems or some
other software has been run which leaves the mouse in an aggressive
state (eg. GEM). If your computer `hangs' when you first run
HyperShell, this might be because of the mouse driver, and the -m flag
can be used to determine this.
On start-up, HyperShell positions the mouse cursor (A square block) in
the centre of the screen. Moving the mouse will move this block. You
would typically move the mouse to a highlighted reference and select
it.
The left mouse button, and the RETURN key, selects the reference over
which the mouse cursor is positioned. If a menu is presented for
selection, the left button is pressed over a choice to select it, or
pressed outside the menu to cancel the menu (but see below).
- 100 -
HyperShell Users Guide Operation
The right mouse button, and the ESCAPE key, has two differing actions
depending upon when it is pressed. When reading a normal frame
display, this button causes the main HyperShell control menu to
appear. When it is pressed during the display of a menu, a popup
message, a note or a paged display, it cancels that item. When it is
pressed during one of these displays in the execution of a script, it
also cancels the rest of the script.
6.7 The Keyboard
The keyboard may be used if a mouse is not available. It is also used
in support of a mouse.
The RETURN key is used for selections, as well as for terminating
typed responses to prompts and input fields.
The ESCAPE key is used as a cancel key, and has the same effect as the
right mouse button. It is also by default mapped to the popup control
menu.
The Home, PgUp and PgDn keys are used during frame displays and paged
displays, to move the display to the first, previous and next page
respectively.
The End key is used during a frame display to recall the screen saved
on entry if the -s command line option was used. This is useful when
the hyperfile is being used for a help system, and you want to recall
what you wanted help about. Pressing any key returns you to the frame
display. If -s was not used, the End key just refreshes the display.
The Keypad Ins and Del keys are used for adding and removing
references from the `notepad'. This is a list which is maintained
during your HyperShell session, and is used to store references that
you may not wish to follow immediately, but nevertheless wish to
`note'. The keys are used by pressing them when over the required
reference. A message is displayed to show you the results of the
action. Pressing the keys when not over a reference, when displaying a
frame, will result in the current frame having its reference added to
the notepad. The notepad information can be retained between sessions
using a notepad file. This can be initially created by using the -n
option on the invocation command line.
The `?' key is used to ask for help. It will usually display a menu of
topics for which help is available. When a topic is selected, a note
describing the topic is displayed. The help key is available in frame
displays and paged displays. If a particular hyperfile does not
support the help key, a message will be displayed to say that the help
menu is not available. The F1 key may in some hyperfiles be mapped to
the help menu, and in this case may offer more than simple notes from
the help menu.
- 101 -
Operation HyperShell Users Guide
The TAB and BACKTAB act as a quick means of stepping through the
highlighted references on display. These wrap around the display,
moving back to the beginning when they reach the end and vice versa.
The left and right cursor keys can optionally be mapped to these
functions as well.
Unshifted function keys are by default mapped to the control actions
provided by the main control menu. The three shifts applied against
the function keys are generally mapped depending on a particular
applications requirements. By convention, an application provides a
help display of actions mapped to the function keys.
The keys in the normal ASCII printable set may also be mapped to
actions. However, displayed reference mappings and menubar items may
use these keys, so permanent mappings are not always provided.
The frame text reference specification allows a key to be mapped to a
highlighted reference. This can be nearly any key or shift/key
combination available that is not mapped to an action. Normally an
alphabetic character is used for this purpose, being the initial
character of the reference. The provision of this facility is
sometimes indicated in the frame text by a reminder of the form `[x]'
to the left of the reference for which the `x' key is mapped.
6.8 Text string input
Some HyperShell actions require a text string to be typed in, rather
than just a single key, for example when an action prompts for a
string to search for, or for a file name, or when an input field is
selected.
When entering a text string, characters are echoed on the input line,
and can be deleted if a mistake occurs. The RETURN key is used to
terminate such an input string, as usual. When the text reaches a
certain length, being the maximum for that input field, the input is
terminated automatically. The ESCape key cancels the input, and can
cancel any script in progress as well.
6.8.1 Word picking
During text input, the mouse cursor is hidden. However, if PgUp is
pressed, the mouse cursor appears and can be moved around the screen.
If the mouse cursor is positioned over a word or number, pressing the
INSert key will cause that word or number to be entered as though it
had been typed. If you have a three button mouse, the middle button
can be used for this action. Pressing PgDn or a normal character will
cause the mouse cursor to disappear.
- 102 -
HyperShell Users Guide Operation
6.8.2 Copy cursor
When in picking mode (after PgUp pressed), pressing the HOME key will
make the mouse cursor act as a copy cursor. Each depression of the
HOME key copies a single character and moves the mouse cursor along
one place. Holding down the HOME key to auto-repeat will copy a
string character by character.
6.9 Moving about
The normal HyperShell display presents a full screen display
consisting of a header, fixed in format for any particular hyperfile,
a frame text section, containing the frame text for a topic, and a
footer, also fixed in format for a particular hyperfile. Any of these
sections can contain highlighted words, which can be selected to
perform various actions. These are known as `references'.
6.9.1 References
References are highlighted in some way to make them stand out from the
rest of the text. It may also be the case that highlighting is used
to enhance the appearance of the general display, and items so
highlighted are not selectable (you can distinguish these by their
lack of action when you attempt to select them - hopefully their
content and contextual circumstances will have already told you this
before you try).
To help you to know what resulting action a reference selection will
have, references are highlighted in different ways depending on type.
It will not always tell you what type they are, but in the majority of
cases it will.
6.9.2 Frames
Frame references are references to other frames of text, in this or
another hyperfile. Selecting one of these adds the current frame
reference to the backtrack list and displays the selected one.
Another form of frame reference does not cause the frame reference to
be added to the backtrack list before moving to the selected frame.
6.9.3 Notes
Note references refer to short notes about a particular topic, which
popup over the frame display. These can be local to the frame, or
local to the hyperfile as a whole. Further selections can be made
from notes, and the note will be cleared when any button or key is
pressed. A note can be used within a particular hyperfile to obtain
information from you by offering a number of choices for selection, in
a similar fashion to a menu.
- 103 -
Operation HyperShell Users Guide
6.9.4 Menus
Menu references pop up a menu from which a choice of actions is
available. Menus can be local to a frame or local to a hyperfile as a
whole. A choice can be made from the menu by moving the mouse cursor
to highlight the option, then pressing the left mouse button or the
RETURN key, or the menu can be cancelled using the right mouse button
or the ESCAPE key.
6.9.5 Scripts
A script is a sequence of actions, which acts like a small program
within HyperShell. A script can be cancelled whenever the computer is
awaiting an input, by use of the ESCAPE key. The presence of scripts
is not always obvious to the end user.
6.9.6 Actions
An action reference is used to show that some action other than one of
the above will be performed when it is selected. Normally the content
or context of the reference will give some clue as to the likely
outcome of selection.
6.9.7 Input fields
Input fields, when selected, allow a string to be entered. The string
is accepted when the RETURN key is pressed, or when the string reaches
the length of the field. The ESCAPE key cancels the input. Input
fields are generally used to input variables, but may be used for
almost any action. If there is something on display in the input
field, it is presented for editing when the field is selected.
6.10 Control menu
The control menu provides a means of controlling HyperShell where no
other key control or references are available. It is also a handy
means of accessing control functions. It provides the following
actions.
6.10.1 Home Frame
This selects the `Home' frame in the current hyperfile. This is the
first frame defined in the hyperfile, and is usually the introductory
frame, containing routes to the other frames.
In some hyperfiles, the first menu choice, also mapped to the F1 key,
may be used to present the help menu. This is a standard convention
for PC compatible software. The key is not mapped in this way by
default in HyperShell because certain hyperfiles may not provide a
help menu. To select the home frame, if this option is not available,
simply select the contents menu (usually F2) and then press `a' to
select the first frame.
- 104 -
HyperShell Users Guide Operation
6.10.2 Contents
This produces a paged list of contents, from which you can select a
frame as a frame reference in the normal way.
6.10.3 Backtrack
This displays the frame you were displaying before selecting the
current frame. Repeated selection takes you back to the original frame
you were displaying, one step at a time. When you reach the start, a
message will be displayed to tell you that you are at the beginning of
the list.
Certain frame references may control the stacking of backtrack
information, and cause the top entry to be overwritten rather than
stacked. This will mean that not all frames visited will be available
on the backtrack list. References for these frames, called `replace'
frame references, are highlighted in yellow rather than white when
displayed in text.
6.10.4 Select back
This produces a paged list of frames you have visited on the way to
displaying the current frame, and allows you to return to displaying
any of these frames, by simply selecting it as a reference.
6.10.5 Notepad
This presents a paged display of references inserted by you into the
notepad list. These references can be selected to action them at any
time after they have been noted, although certain of them will only be
available if you are using the same hyperfile as you were when you
inserted them. References can be removed from the list by pressing the
keypad DEL key when positioned over the reference. As mentioned
previously, the notepad can be retained between sessions using the
notepad file.
6.10.6 Search Text
This prompts for a search string, and then searches the current
hyperfile for a frame containing the search string in its title or
text. The search operation can be stopped by pressing any key.
6.10.7 Type file
This prompts for the name of a file, then produces a paged display of
the named file. If a suffix of `/string' is added to the filename, a
search for the string is immediately executed - see below.
- 105 -
Operation HyperShell Users Guide
If the text file contains any embedded reference annotation, this will
be highlighted, and you can select this to display frames, notes or
other items from the current hyperfile. If `autoreferencing' is
switched on, references in the text file that match any of the frame
names in the current hyperfile will be highlighted as frame
references.
You can use the PgUp, PgDn, Home and End keys to page up and down the
file, and to move to the start and end of the file. Function key 10
will cancel the file display without having any further cancel action.
The ESCAPE key will cancel the file display, along with any currently
executing script.
When you reach the end of the file, a message will flash to tell you
that you have reached the end. When this occurs pressing anything
other than the above keys will cause the file to be closed and the
last frame displayed to be shown.
The RETURN key or LEFT mouse button, if over a highlighted reference,
selects the reference, otherwise it returns to the current frame
display, and permits subsequent return to viewing of the file by use
of the `T' action with no parameter. A further T action, supplying a
parameter, will close the file on display and start a new one.
References selected from the text will be acted on. Certain references
will have a `T' action appended so that viewing of the file will
resume after the action has been performed.
The F6 or `/' key will prompt for a search string, and search forward
through the file for that string, stopping at the page containing the
string and highlighting any lines containing the string. A pattern
match search can be specified by starting the search string with the
`^' character. Further occurrences of the string can be located by
pressing F5.
The F2 or `#' key will prompt for a page number, and will then locate
and display the page.
Pressing a key during one of these searches will stop the search and
display the page currently being searched.
- 106 -
HyperShell Users Guide Operation
Type File - Control Keys
+---------------------------------------------------------+
|F1 or ? Help |
|F2 or # Request page number and go to page |
|F3 or Pg Up Go to previous page |
|F4 or Home Go to start of file |
|F5 Search for next occurrence |
|F6 or / Request search string and perform search |
|F7 Re-display current page |
|F8 or End Go to end of file |
|F9 or RETURN Suspend typing, allowing subsequent return |
|F10 Close file and exit typing |
| |
|Ctrl-Right Scroll Right to view text off screen |
|Ctrl-Left Scroll screen to left |
|ESCAPE Exit typing and cancel script |
|Pg Dn or other unmapped key - Go to next page |
+---------------------------------------------------------+
6.10.8 Do action
This allows the more expert HyperShell user to directly enter action
commands. See the list of actions in the Reference Guide for details
of what actions are available. An example is `Fframename', where
framename is the name of a frame in the current hyperfile, which
displays the named frame.
6.10.9 DOS Shell
This runs a DOS command processor, to allow you to run programs from
the DOS command line and return to HyperShell afterwards, by typing
EXIT at the DOS command prompt.
6.10.10 Exit to DOS
This causes HyperShell to terminate. If it was invoked with the -s
option, it will re-display the screen as it was when you entered
HyperShell.
6.11 Paged displays
Paged displays are displays of information which may take more than
one screenfull to display. The `Type File' display is a paged
display, and allows movement up and down the file, searching etc.
Other paged displays are used for the various lists - contents list,
notepad list, backtrack list etc, as well as extended directory
listings.
- 107 -
Operation HyperShell Users Guide
Whilst viewing a paged display, you may use certain keys as indicated
by the heading line. `Paging' implies that the Pg Up, Pg Dn and Home
keys can be used to move to the previous page, next page, and first
page of the list respectively. [key] indicates that the unshifted
letter keys indicated down the left side of the list can be used to
select items in the list. The Escape key can be used to cancel the
list and return to the frame display.
Also available during paged displays are the function keys.
Paged Display - Control keys
+--------------------------------------------------+
|F1 or ? | Help menu |
|F3 or PgUp | Previous page |
|F4 or Home | Start of list/file |
|F9,F10 | Quit |
|RETURN | Select reference |
|INS/DEL | Add / Remove reference from notepad |
|Pg Dn | or other unmapped key - Next page |
+--------------------------------------------------+
Not all these keys are available for all paged displays, and will
cause a next page operation if not available for a particular display.
6.12 Display states
The HyperShell reader initially displays a frame, and the frame
display can be thought of as the `base state' to which HyperShell
returns from other states.
The program makes excursions from this state to display menus and
notes as `popup' displays, or for paged displays.
The `type file' display can have popups displayed over it, but these
are really displayed from the base state, without the frame display.
Thus popup notes appear to retain the typed file display, but this has
been `re-entered' as can be seen by any search string being cleared.
- 108 -
HyperShell Users Guide Operation
+---------------+
| FRAME DISPLAY |----------+
| | Select new frame
| |----------+ +---------+
| | | +--------------+
| |--- Select Note --+ | NOTE DISPLAY |
| |------------------+ | |
| |--------+ | +--------------+
| | New Page +---------+
| |--------+ +---------+
| | | +--------------+
| |--- Select Menu --+ | MENU DISPLAY |
| |------------------+ | |
| | | +--------------+
| | +---------+
| | +- Select --+ +-Select-+
| | | +-------------+ | +--------------+
| |-+ | PAGED |-+ | MENU OR NOTE |
| |-+ | DISPLAY |-+ | DISPLAY |
| | | +-------------+ | +--------------+
| | +-----------+ +--------+
| | +- Run Program -+
| | | +------------------+
| |-+ | EXTERNAL PROGRAM |
| |-+ | DISPLAY |
| | | +------------------+
+---------------+ +---------------+
6.13 Error messages
6.13.1 Popup
A number of popup messages can appear - some from HyperShell itself,
and some from hyperfiles doing a `popup message' action. When you
have read a popup message, press any key to cancel it. The ones that
HyperShell displays are as follows:-
At beginning of list
You have reached the start of the backtrack list and cannot backtrack
any further.
{Item} is not available
Where item is one of Frame, Note, Menu, Script, File. The reference
you have selected directly or indirectly refers to the name of an item
that does not exist. An inconsistent hyperfile text is the probable
cause for this.
- 109 -
Operation HyperShell Users Guide
6.13.2 Error codes
The error code variable `?' is set whenever certain errors occur. It
may be displayed using the command `P$?' at the DO ACTION prompt. The
codes, with their associated meanings, are listed in section 9.8 of
the Reference Guide.
Fatal
These messages appear when a situation occurs where it is not
practical to continue running HyperShell. They are as follows:-
Out of memory - code nnn
HyperShell ran out of memory when attempting to allocate some for an
item. You were probably running a lot of hyperfiles, or a large
hyperfile of 500 frames or more. You can use the HL component, which
can handle much larger hyperfiles, or sets of hyperfiles.
Can't open file {filename}
The filename given does not exist. Check that you have its name
correct, that you have drive and directory paths if needed, or have
the HSPATH environment variable set correctly.
6.13.3 Other Problems
If something does not appear to work correctly, check that the various
environment variables are set up correctly as described in the first
section. If the COMSPEC and PATH variables are not set up, programs
cannot be run from HyperShell, and the DOS EXIT cannot be used.
- 110 -
