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:

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:

$ @HLP_DIR:HLIB EXAMPLE

To translate all *.HLP source files in the current directory into *.SHL library files:

$ @HLP_DIR:HLIB

To translate all *.HLP source files in the current directory into *.SHL library files in directory [.SUB]:

$ @HLP_DIR:HLIB * [.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:

% hlib example.hlp

To translate all *.hlp source files in the current directory into *.shl library files:

% hlib *.hlp

Programmers wishing to integrate help library creation into their application packages may use the HLP_CREH subprogram:

CALL HLP_CREH (NAMETR, LUIN, SOURCE, LUOUT, LIB, LUERR, EOS, JSTAT)

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: $0=$OK, $-9$=fail

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