Guide to the DocBook DTD | ||
---|---|---|
Prev | Next |
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.
Build variants only by redefining the original entities, if possible; don't edit any of the original modules except for the driver file.
Favor markup changes that place tighter validation restrictions on documents (subsets), rather than changes that would allow instances that no longer conform to standard DocBook (extensions).
Negotiate all changes with your interchange partners and document not only the substance of the changes, but the reasons for them.
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.
Prev | Home | Next |
Acknowledgments | Up | Setting Up DocBook for Customization |