dthelptag(1) UNIX System V (1 August 1995) dthelptag(1)
NAME
dthelptag - compile CDE Help source documents into runtime
Help volumes
SYNOPSIS
dthelptag [ options ] file [ parser-options ]
DESCRIPTION
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
Page 1 (printed 9/3/04)
dthelptag(1) UNIX System V (1 August 1995) dthelptag(1)
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.
Page 2 (printed 9/3/04)
dthelptag(1) UNIX System V (1 August 1995) dthelptag(1)
The order of precedence of the option settings is:
o The file helptag.opt in the dthelptag
installation directory. This directory
defaults to /usr/dt/bin.
o The environment variable DTTAGOPT.
o The file helptag.opt in the current
directory.
o The file file.opt in the current
directory.
o 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
Page 3 (printed 9/3/04)
dthelptag(1) UNIX System V (1 August 1995) dthelptag(1)
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.
Page 4 (printed 9/3/04)
dthelptag(1) UNIX System V (1 August 1995) dthelptag(1)
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
Page 5 (printed 9/3/04)
dthelptag(1) UNIX System V (1 August 1995) dthelptag(1)
Guide.
Page 6 (printed 9/3/04)
