Chapter 1. Building Variant DTDs Based on DocBook

DocBook is "cannibalized" as often as it is used in its original form. It has a modular structure and uses parameter entities to ease the process of using the desired parts of DocBook and modifying them as necessary. This book explains how to create variants of DocBook using its modules and parameter entities.

There are two main methods for building DocBook variants: You can start with both of the standard main modules and customize them, or you can reuse one of the modules in building a new DTD. You can also use the two methods in combination, for example, by using just one module and also customizing it. Regardless of the techniques you use, building a variant DTD requires careful planning.

You can make two kinds of changes to DocBook "for free"; they don't fundamentally alter its markup model, and you can make these changes in the main DocBook DTD file, in your own driver file, or in an internal subset without considering your version a variant:

• Declaring additional data content notations

  DocBook declares many common non-SGML notations. Your environment may need additional notations.

• Declaring and referencing general entities of any kind (even if the entity declarations are stored in an external parameter entity)

  DocBook declares and references all 19 of the ISO 8879 annex entity sets. You may need additional character entities and/or may need to declare general entities that can be used as boilerplate text. If you remove any declarations of ISO entities, your DTD will be considered a variant of DocBook because valid DocBook documents that use any of the missing entities would be invalid under your DTD.

All other changes, no matter how small, should result in the use of a formal public identifier (if you use one) that is different from that of the original module or driver file. You should change both the owner identifier and the description. The original DocBook formal public identifiers use the following syntax (note that the owner identifier has changed from "HaL and O'Reilly" to "Davenport"):

-//Davenport//{DTD|ELEMENTS} DocBook description version//EN

Your own formal public identifiers should use the following syntax in order to record their DocBook derivation:

-//your-owner-ID//{DTD|ELEMENTS} DocBook Vn.n[.n]-Based [Subset|Extension|Variant] your-descrip-and-version//lang

For example:

"-//DocTools//DTD DocBook V2.3-Based Subset V1.1//EN"

If your DTD is a proper subset, you can advertise this status by using the "Subset" keyword in the description. If your DTD contains any markup model extensions, you can advertise this status by using the "Extension" keyword. If you'd rather not characterize your variant specifically as a subset or an extension, you can leave out this field entirely, or, if you prefer, use the "Variant" keyword.

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

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
]>

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