Table of Contents
dthelptag -- compile CDE Help source documents into runtime Help volumes
dthelptag [options] [file] [parser-options]
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.
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.
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/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.
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.
Single- and multi-byte character code sets
are supported.
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.
Following are the input files used by the dthelptag parser:
- file.sdl
- Runtime help volume
- file.err
- Run log and error listing
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.
The following exit values are returned:
- 0
- Successful completion.
- 1
- An error was detected in the source file.
- 2
- An invocation error was detected.
Default.
- 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.
dthelpview(1)
,
CDE Help System Author’s and Programmer’s Guide.
Table of Contents