Guide to the DocBook DTD
PrevNext

Chapter 9. Building Variant DTDs Based on DocBook

Table of Contents
Setting Up DocBook for Customization
Reusing Individual DocBook Modules
Customization Specifics
Sample Customization

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:

Even though you can make these changes at will, you should still document them in your answers to the interchange checklist (provided in the Overview) when you share your files.

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.


PrevHomeNext
AcknowledgmentsUpSetting Up DocBook for Customization