helptag(1)

NAME

helptag − Driver program to process HP Help System documents

SYNOPSIS

helptag [options] file [parser−options]

DESCRIPTION

helptag is the driver program for the three phases of preparing an HP Help System document for use in presenting online help. These three phases are parsing, creating a volume and keyword index and compressing the resulting topic files.

The helptag command accepts a single file name as an argument. If the file name contains a period ("."), any characters after the last period are considered to be the extension. The helptag command will remove all characters after the last period and use the resulting name as the base name for all intermediate files and for the final output files. If the file argument has no periods, helptag uses the argument as the base name for intermediate and output files and assumes and extension of .htg for the input file.

Several options directing the helptag process may precede the file name. Several arguments directing the parsing phase of the helptag process may follow the file name.

The output files are:

• file##.ht − where ## is replaced by 00, 01, etc., are the text of the help topics.

• file.hv − is an index into the .ht files for finding the beginning of topics.

• file.hvk − is a list of keywords and their associated topics.

• file.err − contains a log of the parsing activity along with any errors generated during the parse.

• file.xrh − is used in generating cross references. This file is not used by the runtime HP Help System engine. It is used between passes of the parser phase of the helptag process. Retaining this file between invocations of helptag often eliminates the need for a second pass of the parser.

Options

The following options are recognized by helptag and must be placed before the specified file.

−clean
The −clean option removes all helptag generated files corresponding to the file specified.

−files
This option emits a list of files entered as entity declarations in the file argument.

−help
The −help option prints a list of helptag options and their meanings to the standard output.

−shortnames
The −shortnames option causes all generated file names to be less than eight characters before the extension. This length limitation is achieved by truncating the input file argument to six characters so that adding, for example, "00.ht" produces an eight character file name and a two character extension.

−verbose
Setting the −verbose option will cause helptag to be much more descriptive about the parser phase.

Parser Options

Any parser options follow the file argument on the command line and take the form option=value for those options taking a parameter and simply option for those options not taking a parameter. Parser options may also be set in the environment variable TAGOPT, in a helptag.opt file or in a file named file.opt in the current directory. The helptag.opt file may reside in the current directory or in the directory in which helptag is placed.

The order of precedence of the option settings is:

• The file helptag.opt in the helptag installation directory. This directory defaults to /usr/vhelp/bin.

• The environment variable TAGOPT

• The file helptag.opt in the current directory.

• The file file.opt in the current directory.

• The command line.

Parser options set later in the list will override options set earlier.

The parser options supported by helptag are:

onerror=go
Cause errors to be non-fatal. That is, parsing will continue and later phases of the helptag process will be run even if syntax errors were encountered in the parse.

onerror=stop
This is the default setting of the onerror= option. It causes the helptag process to stop upon completion of the parser phase if syntax errors were encountered during the parse.

charset=name
The default character set used by the HP Help System is ISO8859-1. A different character set may be specified, e.g., name, using the charset= option. The character set may also be set in the helplang.ent file described in the HP Help System Developers’ Guide.

search=path
Adds path to the list of directories searched for file and image entities.

clearsearch
Clears the list of directories searched for file and image entities.

memo
The memo option causes authors’ memos to be included in the output document.

nomemo
Is the inverse of the memo option. Both memo and nomemo may be specified but the last one mentioned will override any previous setting.

shortfiles
Neither the shortfiles parser-option nor any of its synonyms should be used. Rather, the −shortfiles option should be given as an option to helptag. The helptag driver needs to know whether the user has requested short file names since helptag must know the names of the intermediate files.

shortfile
is a synonym for shortfiles.

short is a synonym for shortfiles.

longfiles
Neither this option nor any of its synonyms should be used for the same reason that the shortfiles option should not be used.

Long, untruncated, file names are the default.

longfile
is a synonym for longfiles.

long is a synonym for longfiles.

EXTERNAL INFLUENCES

Environment Variables

LANG determines the language in which the input file is interpreted. The LANG environment variable can be overridden in the helplang.ent file described in the HP Help System Developers’ Guide.

TAGOPT may be used to set parser options as described earlier.

International Code Set Support

Single- and multi-byte character code sets are supported.

AUTHOR

helptag was developed by HP.

FILES

file.htg input file

file##.ht help topic text

file.hv index into .ht files

file.hvk keyword index file

file.err run log and error listing

file.xrh cross-reference file

\.file.st status file and log

file.hmi intermediate

file.idt intermediate

file.tpc intermediate

file.idx intermediate

Museum