The procedure for creating, testing, and using a customization layer is always about the same. In this section, we'll go through the process in some detail. The rest of the sections in this chapter describe a range of useful customization layers.
If you're considering writing a customization layer, there must be something that you want to change. Perhaps you want to add an element or attribute, remove one, or change some other aspect of the DTD.
Adding an element, particularly an inline element, is one possibility. If you're writing documentation about an object-oriented system, you may have noticed that DocBook provides ClassName but not MethodName. Suppose you want to add MethodName?
Figuring out what to change may be the hardest part of the process. The organization of the parameter entities is quite logical, and, bearing in mind the organization described in the Section called Understanding DocBook Structure, finding something similar usually provides a good model for new changes.
Two online resources may be useful. First, the parameter entity reference section of the online book provides more detail than the print version. Second, there is an alternate version of the book online that shows all of the element content models in terms of the parameter entities that define them, rather than the "flattened" versions shown here.
One resource that may be useful is the alternate version of this book that shows all of the element content models in terms of the parameter entities which define them, rather than the "flattened" versions shown here. The alternate version is on the CD-ROM and online at the book web site: http://docbook.org/.
MethodName is similar to ClassName, so ClassName is probably a good model. ClassName is an inline element, not a hierarchy element, so it's in dbpool.mod. Searching for "classname" in dbpool.mod reveals:
<!ENTITY % local.tech.char.class "">
<!ENTITY % tech.char.class
"Action|Application|ClassName|Command|ComputerOutput
|Database|Email|EnVar|ErrorCode|ErrorName|ErrorType|Filename
|Function|GUIButton|GUIIcon|GUILabel|GUIMenu|GUIMenuItem
|GUISubmenu|Hardware|Interface|InterfaceDefinition|KeyCap
|KeyCode|KeyCombo|KeySym|Literal|Constant|Markup|MediaLabel
|MenuChoice|MouseButton|MsgText|Option|Optional|Parameter
|Prompt|Property|Replaceable|ReturnValue|SGMLTag|StructField
|StructName|Symbol|SystemItem|Token|Type|UserInput|VarName
%local.tech.char.class;">
|
Searching further reveals the element and attribute declarations for ClassName.
It would seem (and, in fact, it is the case) that adding MethodName can be accomplished by adding it to the local extension mechanism for tech.char.class, namely local.tech.char.class, and adding element and attribute declarations for it. A customization layer that does this can be seen in Example 5-1.
Example 5-1. Adding MethodName with a Customization Layer
In order to use the new customization layer, you must save it in a file, for example mydocbk.dtd, and then you must use the new DTD in your document.
The simplest way to use the new DTD is to point to it with a system identifier:
<!DOCTYPE chapter SYSTEM "/path/to/mydocbk.dtd"> <chapter><title>My Chapter</title> <para> The Java <classname>Math</classname> class provides a <methodname>abs</methodname> method to compute absolute value of a number. </para> </chapter> |
If you plan to use your customization layer in many documents, or exchange it with interchange partners, consider giving your DTD its own public identifier, as described in the Section called If You Change DocBook, It's Not DocBook Anymore!
In order to use the new public identifier, you must add it to your catalog:
PUBLIC "-//Your Organization//DTD DocBook V3.1-Based Extension V1.0//EN" "/share/sgml/mydocbk.dtd" |
<!DOCTYPE chapter PUBLIC "-//Your Organization//DTD DocBook V3.1-Based Extension V1.0//EN"> <chapter><title>My Chapter</title> <para> The Java <classname>Math</classname> class provides a <methodname>abs</methodname> method to compute absolute value of a number. </para> </chapter> |
If you're using XML, remember that you must provide a system identifier that satisfies the requirements of a Uniform Resource Identifier (URI).