DocBook Entities

DocBook relies heavily on internal parameter entities (substitution-string mechanisms that work somewhat like programming macros) to achieve consistency, ease maintenance, and encourage appropriate customization. Unfortunately, the density of entity references can make it difficult to read the actual element and attribute declarations. The major entities used inside these declarations are described briefly here.

There are two special kinds of entities that are used to group elements: classes and mixtures. Class entities are used to group elements that are very similar, such as "all the list elements." Mixture entities are used to group whole element classes (and sometimes individual elements as well) that are all supposed to be allowed in a particular set of contexts. Classes and mixtures are described in more detail below.

Patterns of Entity Naming and Usage

Example 2-1 shows a synopsis of the kinds of parameter entities that are used in the definition of most elements in DocBook.

Example 2-1. Parameter Entity Synopsis

<!ENTITY % element.content.module "INCLUDE">     aggregate module entity
<!ENTITY % element.module "INCLUDE">             simple module entity
<!ENTITY % subelement.module "INCLUDE">          simple module entity
⋮
<!ENTITY % class1.class "elem1|elem2">        class entity
<!ENTITY % class2.class "elem3|elem4">        class entity
⋮
<!ENTITY % mixture1.mix "%class1.class;|%class2.class;"  mixture entity
<!ENTITY % mixture2.mix "%class1.class;">                  mixture entity
⋮
<![ %element.content.module; [                   aggregate module entity reference
<![ %element.module' [                           simple module entity reference
<!ENTITY % local.element.attrib "">              local attribute entity
<!ELEMENT element - - (subelement, (%mixture1.mix;)+)>
<!ATTLIST element
        %common.attrib;                            common attribute entity reference
        %local.element.attrib;                   local attribute entity reference
>
<!--end of element.module-->]]>
<![ %subelement.module' [                        simple module entity reference
<!ENTITY % local.subelement.attrib "">           local attribute entity
<!ELEMENT subelement - - ((%mixture2.mix;)+)>  content with mixture entity reference
<!ATTLIST subelement
        %common.attrib;                            common attribute entity reference
        %local.subelement.attrib;                local attribute entity reference
>
<!--end of subelement.module-->]]>
<!--end of element.content.module-->]]>

Previous and Current Parameter Entities

Table 2-1 shows the equivalences between the parameter entities in V2.2.1 and the versions starting with V2.3, in approximately the order that the original entities appear in DocBook V2.2.1. If you are new to reading DocBook, you don't need to read this table. (Note that many new entities have been added; these don't appear in the table.)

Table 2-1. Parameter Entity Equivalences

Original EntityNew EntityComments
notationtypesnotation.class 
commonattscommon.attrib 
yesornoyesorno.attvals 
yesyes.attval 
nono.attval 
appendix.gpappendix.class 
book.gpbook.class 
chapter.gpchapter.class 
index.gpindex.class 
bookcontent.gppartcontent.mix 
ndxterm.gpndxterm.class 
xref.gpxref.char.class 
links.gplink.char.class 
basechar.gpbase.char.classNo #PCDATA directly in entity
phrase.gpRemoved in V2.4

In V2.3, was phrase.char.mix (other.char.class + base.char.class + link.char.class)

bookinfo.content.gpsetinfo.char.mix

Now contains ModeSpec; omission was an oversight

docinfo.content.gpdocinfo.char.class 
words.gpword.char.class 
computerterms.gpcptr.char.class 
cptrphrase.gp

cptr.char.mix (cptr.char.class + other.char.class + base.char.class + link.char.class)

 
inlinechar.gpRemoved in V2.4; see para.char.mixIn V2.3, was inline.char.mix
eqncontent.gpequation.contentNo more local.equations
tblcontent.gptable.contentNo more local.tables
list.gplist.class 
admonition.gpadmon.class 
code.example.gplinespecific.class 
synop.gpsynop.class 
object.gp(informal.class + linespecific.class + synop.class)No single replacement entity
para.gppara.class 
formalobject.gpformal.class 
component.gp

component.mix, divcomponent.mix, refcomponent.mix (genobj.class + descobj.class + admon.class + formal.class + list.class + informal.class + linespecific.class + synop.class + para.class + compound.class)

 
refclass.gprefclass.char.mix 
nav.gpnav.class 
inlineobj.gp

