Help files exist in two forms: (i) the source form, which you create using a text editor, and (ii) the library form, which is read by the application program when it calls the HLP_HELP subprogram. The source form is read sequentially (a two-pass operation) by the HLP_CREH routine to write the randomly-addressable indexed library file which can be interrogated by means of the HLP_HELP routine.
No facilities exist for inserting a single topic into an existing help library.
Each source file contains one hierarchy of help text. Embedded within the file may be pointers to other help libraries, though it is perfectly possible and normal for all the help text for a given application to be stored in a single source file. Whether or not multiple files are used, the result always appears to the user as a single “tree” of help information.
Each topic within a help source file consists of lines of plain text, preceded by a special line of text containing the level number and the keyword. The level number, a single decimal digit in the first character position, can be from 0 to 9, and shows the hierarchical level of the help text which follows. The keyword is a unique name for the topic, which will be specified by the user to retrieve the text for that topic or one of its subtopics.
The source file comprises four sorts of record; COMMENT, KEYWORD, TEXT and END records. All are ordinary formatted alphanumeric records, as produced by a text editor. Up to 132 characters are accepted, though a maximum of 80 characters is recommended.
COMMENT records have “!” as their first character, and are ignored.
The format of a KEYWORD record is either:
n keyword
@library n keyword
TEXT records are just plain text, and apply to the preceding keyword. Any that precede the first keyword are ignored. Blank lines before and after each group of TEXT records are ignored. Note that the rules for recognizing other sorts of record mean that text records cannot begin with a decimal digit, “@” or “END” etc. It is also recommended that the character “/” is avoided; “/” is reserved for future use by Starlink and also could cause incompatibilities with VMS Help.
The optional END record consists of the three characters “END”, in any mixture of uppercase and lowercase.
The rules for level numbers are as follows:
The rules for keywords are as follows:
Here is an example help source file:
The file HLP_DIR:DEMO.HLP
on VAX/VMS or /star/bin/examples/hlp/demo.shl
on Unix platforms
contains a more elaborate example.
To translate one or more files of help source into a library which can be read by an application
program, execute the hlib
command script:
VAX/VMS | UNIX |
$ @HLP_DIR:HLIB source library | % hlib source_1 source_2 … |
where source.. is a file of help text to be input and (on VAX/VMS platforms only) library is the library file to be written.
On VAX/VMS, the default file extensions are .HLP
for the source file and .SHL
for the library
file. A wildcard in the name of the source file will cause each such file to be processed
individually. If the first argument is omitted it defaults to “*”. If the second argument
is omitted then library = source with extension changed to .SHL
. A wildcarded name in
the second argument defaults to the name field of the first filename. Typical uses are as
follows.
To translate source EXAMPLE.HLP
into library file EXAMPLE.SHL
:
To translate all *.HLP
source files in the current directory into *.SHL
library files:
To translate all *.HLP
source files in the current directory into *.SHL
library files in directory
[.SUB]
:
On Unix platforms, less flexibility is provided. The library file always has file extension .shl
. A series
of source file names may be specified, perhaps using a wildcard, and each one will be translated into
an appropriately-named .shl
file. Typical uses are as follows.
To translate source example.hlp
into library file example.shl
:
To translate all *.hlp
source files in the current directory into *.shl
library files:
Programmers wishing to integrate help library creation into their application packages may use the HLP_CREH subprogram:
where the arguments are as follows:
Given: | |||
NAMETR | EXTERNAL | subroutine to translate library names into filenames | |
LUIN | INTEGER | I/O unit number for reading help source | |
SOURCE | CHARACTER*(*) | filename for help source, or spaces | |
LUOUT | INTEGER | I/O unit number for writing help library | |
LIB | CHARACTER*(*) | filename for help library, or spaces | |
LUERR | INTEGER | I/O unit number for error messages | |
EOS | CHARACTER*1 | character to use as end-of-string | |
Returned: | |||
JSTAT | INTEGER | status: OK, =fail | |
The conventional EOS value in all present implementations is CHAR(0)
.