dthelptag(user cmd)

NAME
dthelptag — compile CDE Help source documents into runtime Help volumes

SYNOPSIS

dthelptag [options] [file] [parser-options]

DESCRIPTION

    Note:

    This utility has been superseded by the dtdocbook utility, which converts source documents that conform to the DocBook 2.2.1 DTD (Document Type Definition) subelement PART to documents that conform to the SDL 1.2 DTD. The converted DocBook documents are readable by the DtHelp viewer.

The dthelptag utility is the CDE Help System compiler for translating HelpTag source markup into the online distribution format suitable for runtime display. See the CDE Help System Author's and Programmer's Guide for a description of the HelpTag markup language. See dthelpview(1) for more information on previewing compiled Help volumes.

The dthelptag utility 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 dthelptag utility removes all characters after the last period and uses the resulting name as the base name for all intermediate files and for the final output files.

If the file argument has no periods, dthelptag uses the argument as the base name for intermediate and output files and assumes an extension of .htg, .ctg or .sdl for the input file. The .ctg extension is assumed when the -formal option described below is used. The .sdl extension is assumed when the -compress or -decompress option (described later in this document) is used.

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

The output file is: file.sdl - the compiled help volume file.

OPTIONS

The following options are available:

-verbose
    The -verbose option will cause dthelptag to generate and display parser messages during processing.

-formal
    The -formal option causes dthelptag to accept a subset of the HelpTag language that is strictly compliant to canonical SGML. (See the CDE Help System Author's and Programmer's Guide.) When this option is given, the default extension of the input file becomes .ctg.

-nooptimize
    The -nooptimize option eliminates certain optimizations that normally take place during translation of HelpTag markup to the runtime format. Using this option speeds the translation process.

-clean
    The -clean option causes dthelptag to simply remove any intermediate files from the current directory. No translation takes place.

-debug
    The -debug option causes dthelptag to leave all intermediate files in the current directory. The -debug option also blocks the compression step of dthelptag, leaving the resulting .sdl output file in a human-readable form.

-files
    The -files option causes a list of files referenced in the translation process to be emitted to the standard output. No translation takes place.

-help
    The -help option causes dthelptag to emit a synopsis of the dthelptag command line and a list of options to the standard output.

-decompress
    The -decompress option causes dthelptag to decompress a previously created .sdl file. When this option is specified, the default input extension is .sdl.

-compress
    The -compress option causes dthelptag to compress a .sdl file that either was created by translating a .htg or .ctg file using the -debug option or was previously decompressed using the -decompress option. When this option is specified, the default input extension is .sdl.

  Parser Options

Any parser options follow the file argument on the command line and take the form option=value for those options taking an argument and simply option for those options not taking an argument. Parser options may also be set in the environment variable DTTAGOPT, 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 dthelptag is placed.

The order of precedence of the option settings is:

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

•   The environment variable DTTAGOPT.

•   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 override options set earlier.

The parser options supported by dthelptag are:

onerror=go
    Cause errors to be non-fatal. That is, parsing continues and later phases of the dthelptag process are run even if syntax errors were encountered.

onerror=stop
    This is the default setting of the onerror= option. It causes the dthelptag 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 help system is ISO8859-1. A different character set may be specified, for example, name, using the charset= option. The character set may also be set in the helplang.ent file described in the CDE Help System Author's and Programmer's Guide.

search=path
    Specifies one or more directory path(s) to be searched when executing dthelptag. Both dthelptag input files and/or additional graphics or entity declaration files referenced within the HelpTag markup can be made accessible by setting this option. The search= option may be specified more that once and the list of directories to search is accumulated.

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

memo
    The memo option causes authors' comments to be included in the output.

nomemo
    Specifies the inverse of the memo option. Both memo and nomemo may be specified, but the last entry 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 dthelptag. The dthelptag driver needs to know whether the user has requested short file names since dthelptag must know the names of the intermediate files.

shortfile
    This is a synonym for shortfiles.

short
    This is a synonym for shortfiles.

longfiles
    This option and any of its synonyms should not be used for the same reason that the shortfiles option should not be used.

longfiles
    Long, untruncated file names are the default.

longfile
    This is a synonym for longfiles.

long
    This is a synonym for longfiles.

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 CDE Help System Author's and Programmer's Guide.

DTTAGOPT may be used to set parser options.

  International Code Set Support

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

INPUT FILES

Following are the input files used by the dthelptag parser:

file.htg
    Default input file.

file.ctg
    Default input file when the -formal option has been specified.

file.st
    Status file and log.

helplang.ent
    Character set information and localizable replacement text.

helptag.opt
    Option file.

OUTPUT FILES

Following are the input files used by the dthelptag parser:

file.sdl
    Runtime help volume

file.err
    Run log and error listing

EXTENDED DESCRIPTION

The dthelptag utility is a driver program that executes two phases of the compilation process. The first phase translates the source markup into the distribution format. The second phase enhances the distribution file by precomputing information such as a list of identifiers in the file and their locations. These precomputations, along with several optimizations, enable rapid runtime display of the file. The second phase of the translation process also compresses the distribution file to reduce file system space required to store the file.

EXIT STATUS

The following exit values are returned:

0   Successful completion.

1   An error was detected in the source file.

2   An invocation error was detected.

CONSEQUENCES OF ERRORS

Default.

EXAMPLES

dthelptag -clean myFile.htg
    Remove all files previously generated by processing a source file of myFile.htg.

dthelptag myFile.htg onerror=go
    Process the file myFile.htg, not stopping even if there are syntax errors.

dthelptag myFile.htg
    Process the file myFile.htg.

SEE ALSO

dthelpview(1), CDE Help System Author's and Programmer's Guide.