1 INTRODUCTION
The Starlink HLP system is a set of subprograms and utilities which allows an application program to
retrieve named items from a hierarchically-arranged library of text.
The facility is functionally very similar to the VAX/VMS Help system. The major differences are that
the Starlink HLP system (i) is implemented in a portable way and is not tied to the VAX, and
(ii) allows independent creation of multiple libraries which are bound together at run-time and
appear to the user as a single “tree”. The system is written in a free-standing manner and does not call
any other Starlink packages.
The present document will be of most interest to application programmers, though users of
application packages which incorporate the HLP system may find Section 2 of some value. Section 5
is relevant only to those providing software support for the package, or others who are interested in
the internals of the system.
1.1 Comparison with VMS Help
Readers already familiar with the VMS Help system may find it most convenient to begin by looking
at how the Starlink HLP system differs. In the list, below, the most useful or significant features are
described first, with less important differences later.
- The package is portable, and available from Starlink in source form.
- The Starlink system allows different parts of the help text tree to be stored in separate
files which are joined at run-time, transparently. It is possible to refer to a file from more
than one point in the hierarchy.
- If no keyword is supplied, the VMS Help system delivers the help information for the
“HELP” topic, though this behaviour can be suppressed. In the Starlink HLP system each
library has a unique top-level topic which is returned under these circumstances.
- In the VAX version, the “...” ellipsis feature only works for top-level topics. In the
Starlink HLP system ellipsis can be used from any level.
- The keyword matching capabilities are slightly more elaborate in the Starlink version: a
keyword can consist of multiple words, separated by underscores, each of which can be
individually abbreviated. For example, the keyword “ACTIVE_GALACTIC_NUCLEI” could
be abbreviated “A_G_N” (or “A” etc).
- In both systems, “%” and “*” wildcard characters can be used when specifying the keyword
to be searched for. In the VMS system these characters must not form part of a keyword
in a library. In the Starlink system it is possible (though not recommended) to use such
characters, their special function being suppressed by preceding them with a “”
“escape” character in the search string.
- In the Starlink system there is no capability for specifying different help libraries on the
command line. Any such facilities must be provided by the application.
- The VAX system treats a keyword beginning with the character “/” as a special case,
signifying a command qualifier. This feature does not exist in the Starlink HLP system;
all topics and subtopics begin with a level number.
- Like the VAX Help system, the Starlink HLP system ignores records beginning with “!”.
However, the Starlink system allows exclamation marks to appear in HLP text, whereas
the VAX system would interpret them as end-of-line comments.
- The package includes subprogram interfaces and utility programs only; no equivalent of
the DCL HELP command has been implemented.
- The Starlink system offers fewer library maintenance facilities. In particular, a library has
to be rebuilt in its entirety from source when a single topic is changed (but note that pieces
of library can be separate files in the Starlink system).
- The VMS routine LBR$OUTPUT_HELP supports five options (through its flags argument)
that are irrelevant for the Starlink HLP_HELP routine. The only option common to both
is the one which enables and disables interactive prompting.
- In the Starlink HLP system a series of keywords is separated by spaces; in the VMS Help
system, “/” can also be used.
- There are minor differences in the handling of unusual and unimportant conditions,
e.g. duplicate keywords in a library, use of punctuation characters in keywords.
- In the VAX system, top-level topics always appear in alphabetical order. In the Starlink
system they appear in the order specified in the help source, as do subtopics in both
systems.
- There are small differences in the way blank lines are handled. In particular, multiple
blank lines preceding and following the text for a given topic are ignored in the Starlink
version.
- There are unimportant differences in the formatting of output text – where blank lines
occur, what keywords are converted to uppercase, etc.
1.2 Portability
Although the Starlink HLP facility is functionally similar to the one provided with VAX/VMS, it is not
tied to the VAX, makes no use of the VMS Librarian utility and Run-Time Library and does not
depend (to any significant extent) on DEC Fortran extensions. Written almost entirely in
ANSI-standard Fortran, the few unavoidable machine and operating system dependencies are
isolated within a small number of routines which are supplied in different forms for different
platforms. At present, VAX/VMS, Sun/SunOS, Sun/Solaris, DECstation/Utrix and DEC
Alpha/OSF-1 variants are available (there is also a private PC/MS-Fortran version available from the
author), plus functionally inferior but machine-independent variants.
The present document describes only the VAX and Unix versions. The VAX release contains also the
PC versions. More information on portability issues can be found in Section 5.2.
1.3 Package Contents
The main components of the Starlink HLP system are as follows:
- A utility program CREHLP, which reads a file of help text and writes a help library;
- A command procedure, HLIB, which front-ends the CREHLP program.
- An object library containing, among other things:
- a subprogram, HLP_HELP, which executes an interactive help session; and
- a subprogram, HLP_ERRMES, which translates internal error codes into message
strings.
For VAX/VMS and some Unix platforms two shareable libraries are supplied in addition to the
non-shared library. One (HLP_IMAGE_ADAM.EXE on VMS) is for use with applications
which run under the ADAM software environment; the other (HLP_IMAGE.EXE on
VMS) is for use with stand-alone applications. There are associated link option files
(HLP_LINK.OPT and HLP_LINK_ADAM.OPT for VMS, hlp_link and hlp_link_adam for
Unix).
Other useful items include:
- An example application program, TSTHLP, which allows a help library to be interrogated.
- An example help library,
demo.hlp
(source) and demo.shl
(library format).
- Example implementations of the user-supplied routines which (a) output a line of text,
(b) obtain an interactive response and (c) translate a library name into a filename.
The names of these examples are HLP_OUTSUB, HLP_INSUB and HLP_NAMETR
respectively.
- The HLP_CREH subprogram, which carries out the translation of a file of help text into
the library format. (The CREHLP program is just a front-end for HLP_CREH.)
Also supplied, but of less interest, are:
- A number of internal subprograms, some of which may have uses outside the HLP
system but are not officially part of the published interface to the system, e.g. some of the
character-string handling and I/O routines.
- Command procedures for managing development of the software.
- A utility program, LSTHLP, that lists a help library file for diagnostic purposes, showing
the various index pointers etc. Section 5.3 includes an example of such a listing.