The architecture of the DocBook DTD is modular and parameterized so
that people who read and use DocBook and who interchange DocBook documents
can more easily do the following:
Customize DocBook
in appropriate ways
Maintain variant DTDs over time with as high a
degree of fidelity to the original as possible
Determine exactly what is different between the
original and a variant
Even if you intend to use DocBook in its original form, you need to
understand how all the files go together. Figure 2-1 shows stacked
boxes that represent the interdependencies of all the files that make up the
distributed DocBook V2.4 application, as well as the files that can be supplied
to create a "customization layer" on top of the DTD. Upper modules
depend on lower ones.
Figure 2-2 shows the "call tree" (entity
referencing structure) of the DTD modules, with the order of references shown
left to right. Modules related exclusively to customization are shown with
dashed lines; these need not be supplied if you are not customizing DocBook,
and may not even need to be supplied for most simple customizations.
The contents and function of the files that make up the DocBook application
are as follows. For V2.4.1 of DocBook, the formal public identifiers of the
DocBook modules should use the version string "V2.4.1".
docbook.dcl
This file contains an SGML declaration developed for DocBook, which
depends on certain SGML declaration characteristics being set. You may need
to change this declaration to suit your particular documents and processing
applications; if so, it is a good idea to document what you've changed using
comments.
docbook.dtd
This driver file declares data content notations and declares and references
the two main modules and the ISO standard entity sets. The driver file can
be thought of as "the DocBook DTD." If you reference the driver
file, declare it with the formal public identifier "-//Davenport//DTD
DocBook version//EN".
Note that the driver file declares and references the nineteen ISO entity
sets that appear in an annex to ISO 8879. It is assumed that your environment
has these entity set files available. (The DocBook catalog data file (docbook.cat) has entries for these entity sets.) If you do not
have these files, you can get them from the Davenport archive.
dbhier.mod
This module contains the declarations related to the document hierarchical
structure of DocBook documents: sets, books, reference entries, sections,
articles, and so on. It is stored in a separate module in order to ease the
process of reusing the information pool with a completely different document
hierarchy. If you reference this module directly, declare it with the formal
public identifier "-//Davenport//ELEMENTS DocBook Document Hierarchy version//EN".
dbpool.mod
This module contains the declarations related to the information pool
of DocBook documents, such as paragraphs, command names, and index terms.
Here is where most of the parameter entities for element classes (such as "lists") and mixtures (such as the "component mixture")
are set up, as well as the entities for common attributes. It is stored in
a separate module in order to ease the process of reusing the information
pool with a completely different document hierarchy. If you reference this
module directly, declare it with the formal public identifier "-//Davenport//ELEMENTS
DocBook Information Pool version//EN".
This module has dependencies on calstbl.mod and
also has a few unavoidable dependencies on docbook.mod
(which Figure 2-1 doesn't reflect). See the comments in the dbpool.mod file for more information.
calstbl.mod
This module contains the CALS-based table model that DocBook uses. It
is referenced directly by the information pool module, which parameterizes
it by redefining various entities. If you reference this module directly,
declare it with the formal public identifier "-//Davenport//ELEMENTS
CALS-Based DocBook Table Model version//EN".
dbgenent.mod
This file contains the declarations for any general entities (such as
entities for special characters and boilerplate text) needed in your environment.
The entity for this file is referenced in the DocBook driver file so that
you can take advantage of it without having to do anything special to the
original parts of the DTD, but the file provided as part of the distribution
is empty except for an explanatory SGML comment. Its formal public identifier
is "-//Davenport//ELEMENTS DocBook Additional General Entities//EN".
You can edit this file as necessary to add general entity declarations,
or you can use the file as provided if you need no additional general entities.
Note that you do not need to edit this file if you want to use only the ISO
entity sets already referenced in the driver file. If you do edit the file,
be sure not to overwrite it with the original file contents when you unpack
new versions of DocBook.
These are the suggested names for the files that contain any customizations
(entity redeclarations) that require the referencing of entities declared
earlier in the DTD. You must declare these files as entities in your customization
layer. If you declare these entities as PUBLIC entities,
you will need to add the appropriate entries to the DocBook catalog data file
(docbook.cat) or to another catalog file that you use.
These files exist only if you create them and declare their associated
entities as part of a customization effort, and their contents will be unique
to your customization. Note that many simple customizations do not require these files to be created.
docbook.cat
This is a collection of catalog data in SGML Open TR9401 format, providing
default filename locations as the "storage object identifiers"
corresponding to the formal public identifiers by which DocBook modules should
be identified. This file is provided as a convenience; you may need to incorporate
this data into an existing catalog file or change the entries into a different
format for use by your applications, and may need to change the storage object
identifiers depending on the names, locations, and storage platforms of the
DocBook files in your environement.