para.char.mix (inline.char.mix + inlineobj.char.class + synop.class)

 
sect1.gpbookcomponent. contentIn V2.3, was sect1.content
ubiq.gpubiq.mix 
primsee(none) 
secsee(none) 
argchcatt(none) 
grpchcatt(none) 
repatt(none) 

Marked Section Entities

All of DocBook's element and attribute declaration pairs are surrounded by marked sections (regions that work somewhat like programming "ifdefs") whose status keywords are stored in entities. Some marked sections surround groups of related elements. In reading the DTD, you can simply ignore all the lines that look as follows:

<![ %name.content.module; [
<![ %name.module; [
⋮
<!--end of name.module-->]]>
<!--end of name.content.module-->]]>

Class (xxx.class) Entities

Class entities are used to build mixture entities and, in some cases, are used directly in element and attribute declarations in various capacities. Table 2-2 lists all the class entities and their contents in alphabetical order.

Table 2-2. Class Entities and Contents

Class EntityContents
admon.classCaution, Important, Note, Tip, Warning
appendix.classAppendix
article.classArticle
base.char.classAnchor
book.classBook
chapter.classChapter
compound.classMsgSet, Procedure, Sidebar
cptr.char.class

Action, Application, ClassName, Command, ComputerOutput, Database, Email, 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, Property, Replaceable, ReturnValue, SGMLTag, StructField, StructName, Symbol, SystemItem, Token, Type, UserInput

descobj.classAbstract, AuthorBlurb, Epigraph
docinfo.char.class

Author, AuthorInitials, CorpAuthor, ModeSpec, OtherCredit, ProductName, ProductNumber, RevHistory

formal.classEquation, Example, Figure, Table
genobj.class

Anchor, BridgeHead, Comment, Highlights

index.classIndex, SetIndex
informal.classAddress, BlockQuote, Graphic, GraphicCO, InformalEquation, InformalExample, InformalTable
inlineobj.char.classInlineGraphic, InlineEquation
linespecific.classLiteralLayout, ProgramListing, ProgramListingCO, Screen, ScreenCO, ScreenShot
link.char.classLink, OLink, ULink
list.classCalloutList, GlossList, ItemizedList, OrderedList, SegmentedList, SimpleList, VariableList
nav.classToC, LoT, Index, Glossary, Bibliography
ndxterm.classIndexTerm
notation.classBMP, CGM-CHAR, CGM-BINARY, CGM-CLEAR, DITROFF, DVI, EPS, EQN, FAX, GIF, IGES, PCX, PIC, PS, TBL, TEX, TIFF, WMF, WPG, linespecific (this is the only class entity that contains not element names, but non-SGML notation names)
other.char.classComment, Subscript, Superscript
para.classFormalPara, Para, SimPara
refentry.classRefEntry
synop.classSynopsis, CmdSynopsis, FuncSynopsis
word.char.classAbbrev, Acronym, Citation, CiteTitle, CiteRefEntry, Emphasis, FirstTerm, ForeignPhrase, GlossTerm, Footnote, Phrase, Quote, Trademark, WordAsWord
xref.char.classFootnoteRef, XRef

Mixture (xxx.mix) Entities

Mixture entities combine various class entities and individual elements for use in repeatable-OR content model groups.

Table 2-3 shows the pattern of class entities used to build the object-level mixture entities that are used directly in content models. An "X" means that all elements in the indicated class are allowed.

Table 2-3. Object-Level (xxx.mix) Mixture Entities and Contents

 listadmlinesynparainfformcmpdgendesc
admon.mixX XXXXXab 
component.mixXXXXXXXXXX
divcomponent. mixXXXXXXXXXX
example.mixX XXXX    
figure.mix  XX X    
footnote.mixX XXXX    
glossdef.mixX XXXX c  
highlights.mixXX  X     
indexdiv. component.mixd XXXX  e 
legalnotice.mixXXX Xf    
para.mixX XX X    
refcomponent. mixXXXXXXXXXX
sidebar.mixXXXXXXXgX 
tabentry.mixXXX Xh    

a: Procedure
and Sidebar only.
b: Anchor, BridgeHead, and Comment only.
c: Comment only.
d: ItemizedList, OrderedList, VariableList, and SimpleList only.
e: Anchor and Comment only.
f: BlockQuote only.
g: Procedure only.
h: Graphic only.

lst: list.class
adm: admon.class
line: linespecific.class
syn: synop.class
para: para.class
inf: informal.class
form: form.class
cmpd: compound.class
gen: genobj.class
desc: descobj.class

