DocBook Output |
 |
DocBook takes the file volume.sgm
as its input and outputs several files:
Most importantly, the final output
file, a run-time help volume, named volume.sdl.
If any errors occurred during processing, they are
reported in an error file named volume.log,
typically removed after use.
The volume.sdl
file is not created until the source file is without errors.
The volume.sdl,
file, plus your graphics files, are read by the Help System to display
help topics.
The run-time help file has the same base name as your volume.sgm
file. For example, if your source file is named Librarian.sgm,
then the help volume name is Librarian.sdl.
The dtdocbook utility
accepts a single file as an argument. If the file name ends in the
characters ".sgm",
those characters are assumed to be the file name extension and are
removed to create the file base names for all intermediate files
and for the final output file.
When the dtdocbook -c
or the dtdocbook -d option
is specified to request compression or decompression of an existing
SDL file, the input file name will end in the characters ".sdl".
Again, those characters are assumed to be the file name extension
and are removed to create the file base names for all intermediate
files and for the final output file.
If the -c option is specified
and the file is already compressed, the file will be decompressed
and recompressed. This action is useful as a means to verify the
integrity of a compressed SDL file.
If the -d is specified
and the file is already decompressed, the file will be re-parsed,
all precomputations will be performed, and the file will be re-written.
This action is useful as a means to verify the integrity of an SDL
file. It is also useful for forcing a recomputation of the table
of contents, including byte offsets to individual help topics, when
such recomputation is made necessary, for example, by editing the
SDL file directly.
The final output file name extension will always be ".sdl",
unless the dtdocbook -o option
is specified, in which case the filename
argument to dtdocbook -o will
be used as given as the output file name.
|
| |
|
 | CAUTION: Never rename a run-time help file or graphics file
after running dtdocbook. The
information stored in the volume.sdl
file depends on the original names. If you rename your volume.sgm
file or any of your graphic files, be sure to rerun dtdocbook. |
|
| |
|
To Review and Correct Parser Errors |
|
The primary source of error messages will be the SGML parser.
Most of them will be SGML syntax error messages, and a few will
be of the "file not found" variety.
The two passes of the translation process that takes the source
file from SGML to SDL will also generate syntax error messages and
"file not found" messages, but to a lesser degree. The second of
the two passes will issue error messages rarely, since all the syntax
and context will have been checked by then.
After running dtdocbook,
look at the contents of the volume.log
file (where volume
is the base name of your volume.sgm
file).
It is quite possible for a single, simple error to produce
several error messages, because the error may cause the parser to
lose track of the intended context, making it impossible to interpret
subsequent markup properly.
Most processing errors result from these common mistakes:
Using an incorrect entity name
Referring to an invalid element ID
Omitting an end tag for an element is a common mistake. Virtually
all DocBook elements require end tags. Check your markup
when you have nested one structurally complex element within another,
such as a figure within a list.
Errors can also be introduced by using an incorrect entity
name. In most instances, it is simply a misspelled word. In other
cases, an entity name may have been changed, but cross-references
to the original name were overlooked. When you change an entity
name, remember to search your source file (or files) for all instances
of the entity name.
Errors can also be introduced by changing the ID assigned
to an element, since this affects any cross-reference or link to
that topic. When you change an ID, remember to search your source
file (or files) for all instances of that ID.
Printable version
