For the applications you have in mind, DocBook "out of the box" may not be exactly what you need. Perhaps you need additional inline elements or perhaps you want to remove elements that you never want your authors to use. By design, DocBook makes this sort of customization easy.
This chapter explains how to make your own customization layer. You might do this in order to:
Add new elements
Remove elements
Change the structure of existing elements
Add new attributes
Remove attributes
Broaden the range of values allowed in an attribute
Narrow the range of values in an attribute to a specific list or a fixed value
You can use customization layers to extend DocBook or subset it. Creating a DTD that is a strict subset of DocBook means that all of your instances are still completely valid DocBook instances, which may be important to your tools and stylesheets, and to other people with whom you share documents. An extension adds new structures, or changes the DTD in a way that is not compatible with DocBook. Extensions can be very useful, but might have a great impact on your environment.
Customization layers can be as small as restricting an attribute value or as large as adding an entirely different hierarchy on top of the inline elements.
Changing a DTD can have a wide-ranging impact on the tools and stylesheets that you use. It can have an impact on your authors and on your legacy documents. This is especially true if you make an extension. If you rely on your support staff to install and maintain your authoring and publishing tools, check with them before you invest a lot of time modifying the DTD. There may be additional issues that are outside your immediate control. Proceed with caution.
That said, DocBook is designed to be easy to modify. This chapter assumes that you are comfortable with SGML/XML DTD syntax, but the examples presented should be a good springboard to learning the syntax if it's not already familiar to you.
The DocBook DTD is usually referenced by its public identifier:
-//OASIS//DTD DocBook V3.1//EN
Previous versions of DocBook, V3.0 and the V2 variants, used the owner identifier Davenport, rather than OASIS.
If you make any changes to the structure of the DTD, it is imperative that you alter the public identifier that you use for the DTD and the modules you changed. The license agreement under which DocBook is distributed gives you complete freedom to change, modify, reuse, and generally hack the DTD in any way you want, except that you must not call your alterations "DocBook."
You should change both the owner identifier and the description. The original DocBook formal public identifiers use the following syntax:
-//OASIS//text-class DocBook description Vversion//EN
Your own formal public identifiers should use the following syntax in order to record their DocBook derivation:
-//your-owner-ID//text-class DocBook Vversion-Based [Subset|Extension|Variant] your-descrip-and-version//lang
For example:
-//O'Reilly//DTD DocBook V3.0-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.
There is only one file that you may change without changing the public identifier: dbgenent.mod. And you can add only entity and notation declarations to that file. (You can add anything you want, naturally, but if you add anything other than entity and notation declarations, you must change the public identifier!)
SGML and XML DTDs are really just collections of declarations. These declarations are stored in one or more files. A complete DTD is formed by combining these files together logically. Parameter entities are used for this purpose. Consider the following fragment:
<!ENTITY % dbpool SYSTEM "dbpool.mod"> (1) <!ENTITY % dbhier SYSTEM "dbhier.mod"> (2) %dbpool; (3) %dbhier; (4)
It is an important feature of DTD parsing that entity declarations can be repeated. If an entity is declared more than once, then the first declaration is used. Given this fragment:
<!ENTITY foo "Lenny"> <!ENTITY foo "Norm">
The replacement text for &foo; is "Lenny."
These two notions, that you can break a DTD into modules referenced with parameter entities and that the first entity declaration is the one that counts, are used to build "customization layers." With customization layers you can write a DTD that references some or all of DocBook, but adds your own modifications. Modifying the DTD this way means that you never have to edit the DocBook modules directly, which is a tremendous boon to maintaining your modules. When the next release of DocBook comes out, you usually only have to make changes to your customization layer and your modification will be back in sync with the new version.
Customization layers work particularly well in DocBook because the base DTD makes extensive use of parameter entities that can be redefined.
DocBook is a large and, at first glance, fairly complex DTD. Much of the apparent complexity is caused by the prolific use of parameter entities. This was an intentional choice on the part of the maintainers, who traded "raw readability" for customizability. This section provides a general overview of the structure of the DTD. After you understand it, DocBook will probably seem much less complicated.
DocBook is composed of seven primary modules. These modules decompose the DTD into large, related chunks. Most modifications are restricted to a single chunk.
Figure 5-1 shows the module structure of DocBook as a flowchart.
The modules are:
The main driver file. This module declares and references the other top-level modules.
The hierarchy. This module declares the elements that provide the hierarchical structure of DocBook (sets, books, chapters, articles, and so on).
Changes to this module alter the top-level structure of the DTD. If you want to write a DocBook-derived DTD with a different structure (something other than a book), but with the same paragraph and inline-level elements, you make most of your changes in this module.
The information pool. This module declares the elements that describe content (inline elements, bibliographic data, block quotes, sidebars, and so on) but are not part of the large-scale hierarchy of a document. You can incorporate these elements into an entirely different element hierarchy.
The most common reason for changing this module is to add or remove inline elements.
The notation declarations. This module declares the notations used by DocBook.
This module can be changed to add or remove notations.
The character entities. This module declares and references the ISO entity sets used by DocBook.
Changes to this module can add or remove entity sets.
The general entities. This is a place where you can customize the general entities available in DocBook instances.
This is the place to add, for example, boiler plate text, logos for institutional identity, or additional notations understood by your local processing system.
The CALS Table Model. CALS is an initiative by the United States Department of Defense to standardize the document types used across branches of the military. The CALS table model, published in MIL-HDBK-28001, was for a long time the most widely supported SGML table model (one might now argue that the HTML table model is more widely supported by some definitions of "widely supported"). In any event, it is the table model used by DocBook.
DocBook predates the publication of the OASIS Technical Resolution TR 9503:1995, which defines an industry standard exchange table model and thus incorporates the full CALS Table Model.
Most changes to the CALS table model can be accomplished by modifying parameter entities in dbpool.mod; changing this DTD fragment is strongly discouraged. If you want to use a different table model, remove this one and add your own.
The ISO standard character entity sets. These entity sets are not actually part of the official DocBook distribution, but are referenced by default.
There are some additional modules, initially undefined, that can be inserted at several places for "redeclaration." This is described in more detail in Section 5.8.5."
Customization layers are possible because DocBook has been extensively parameterized so that it is possible to make any changes that might be desired without ever editing the actual distributed modules. The parameter entities come in several flavors:
Classes group elements of a similar type: for example all the
lists are in the
If you want to add a new kind of something (a new kind of list or a new kind of verbatim environment, for example), you generally want to add the name of the new element to the appropriate class.
Mixtures are collections of classes that appear in content
models. For example, the content model of the
Example element includes
If you want to change the content model of some class of elements (lists or admonitions, perhaps), you generally want to change the definition of the appropriate mixture.
The
If you want to remove or redefine an element or its attribute list, you generally want to change its module marked section to IGNORE and possibly add a new definition for it in your customization layer.
The
The
These parameter entities control the inclusion and exclusion markup in element declarations.
Changing these declarations allows you to make global changes to the inclusions and exclusions in the DTD.
The
Although customization layers vary in complexity, most of them have the same general structure as other customization layers of similar complexity.
In the most common case, you probably want to include the entire DTD, but you want to make some small changes. These customization layers tend to look like this:
(1) Overrides of Entity Declarations Here (2) <!ENTITY % orig-docbook "-//OASIS//DTD DocBook V3.1//EN"> %orig-docbook; (3) New/Modified Element and Attribute Declarations Here
In slightly more complex customization layers, the changes that you want to make are influenced by the interactions between modules. In these cases, rather than including the whole DTD at once, you include each of the modules separately, perhaps with entity or element declarations between them:
Overrides of Most Entity Declarations Here <!ENTITY % orig-pool "-//OASIS//ELEMENTS DocBook Information Pool V3.1//EN"> %orig-pool; Overrides of Document Hierarchy Entities Here <!ENTITY % orig-hier "-//OASIS//ELEMENTS DocBook Document Hierarchy V3.1//EN"> %orig-hier; New/Modified Element and Attribute Declarations Here <!ENTITY % orig-notn "-//OASIS//ENTITIES DocBook Notations V3.1//EN"> %orig-notn; <!ENTITY % orig-cent "-//OASIS//ENTITIES DocBook Character Entities V3.1//EN"> %orig-cent; <!ENTITY % orig-gen "-//OASIS//ENTITIES DocBook Additional General Entities V3.1//EN"> %orig-gen;
Finally, it's worth noting that in the rare case in which you need certain kinds of very simple, "one-off" customizations, you can do them in the document subset:
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V3.1//EN" [ Overrides of Entity Declarations Here New/Modified Element and Attribute Declarations Here ]> <book>...</book>
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 Section 5.4," finding something similar usually provides a good model for new changes.
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: https://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
Example 5-1. Adding MethodName with a Customization Layer
<!ENTITY % local.tech.char.class "|MethodName"> (1) <!-- load DocBook --> (2) <!ENTITY % DocBookDTD PUBLIC "-//OASIS//DTD DocBook V3.1//EN"> %DocBookDTD; <!ELEMENT MethodName - - ((%smallcptr.char.mix;)+) (3)> <!ATTLIST MethodName (4) %common.attrib; %classname.role.attrib; %local.classname.attrib; >
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 Section 5.2"
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"and use that public identifier in your documents:
<!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).
DTDs, by their nature, contain many complex, interrelated elements. Whenever you make a change to the DTD, it's always wise to use a validating parser to double-check your work. A parser like nsgmls from James Clark's SP can identify elements (attributes, parameter entities) that are declared but unused, as well as ones that are used but undeclared.
A comprehensive test can be accomplished with nsgmls using the -wall option. Create a simple test document and run:
nsgmls (1)-sv (2)-wall test.sgm
If you run the preceding command over DocBook V3.1, you'll discover one warning generated by the DTD:
nsgmls:I: SP version "1.3" nsgmls:cals-tbl.dtd:314:37:W: content model is mixed but does not allow #PCDATA everywhere
This is not truly an error in the DTD, and can safely be ignored. The warning is caused by "pernicious mixed content" in the content model of DocBook's Entry element. See the Entry reference page for a complete discussion.
DocBook has a large number of elements. In some authoring environments, it may be useful or necessary to remove some of these elements.
MsgSet is a favorite target. It has a complex internal structure designed for describing interrelated error messages, especially on systems that may exhibit messages from several different components. Many technical documents can do without it, and removing it leaves one less complexity to explain to your authors.
Example 5-2 shows a customization layer that removes the MsgSet element from DocBook:
Example 5-2. Removing MsgSet
<!ENTITY % compound.class "Procedure|SideBar"> (1) <!ENTITY % msgset.content.module "IGNORE"> (2) <!-- load DocBook --> <!ENTITY % DocBookDTD PUBLIC "-//OASIS//DTD DocBook V3.1//EN"> %DocBookDTD;
DocBook contains a large number of computer inlines. The DocBook
inlines define a domain-specific vocabulary. If you're working in
another domain, many of them may be unnecessary. You can remove a
bunch of them by redefining the
<!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|Markup|MediaLabel|MenuChoice |MouseButton|MsgText|Option|Optional|Parameter|Prompt|Property |Replaceable|ReturnValue|SGMLTag|StructField|StructName |Symbol|SystemItem|Token|Type|UserInput %local.tech.char.class;">
When examining this list, it seems that you can delete all of the inlines except, perhaps, Application, Command, Email, Filename, Literal, Replaceable, Symbol, and SystemItem. The following customization layer removes them.
Example 5-3. Removing Computer Inlines
<!ENTITY % tech.char.class "Application|Command|Email|Filename|Literal |Replaceable|Symbol|SystemItem"> <!ENTITY % action.module "IGNORE"> <!ENTITY % classname.module "IGNORE"> <!ENTITY % computeroutput.module "IGNORE"> <!ENTITY % database.module "IGNORE"> <!ENTITY % envar.module "IGNORE"> <!ENTITY % errorcode.module "IGNORE"> <!ENTITY % errorname.module "IGNORE"> <!ENTITY % errortype.module "IGNORE"> <!--<!ENTITY % function.module "IGNORE">--> <!ENTITY % guibutton.module "IGNORE"> <!ENTITY % guiicon.module "IGNORE"> <!ENTITY % guilabel.module "IGNORE"> <!ENTITY % guimenu.module "IGNORE"> <!ENTITY % guimenuitem.module "IGNORE"> <!ENTITY % guisubmenu.module "IGNORE"> <!ENTITY % hardware.module "IGNORE"> <!ENTITY % interface.module "IGNORE"> <!ENTITY % interfacedefinition.module "IGNORE"> <!--<!ENTITY % keycap.module "IGNORE">--> <!ENTITY % keycode.module "IGNORE"> <!--<!ENTITY % keycombo.module "IGNORE">--> <!--<!ENTITY % keysym.module "IGNORE">--> <!ENTITY % markup.module "IGNORE"> <!ENTITY % medialabel.module "IGNORE"> <!ENTITY % menuchoice.module "IGNORE"> <!--<!ENTITY % mousebutton.module "IGNORE">--> <!--<!ENTITY % msgtext.module "IGNORE">--> <!--<!ENTITY % option.module "IGNORE">--> <!--<!ENTITY % optional.module "IGNORE">--> <!--<!ENTITY % parameter.module "IGNORE">--> <!ENTITY % prompt.module "IGNORE"> <!ENTITY % property.module "IGNORE"> <!ENTITY % returnvalue.module "IGNORE"> <!ENTITY % sgmltag.module "IGNORE"> <!ENTITY % structfield.module "IGNORE"> <!ENTITY % structname.module "IGNORE"> <!ENTITY % token.module "IGNORE"> <!ENTITY % type.module "IGNORE"> <!ENTITY % userinput.module "IGNORE"> <!-- load DocBook --> <!ENTITY % DocBookDTD PUBLIC "-//OASIS//DTD DocBook V3.1//EN"> %DocBookDTD;
Initially we removed several more elements from
It's likely that a customization layer that removed this many technical inlines would also remove some larger technical structures (MsgSet, FuncSynopsis), which allows you to remove additional elements from the DTD.
Another possibility is removing the complex Synopsis elements. The customization layer in Example 5-4 removes CmdSynopsis and FuncSynopsis.
Example 5-4. Removing CmdSynopsis and FuncSynopsis
<!ENTITY % synop.class "Synopsis"> <!-- Instead of "Synopsis|CmdSynopsis|FuncSynopsis %local.synop.class;" --> <!ENTITY % funcsynopsis.content.module "IGNORE"> <!ENTITY % cmdsynsynopsis.content.module "IGNORE"> <!-- load DocBook --> <!ENTITY % DocBookDTD PUBLIC "-//OASIS//DTD DocBook V3.1//EN"> %DocBookDTD;
Completely removing all Synopsis elements would require a more
extensive customization. You can't make any of the
Perhaps you want to restrict your authors to only three levels of sectioning. To do that, you must remove the Sect4 and Sect5 elements, as shown in Example 5-5.
Example 5-5. Removing Sect4 and Sect5 Elements
<!ENTITY % sect3.module "IGNORE"> <!ENTITY % sect4.module "IGNORE"> <!ENTITY % sect5.module "IGNORE"> <!ENTITY % DocBookDTD PUBLIC "-//OASIS//DTD DocBook V3.1//EN"> %DocBookDTD; <!ENTITY % local.sect3.attrib ""> <!ENTITY % sect3.role.attrib "%role.attrib;"> <!ELEMENT Sect3 - O (Sect3Info?, (%sect.title.content;), (%nav.class;)*, (((%divcomponent.mix;)+, ((%refentry.class;)* | SimpleSect*)) | (%refentry.class;)+ | SimpleSect+), (%nav.class;)*)> <!ATTLIST Sect3 -- Renderas: Indicates the format in which the heading should appear -- Renderas (Sect1 |Sect2 |Sect4 |Sect5) #IMPLIED %label.attrib; %status.attrib; %common.attrib; %sect3.role.attrib; %local.sect3.attrib; >
In order to completely remove an element that isn't in the information pool, it is usually necessary to redefine the elements that include it. In this case, because we're removing the Sect4 element, we must redefine the Sect3 element that uses it.
All of the customization layers that we've examined so far have been fairly straightforward. This section describes a much more complex customization layer. Back in Section 5.4.1" we mentioned that several additional modules existed for "redeclaration." The customization layer developed in this section cannot be written without them.
The goal is to remove admonitions (Warning, Caution, Note) from table entries.
Example 5-6 is a straightforward, and incorrect, attempt.
Example 5-6. Removing Admonitions (First Attempt: Incorrect)
<!-- THIS CUSTOMIZATION LAYER CONTAINS ERRORS --> <!ENTITY % tabentry.mix "%list.class; |%linespecific.class; |%para.class; |Graphic %local.tabentry.mix;"> <!-- load DocBook --> <!ENTITY % DocBookDTD PUBLIC "-//OASIS//DTD DocBook V3.1//EN"> %DocBookDTD;
If you attempt to parse this DTD, you'll find that the declaration
of
Your second attempt might look like Example 5-7.
Example 5-7. Removing Admonitions (Second Attempt: Incorrect)
<!-- THIS CUSTOMIZATION LAYER DOESN'T WORK --> <!-- load DocBook --> <!ENTITY % DocBookDTD PUBLIC "-//OASIS//DTD DocBook V3.1//EN"> %DocBookDTD; <!ENTITY % tabentry.mix "%list.class; |%linespecific.class; |%para.class; |Graphic %local.tabentry.mix;">
This example contains no errors, but it also doesn't have any effect.
Remember, only the first entity declaration counts, so the declaration
of
The only way to fix this problem is to make use of one of the redeclaration placeholders in DocBook.
Redeclaration placeholders are spots in which you can insert definitions into the middle of the DTD. There are four redeclaration placeholders in DocBook:
Inserted in docbook.dtd, between
dbpool.mod and
dbhier.mod. This placeholder is controlled by the
Inserted in the middle of dbpool.mod,
between the
Inserted in the middle of dbhier.mod,
between the
Also inserted into dbhier.mod, after the
Use the redeclaration placeholder that it occurs nearest to, but
before the entity that you want to redeclare. In our case, this is
Example 5-8. Removing Admonitions (Third Attempt: Correct, if confusing)
<!ENTITY % dbpool.redecl.module "INCLUDE"> <!ENTITY % rdbpool '<!ENTITY % local.tabentry.mix ""> <!ENTITY % tabentry.mix "%list.class; |%linespecific.class; |%para.class; |Graphic %local.tabentry.mix;">'> <!-- load DocBook --> <!ENTITY % DocBookDTD PUBLIC "-//OASIS//DTD DocBook V3.1//EN"> %DocBookDTD;
Example 5-8 uses numeric character entity references to escape the % signs in the entity declarations and nests an entity declaration in another parameter entity. All of this is perfectly legal, but a bit confusing. A clearer solution, and the only practical solution if you're doing anything more than a single redeclaration, is to place the new declarations in another file and include them in your customization layer by reference, like this:
Example 5-9. Removing Admonitions (Fourth Attempt: Correct)
In your customization layer:
<!ENTITY % dbpool.redecl.module "INCLUDE"> <!ENTITY % rdbpool SYSTEM "rdbpool.mod"> <!-- load DocBook --> <!ENTITY % DocBookDTD PUBLIC "-//OASIS//DTD DocBook V3.1//EN"> %DocBookDTD;
In rdbpool.mod:
<!ENTITY % local.tabentry.mix ""> <!ENTITY % tabentry.mix "%list.class; |%linespecific.class; |%para.class; |Graphic %local.tabentry.mix;">
Perhaps the modification that you want to make is to completely remove
an entire class of elements. (If you have no need for synopsis
elements of any sort, why not remove them?) In order to remove an
entire class of elements, you must not only redefine the class as
empty, but you must also redefine all of the parameter entities that
use that class. The customization layer below completely removes the
Example 5-10. Removing
In the customization layer:
<!ENTITY % synop.class ""> <!ENTITY % dbpool.redecl.module "INCLUDE"> <!ENTITY % rdbpool SYSTEM "remv.synop.class.rdbpool.mod"> <!ENTITY % dbhier.redecl.module "INCLUDE"> <!ENTITY % rdbhier SYSTEM "remv.synop.class.rdbhier.mod"> <!-- load DocBook --> <!ENTITY % DocBookDTD PUBLIC "-//OASIS//DTD DocBook V3.1//EN"> %DocBookDTD;
In remv.synop.class.rdbpool.mod:
<!ENTITY % local.component.mix ""> <!ENTITY % component.mix "%list.class; |%admon.class; |%linespecific.class; |%para.class; |%informal.class; |%formal.class; |%compound.class; |%genobj.class; |%descobj.class; %local.component.mix;"> <!ENTITY % local.sidebar.mix ""> <!ENTITY % sidebar.mix "%list.class; |%admon.class; |%linespecific.class; |%para.class; |%informal.class; |%formal.class; |Procedure |%genobj.class; %local.sidebar.mix;"> <!ENTITY % local.footnote.mix ""> <!ENTITY % footnote.mix "%list.class; |%linespecific.class; |%para.class; |%informal.class; %local.footnote.mix;"> <!ENTITY % local.example.mix ""> <!ENTITY % example.mix "%list.class; |%linespecific.class; |%para.class; |%informal.class; %local.example.mix;"> <!ENTITY % local.admon.mix ""> <!ENTITY % admon.mix "%list.class; |%linespecific.class; |%para.class; |%informal.class; |%formal.class; |Procedure|Sidebar |Anchor|BridgeHead|Comment %local.admon.mix;"> <!ENTITY % local.figure.mix ""> <!ENTITY % figure.mix "%linespecific.class; |%informal.class; %local.figure.mix;"> <!ENTITY % local.glossdef.mix ""> <!ENTITY % glossdef.mix "%list.class; |%linespecific.class; |%para.class; |%informal.class; |%formal.class; |Comment %local.glossdef.mix;"> <!ENTITY % local.para.char.mix ""> <!ENTITY % para.char.mix "#PCDATA |%xref.char.class; |%gen.char.class; |%link.char.class; |%tech.char.class; |%base.char.class; |%docinfo.char.class; |%other.char.class; |%inlineobj.char.class; %local.para.char.mix;">
In remv.synop.class.rdbhier.mod:
<!ENTITY % local.divcomponent.mix ""> <!ENTITY % divcomponent.mix "%list.class; |%admon.class; |%linespecific.class; |%para.class; |%informal.class; |%formal.class; |%compound.class; |%genobj.class; |%descobj.class; %local.divcomponent.mix;"> <!ENTITY % local.refcomponent.mix ""> <!ENTITY % refcomponent.mix "%list.class; |%admon.class; |%linespecific.class; |%para.class; |%informal.class; |%formal.class; |%compound.class; |%genobj.class; |%descobj.class; %local.refcomponent.mix;"> <!ENTITY % local.indexdivcomponent.mix ""> <!ENTITY % indexdivcomponent.mix "ItemizedList|OrderedList|VariableList|SimpleList |%linespecific.class; |%para.class; |%informal.class; |Anchor|Comment |%link.char.class; %local.indexdivcomponent.mix;">
Just as there may be more elements than you need, there may be more attributes.
Suppose you want to remove the RenderAs attribute from the Sect1 element. RenderAs allows the author to "cheat" in the presentation of hierarchy by specifying that the stylesheet should render a Sect1 as something else: a Sect3, perhaps. Example 5-11 details the removal of RenderAs.
Example 5-11. Removing RenderAs from Sect1
<!ENTITY % sect1.module "IGNORE"> (1) <!-- load DocBook --> (2) <!ENTITY % DocBookDTD PUBLIC "-//OASIS//DTD DocBook V3.1//EN"> %DocBookDTD; <!ENTITY % local.sect1.attrib ""> (3) <!ENTITY % sect1.role.attrib "%role.attrib;"> (4) <!ELEMENT Sect1 - O (Sect1Info?, (%sect.title.content;), (%nav.class;)*, (5) (((%divcomponent.mix;)+, ((%refentry.class;)* | Sect2* | SimpleSect*)) | (%refentry.class;)+ | Sect2+ | SimpleSect+), (%nav.class;)*) +(%ubiq.mix;)> <!ATTLIST Sect1 (6) %label.attrib; %status.attrib; %common.attrib; %sect1.role.attrib; %local.sect1.attrib; >
DocBook defines eleven common attributes; these attributes appear on every element. Depending on how you're processing your documents, removing some of them can both simplify the authoring task and improve processing speed.
Some obvious candidates are:
If you're not using all of the effectivity attributes in your documents, you can get rid of up to seven attributes in one fell swoop.
If you're not producing multilingual documents, you can remove Lang.
The Remap attribute is designed to hold the name of a semantically equivalent construct from a previous markup scheme (for example, a Microsoft Word style template name, if you're converting from Word). If you're authoring from scratch, or not preserving previous constructs with Remap, you can get rid of it.
If your processing system isn't using XrefLabel, it's a candidate as well.
The customization layer in Example 5-12 reduces the common attributes to just ID and Lang.
Example 5-12. Removing Common Attributes
<!ENTITY % common.attrib "ID ID #IMPLIED Lang CDATA #IMPLIED" > <!ENTITY % idreq.common.attrib "ID ID #REQUIRED Lang CDATA #IMPLIED" > <!-- load DocBook --> <!ENTITY % DocBookDTD PUBLIC "-//OASIS//DTD DocBook V3.1//EN"> %DocBookDTD;
By definition, whatever attributes you define in the
Adding a structural (as opposed to information pool) element generally requires adding its name to a class and then providing the appropriate definitions. Example 5-13 extends DocBook by adding a Sect6 element.
Example 5-13. Adding a Sect6 Element
<!ENTITY % sect5.module "IGNORE"> <!ENTITY % DocBookDTD PUBLIC "-//OASIS//DTD DocBook V3.1//EN"> %DocBookDTD; <!-- Add Sect6 to content model of Sect5 --> <!ENTITY % sect5.role.attrib "%role.attrib;"> <!ELEMENT Sect5 - O (Sect5Info?, (%sect.title.content;), (%nav.class;)*, (((%divcomponent.mix;)+, ((%refentry.class;)* | Sect6* | SimpleSect*)) | (%refentry.class;)+ | Sect6+ | SimpleSect+), (%nav.class;)*)> <!ATTLIST Sect5 %label.attrib; %status.attrib; %common.attrib; %sect5.role.attrib; > <!ENTITY % sect6.role.attrib "%role.attrib;"> <!ELEMENT Sect6 - O (Sect6Info?, (%sect.title.content;), (%nav.class;)*, (((%divcomponent.mix;)+, ((%refentry.class;)* | SimpleSect*)) | (%refentry.class;)+ | SimpleSect+), (%nav.class;)*)> <!ATTLIST Sect6 %label.attrib; %status.attrib; %common.attrib; %sect6.role.attrib; >
Here we've redefined Sect5 to include Sect6 and provided a declaration for Sect6. Note that we didn't bother to provide RenderAs attributes in our redefinitions. To properly support Sect6, you might want to redefine all of the sectioning elements so that Sect6 is a legal attribute value for RenderAs.
The Role attribute, found on almost all of the elements in DocBook, is a CDATA attribute that can be used to subclass an element. In some applications, it may be useful to modify the definition of Role so that authors must choose one of a specific set of possible values.
In Example 5-14, Role on the Procedure element is constrained to the values Required or Optional.
Copyright © 1999 O'Reilly & Associates, Inc. All rights reserved.