Table 2-4 shows the pattern of class entities used to build the inline-level mixture entities that are used directly in content models. An "X" means that all elements in the indicated class are allowed.

Table 2-4. Inline-Level (xxx.char.mix) Mixture Entities and Contents

 #PXWLCBDOI
cptr.char.mixX  XXX Xa
docinfo.char.mixX c b  Xa
ndxterm.char.mixXXXXXXXXa
para.char.mix (also contains synop.class)XXXXXXXXX
refinline.char.mixXXXXXXXX 
refname.char.mixX   X    
smallcptr.char.mixX   b   a
title.char.mixXXXXXXXXX
word.char.mixX cX X Xa

a: InlineGraphic
only.
b: Replaceable only.
c: Emphasis and Trademark only.

#P: #PCDATA
X: xref.char.class
W: word.char.class
L: link.char.class
C: cptr.char.class
B: base.char.class
D: docinfo.char.class
O: other.char.class
I: inlineobj.char.class

A few miscellaneous mixtures are also defined:

Content Model Fragment (xxx.content) Entities

Table 2-5 alphabetically lists the entities containing non-mixture fragments of content models, the contexts in which they are typically used, and their contents.

Table 2-5. Content Model Fragment Entities, Contexts, and Contents

EntityContextsContents
bookcomponent.contentChapter-level elements, PartIntro, and ArticleA divcomponent mixture followed by either Sect1s, RefEntries, or SimpleSects
bookcomponent.title.contentChapter-level divisions, ToC, LoT, Part, Reference, Bibliography, Glossary, Index, SetIndexAn optional DocInfo, followed by Title, followed optionally by TitleAbbrev
div.title.contentSet, Book, PartIntro, DocInfo, SeriesInfo, ArtHeaderTitle followed optionally by TitleAbbrev
equation.contentEquation, InformalEquationOne or more Graphics
formalobject.title.contentFormal objects, Procedure, Sidebar, SegmentedList, VariableListTitle followed optionally by TitleAbbrev
inlineequation.contentInlineEquationOne or more Graphics
programlisting.contentProgramListingA mixture of CO, LineAnnotation and inline.char.mix
refsect.title.contentReference entry sectionsTitle followed optionally by TitleAbbrev
screen.contentScreenA mixture of CO, LineAnnotation and inline.char.mix
sect.title.contentSectionsTitle followed optionally by TitleAbbrev

Attribute (xxx.attrib) Entities

Table 2-6 lists the entities that define individual attributes and groupings of attributes.

Attribute placeholder entities with the naming pattern local.xxx.attrib are defined in every ELEMENT/ATTLIST pair's marked section. You can ignore these entity declarations.

Table 2-6. Attribute Entities

EntityAttribute name(s)Declared valueDefault value
arch.attribArchCDATA#IMPLIED
common.attribid.attrib, lang.attrib, remap.attrib, role.attrib, xreflabel.attrib, revisionflag.attrib, effectivity.attrib  
effectivity.attribarch.attrib, os.attrib, revision.attrib, userlevel.attrib, vendor.attrib  
graphics.attribAll attributes related to specifying graphics  
id.attribIdID#IMPLIED
idreq.attribIdID#REQUIRED
idreq.common.attribidreq.attrib, lang.attrib, remap.attrib, role.attrib, xreflabel.attrib  
label.attribLabelCDATA#IMPLIED
lang.attribLangCDATA#IMPLIED
linespecific.attribFormatNOTATION linespecificlinespecific
linkend.attribLinkendIDREF#IMPLIED
linkendreq.attribLinkendIDREF#REQUIRED
linkends.attribLinkendsIDREFS#IMPLIED
linkendsreq.attribLinkendsIDREF#REQUIRED
mark.attribMarkCDATA#IMPLIED
moreinfo.attribMoreInfo(RefEntry| None)None
os.attribOSCDATA#IMPLIED
pagenum.attribPageNumCDATA#IMPLIED
remap.attribRemapCDATA#IMPLIED
revision.attribRevisionCDATA#IMPLIED
revisionflag.attribRevisionFlag(Changed |Added |Deleted)#IMPLIED
role.attribRoleCDATA#IMPLIED
userlevel.attribUserLevelCDATA#IMPLIED
vendor.attribVendorCDATA#IMPLIED
xreflabel.attribXRefLabelCDATA#IMPLIED