NAME

dtdocbook — DocBook to SDL translator

SYNOPSIS

dtdocbook [-c] [-d] [-h] [-m] [-o file] [-r] [-s dir] [-u] [-v] [-x] [file]

DESCRIPTION

The dtdocbook command converts 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 reason for translating DocBook documents to SDL is to make them readable by the the DtHelp viewer.

The CDE documentation authoring environment produces documents that conform to the DocBook DTD Version 2.2.1. The CDE online documentation browser (dtinfo) accepts only documents in the DocBook DTD 2.2.1 format. The CDE online help viewer (DtHelp) accepts only documents in the SDL DTD Version 1.2 format. Both DocBook and SDL are implementations of the SGML standard, ISO 8879:1986. dtdocbook translates document from one format to the other, making them suitable for use with the help viewer.

During translation, several items are precomputed to accelerate run-time display of the resulting SDL document. These items include: the table of contents, the keyword index, cross-reference resolution, and the labeling of ordered lists. By default, dtdocbook also compresses the SDL document.

dtdocbook requires only the filename of the input file. Note that the input file can be either a DocBook document or an SDL document, depending on the operation you want dtdocbook to perform. If the file name ends in the characters .sgm or .sdl, dtdocbook assumes they are the file name extension removes them to create the base name for all intermediate files and for the final output file. If the file name does not end in the characters .sgm or .sdl, dtdocbook uses the file name as given for the base name. If you request either compression or decompression (-c or -d option) of an existing SDL file, the input file name extension will be .sdl. If you specify neither -c nor -d, the input file name extension must be .sgm. The output file name extension will always be .sdl unless you specify the -o option, in which case dtdocbook will use the output filename that you specify.

If you specify the -c option and the file is already compressed, dtdocbook will decompress and recompress the file. This is a convenient way to verify the integrity of a compressed SDL file.

If you specify the -c option and the file is already decompressed, dtdocbook will re-parse the file, repeat all precomputations, and update the existing file. This is a convenient way to verify the integrity of an SDL file. It also allows you to force a recomputation of the table of contents to reflect edits made to the SDL file. You must recompute the table of contents because it consists of byte offsets to the individual help topics in the file.

OPTIONS

The following options are available:

-c: Compresses an existing SDL file. This option assumes an input file name extension of .sdl.
-d: Decompresses an existing SDL file. This option assumes an input file name extension of .sdl.
-h: Outputs a summary of the command and its options to standard output.
-m: Adds additional SDATA and/or character mapping files.
-o file: Uses the specified filename for the output file and does not add any file name extension.
-r: Removes any intermediate files and the output file. If none exist, dtdocbook does not issue an error message.
-s dir: Instructs dtdocbook to find the DocBook SGML declaration and associated files in the specified directory.
-u: Turns off compression for the output file during translation.
-v: Instructs dtdocbook to generate and display parser messages during processing (verbose mode).
-x: Retains intermediate files when finished. This option is used primarily for debugging dtdocbook itself.

OPERANDS

The following operand is supported:

file: The document file to be input to dtdocbook. The file can be in either DocBook or SDL format, depending on which options you specify.

EXIT STATUS

0: The input file was processed successfully.
>Caret1: The operation failed.

ENVIRONMENT VARIABLES

dtdocbook references the LANG variable to determine the language used for the input file's contents. LANG can be overridden by the LANG attribute of the DocBook PART element.

RESOURCES

None.

ACTIONS/MESSAGES

None.

ERRORS/WARNINGS

TO BE SUPPLIED

FILES

file.sgm: The source file
file.idx: An intermediate file, typically removed after use
file.snb: An intermediate file, typically removed after use
file.sdl: the output file

EXAMPLES

: Remove all files that resulted from previously processing the source file myFile.dbk:
: % dtdocbook -r myFile.dbk
: or (without the .dbk extension)
: % dtdocbook -r myFile
: Process the file myFile.dbk:
: % dtdocbook myFile.dbk
: or (without the .dbk extension)
: % dtdocbook myFile
: Process the file myFile.dbk and write the SDL output to otherFile.sdl:
: % dtdocbook-o otherFile.sdl myFile.dbk
: or (without the .dbk extension)
: % dtdocbook-o otherFile.sdl myFile