next up previous
Next: The INCLUDE files
Up: SOFTWARE SUPPORT GUIDE
Previous: Portability Issues

Library Format

A help library file (as opposed to a help source file) consists of three regions:

  1. The header region, a single record, gives the size of the file, in characters, as a decimal number in I12.12 format.
  2. The index region, terminated by an empty record.
  3. The data region, lines of help text interspersed with keyword records. The text region, and the whole file, are terminated by an empty record.

For a more detailed picture, it is best to look at an actual file, and one is listed below. It is the example help source file given in Section 3.1, translated into a help library with the HLIB procedure, and listed using the LSTHLP utility. The first column of the listing is the character address. All records are terminated with the chosen ``EOS'' character, conventionally the null CHAR(0).

The file begins with the header record, in this case giving the total length of the file as 1937 characters. The records at character 13, 67, ... 348 are the index region of the file, terminated by the empty record at character 386. The records at character 387, 411, ... 1912 are the data region of the file, terminated by the empty record at character 1936.

The various fields of each index record are separated by spaces. Each record begins with three pointers in I9.9 format. The first pointer indicates the position of the item in the data region of the file. The second pointer indicates the position of the next index entry down the branch of the help tree. The third pointer indicates the position of the next entry of the same level. In this simple library, which does not contain references to other libraries, the three pointers are followed by the level number and the keyword. Where the library refers to another, the name of the referred-to library, prefixed with an "@", is included prior to the level number; an example of this is given later.

    0   000000001937
   13   000000387 000000067 000000386 0 PROGRAMMING_LANGUAGES
   67   000000686 000000110 000000110 1 Assemblers
  110   000000812 000000197 000000152 1 Compilers
  152   000001473 000000310 000000386 1 Interpreters
  197   000000955 000000237 000000237 2 Fortran
  237   000001223 000000276 000000276 2 PASCAL
  276   000001324 000000152 000000152 2 C
  310   000001572 000000348 000000348 2 BASIC
  348   000001709 000000386 000000386 2 Forth
  386   
  387   0 PROGRAMMING_LANGUAGES
  411   Programming via front-panel switches, or by plugboards, is no longer
  480   in fashion.  Even macho programmers now resort to describing what the
  550   computer is to do in terms of text which is assembled or compiled into
  621   machine code, or which is interpreted and executed line by line.
  686   1 Assemblers
  699   One line of assembly language used to turn into one machine instruction,
  772   but these days you're never quite sure.
  812   1 Compilers
  824   A compiler turns high-level code which is supposed to be machine-
  890   independent but isn't into machine code which definitely isn't .
  955   2 Fortran
  965   An archaic language, a fossil remnant of 1950s IBM machines.  Used
 1032   to excellent effect by hordes of programmers round the world.  Produces
 1104   more efficient code than anything except assembler.  Its imminent
 1170   demise has been announced annually since about 1963.
 1223   2 PASCAL
 1232   Used for teaching structured programming.  Comes in various toxic
 1298   vendor-specific flavours.
 1324   2 C
 1328   The most successful computer virus to date.  Great to write in.
 1392   Produces really impressive gibberish code.  Goes wrong in all sorts
 1460   of fun ways.
 1473   1 Interpreters
 1488   There's nothing quite like changing a line of code and instantly
 1553   seeing the result.
 1572   2 BASIC
 1580   Revolting old-fashioned language which lots of people understand
 1645   and use, and which runs surprisingly fast on lots of computers.
 1709   2 Forth
 1717   Forth combines fast execution with compact code and rapid program
 1783   development turnaround.  Other benefits are really sensational
 1846   gibberish code which no-one can ever understand, and a propensity
 1912   to spectacular crashes.
 1936

Where a help library includes references to other libraries, index entries like the following one appear:

   91   000002791 000000149 000000149 @cmnds 1 Commands

The corresponding keyword entry in the data region of the file is normal in appearance except that there are no text records.



next up previous
Next: The INCLUDE files
Up: SOFTWARE SUPPORT GUIDE
Previous: Portability Issues



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