next up previous
Next: Creating the Library File
Up: CREATING A HELP LIBRARY
Previous: CREATING A HELP LIBRARY

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:

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:

  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:

   !
   !  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.



next up previous
Next: Creating the Library File
Up: CREATING A HELP LIBRARY
Previous: CREATING A HELP LIBRARY



HLP --- Interactive Help System
Starlink User Note 124
P. T. Wallace
13th June 1995
E-mail:ptw@star.rl.ac.uk