Guide to the DocBook DTD
PrevChapter 9. Building Variant DTDs Based on DocBookNext

Setting Up DocBook for Customization

To customize DocBook by starting from the standard version:

  1. Decide whether you will store the customizations in a .dtd driver file that will function as “the DTD” for your purposes, or in an internal subset (between the square brackets in a DOCTYPE declaration directly inside a document). Most likely, you will want to create a new driver file so that you can easily use your variant DTD with many documents. (Note that SGML-aware applications that compile DTDs usually don't handle markup customizations in internal subsets.) Your set of customizations can be thought of as a “customization layer.”

  2. From within your customization layer, reference as parameter entities either the original DocBook driver file or both of the main modules, depending on your customization needs. The original driver file has been set up to be usable for nearly all kinds of customization, but you may need or want to construct your own driver file from scratch. Keep in mind that creating your own driver file without including the notations and ISO entity sets found in the original driver file will result in a DocBook subset in this respect.

  3. Add your customizations around the references to the original DocBook material.

The main method for customizing DocBook elements and attributes is the overriding of existing parameter entities, that is, the declaration of a parameter entity with the same name as one that is declared later in the linear flow of the DTD. The redeclarations go in your driver file or internal subset in the appropriate locations to override the original values. With certain redeclarations in place, you might also declare new element types and attribute lists and supply replacement declarations for existing element types and attribute lists.

Following are templates for DocBook customizations, starting with the most common and desirable. Example 9-1shows a customization template using a reference to the original driver file from a higher-level driver file (which might be named myvariant.dtd).

Example 9-1. Template for Customizing Around the Original Driver File

overrides of entity declarations go here
<!ENTITY % orig-docbook "-//Davenport//DTD DocBook V2.3//EN">
%orig-docbook;
element/attribute declarations go here

Example 9-2 shows a customization template using direct references to the original modules from a higher-level driver file. You will need to supply your own notation declarations and references to ISO entity sets in this scenario; leaving out any that DocBook itself supplies will create a subset in this respect.

Example 9-2. Template for Customizing Around the Individual Modules

overrides of most entity declarations can go here
<!ENTITY % orig-pool
"-//Davenport//ELEMENTS DocBook Information Pool V2.3//EN">
%orig-pool;
some overrides of document hierarchy entities may need to go here
<!ENTITY % orig-hier
"-//Davenport//ELEMENTS DocBook Document Hierarchy V2.3//EN">
%orig-hier;
element/attribute declarations go here
]>

Example 9-3 shows a customization template using a reference to the original driver file from an internal subset. Note that parsers read the declarations in the subset before the declarations in the remote portion (the original DTD), so that the local declarations take precedence over whatever is in the original file. Note also that it is generally considered bad practice (even if supported in your software) to change the markup model of a DTD “on the fly” like this. If you must make any customizations that rely on declarations positioned after the original DTD file (such as new element declarations that contain references to entities defined earlier), you can't use this method.

Example 9-3. Template for Customizing in an Internal DOCTYPE Subset

<!DOCTYPE Book PUBLIC "-//Davenport//DTD DocBook V2.3//EN" [
overrides of entity declarations go here
]>

PrevHomeNext
Building Variant DTDs Based on DocBookUpReusing Individual DocBook Modules