3 CREATING A HELP LIBRARY

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.

3.1 The Source File

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:

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:

(1)

Higher-level topics have smaller level numbers. Thus a topic at level $n$ embraces any material at levels $n+1$, $n+2$, etc..

(2)

The order in which the keyword records appear in the source file defines the hierarchy. A level number one larger than the previous one means a subtopic; a level number less than or equal to the previous one means that the current branch has finished and we have moved to the next branch of the given level.

(3)

A level number can be less than the previous one, the same, or one more. Increases greater than one are not allowed.

(4)

The first keyword record in the source file defines the highest level topic for that file. Each file must have exactly one such record: no further keyword records at that level (or higher) are permitted.

(5)

Though it is conventional to start each source file with a zero-level topic, it is permissible to start at any level; apart from limiting the number of levels which can appear in that library, it makes no difference.

(6)

Where one help library refers to another it is not necessary for the levels to match. It is possible, for example, for the same library to appear twice in a tree at two different levels.

(7)

Irrespective of the range of levels in the individual libraries, the complete help tree must not go beyond level 9.

The rules for keywords are as follows:

(1)

The maximum length of a keyword is 64 characters. In practice, keywords longer than about 20 characters are inconvenient to use and are discouraged.

(2)

Keywords remain in the format in which they were entered, with use of uppercase and lowercase preserved. Character case is, however, ignored when matching.

(3)

The wildcard, escape and abbreviation features available during text retrieval mean that there is considerable freedom in choosing keywords. However, it is strongly recommended that only alphabetic characters (uppercase and lowercase), decimal digits, dollar sign, underscore and hyphen be used. Prohibited or deprecated are asterisk, percent sign, ellipsis (three or more consecutive periods), at sign, slashes (forward or back), parentheses (left or right), and quote marks (single or double).

(4)

Accessing topics whose names are valid abbreviations of any that precede them can be awkward: it would be unwise to have a topic PLOT following a topic PLOTXY for example. Topics arranged in alphabetical order automatically comply with this recommendation.

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.

3.2 Creating the Library File

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:

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:

The conventional EOS value in all present implementations is CHAR(0).