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
where n is the level number, or:
@library n keyword
where library is the name of another (different) help library and follows the "@" with no intervening spaces. The @library, n and keyword fields are separated by one or more spaces. Spaces before the n or "@" are not allowed. More details on level numbers and keywords are given later.
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:
! ! Example help library ! 0 PROGRAMMING_LANGUAGES Programming via front-panel switches, or by plugboards, is no longer in fashion. Even macho programmers now resort to describing what the computer is to do in terms of text which is assembled or compiled into machine code, or which is interpreted and executed line by line. 1 Assemblers One line of assembly language used to turn into one machine instruction, but these days you're never quite sure. 1 Compilers A compiler turns high-level code which is supposed to be machine- independent but isn't into machine code which definitely isn't . 2 Fortran An archaic language, a fossil remnant of 1950s IBM machines. Used to excellent effect by hordes of programmers round the world. Produces more efficient code than anything except assembler. Its imminent demise has been announced annually since about 1963. 2 PASCAL Used for teaching structured programming. Comes in various toxic vendor-specific flavours. 2 C The most successful computer virus to date. Great to write in. Produces really impressive gibberish code. Goes wrong in all sorts of fun ways. 1 Interpreters There's nothing quite like changing a line of code and instantly seeing the result. 2 BASIC Revolting old-fashioned language which lots of people understand and use, and which runs surprisingly fast on lots of computers. 2 Forth Forth combines fast execution with compact code and rapid program development turnaround. Other benefits are really sensational gibberish code which no-one can ever understand, and a propensity to spectacular crashes. END
The file HLP_DIR:DEMO.HLP on VAX/VMS or /star/bin/examples/hlp/demo.shl on Unix platforms contains a more elaborate example.