NAME

dthelptag − compile CDE Help source documents into runtime help volumes

SYNOPSIS

dthelptag [ options ] file [ parser−options ]

DESCRIPTION

The dthelptag command is the CDE Help System compiler for translating HelpTag source markup into the online distribution format suitable for run time display.  See the CDE Help System Authors and Programmers Guide for a description of the HelpTag markup language.  See dthelpview(1) for more information on previewing compiled help volumes. 

The dthelptag 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 dthelptag command 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 −strict option described below is used.  The .sdl extension is assumed when the −compress or −decompress options described later in this document are 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. 

−strict
The −strict option causes dthelptag to accept a subset of the HelpTag language that is strictly compliant to canonical SGML.  (See the CDE Help System Authors and Programmers 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 run-time 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/dt/bin. 

• The environment variable DTTAGOPT

• The file helptag.opt in the current directory. 

• The file Rfile.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 Authors and Programmers 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 via 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. 

OPERANDS

????  The OPERANDS section describes the utility operands, and how they affect the actions of the utility. 

  Default Behaviour: When this section is listed as “None”, it means that the implementation need not support any operands.P

STDIN

????  The STDIN section describes the standard input of the utility.  This section is frequently merely a reference to the following section, as many utilities treat standard input and input files in the same manner.  Unless otherwise stated, all restrictions described in INPUT FILES apply to this section as well. 

  Default Behaviour: When this section is listed as “Not used,” it means that the standard input will not be read when the utility is used as described by this document.

INPUT FILES

????  The INPUT FILES section describes the files, other than the standard input, used as input by the utility.  It includes files named as operands and option-arguments as well as other files that are referred to, such as startup and initialisation files, databases, etc.  Commonly-used files are generally described in one place and cross-referenced by other utilities. 

  Record formats are described in a notation similar to that used by the C-language function, printf(). See X/Open CAE Specification, Commands and Utilities, Issue 4 for a description of this notation. 

  Default Behaviour: When this section is listed as “None”, it means that no input files are required to be supplied when the utility is used as described by this document.

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 Authors and Programmers Guide. 

  DTTAGOPT may be used to set parser options. 

International Code Set Support

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

 

FILES

???? need some kind of intro sentence here.  see examples

file.htg default input file

file.ctg default input file when the −strict option has been specified

file.sdl runtime help volume

file.err run log and error listing

file.st status file and log

helplang.ent character set information and localizable replacement text

helptag.opt option file

RESOURCES

???? X/Open required heading.  This section lists the X Window System resources that affect the operation of the utility.

ASYNCHRONOUS EVENTS"

????  The ASYNCHRONOUS EVENTS section lists how the utility reacts to such events as signals and what signals are caught. 

  Default Behaviour: When this section is listed as “Default”, or it refers to “the standard action for all other signals,” it means that the action taken as a result of the signal is one of the following:

 
The result of the utility’s execution
is as if default actions had been taken.

A utility is permitted to catch a signal, perform some additional processing (such as deleting temporary files), restore the default signal action (or action inherited from the parent process) and resignal itself. 

STDOUT

????  The STDOUT section describes the standard output of the utility. 

Default Behaviour: When this section is listed as “Not used”, it means that the standard output will not be written when the utility is used as described by this document.

STDERR

????  The STDERR section describes the standard error output of the utility.  Only those messages that are purposely sent by the utility are described. 

Default Behaviour: When this section is listed as “Used only for diagnostic messages,” it means that, unless otherwise stated, the diagnostic messages are sent to the standard error only when the exit status is non-zero and the utility is used as described by this document. 

When this section is listed as “Not used”, it means that the standard error will not be used when the utility is used as described in this document. 

OUTPUT FILES"

????  The OUTPUT FILES section describes the files created or modified by the utility. 

Record formats are described in a notation similar to that used by the C-language function, printf().

Default Behaviour: When this section is listed as “None”, it means that no files are created or modified as a consequence of direct action on the part of the utility when the utility is used as described by this document.  However, the utility may create or modify system files, such as log files, that are outside the utility’s normal execution environment.

EXTENDED DESCRIPTION

The dthelptag command 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 EXIT STATUS section describes the values the utility will return to the calling program, or shell, and the conditions that cause these values to be returned.  Usually, utilities return zero for successful completion and values greater than zero for various error conditions.  If specific numeric values are listed in this section, the system will use those values for the errors described.  In some cases, status values are listed more loosely, such as “>0”.  A portable application cannot rely on any specific value in the range shown and must be prepared to receive any value in the range.

CONSEQUENCES OF ERRORS

????  The CONSEQUENCES OF ERRORS section describes the effects on the environment, file systems, process state, and so on, when error conditions occur.  It does not describe error messages produced or exit status values used. 

When a utility encounters an error condition several actions are possible, depending on the severity of the error and the state of the utility.  Included in the possible actions of various utilities are: deletion of temporary or intermediate work files; deletion of incomplete files; validity checking of the file system or directory. 

Default Behaviour: When this section is listed as “Default”, it means that any changes to the environment are unspecified.

APPLICATION USAGE

????  The APPLICATION USAGE section gives advice to the application programmer or user about the way the utility should be used.

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 their are syntax errors

dthelptag myFile.htg
Process the file myFile.htg

SEE ALSO

dthelpview(1), CDE Help System Authors and Programmers Guide. 
 
 
 
 
 

  —  12 May 1994