Guide to the DocBook DTD
PrevChapter 2. Understanding, Using, and Maintaining DocBookNext

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 Entity

New Entity

Comments

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 Entity

Contents

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.mixXXXXXXab
component.mixXXXXXXXXXX
divcomponent. mixXXXXXXXXXX
example.mixXXXXX
figure.mixXXX
footnote.mixXXXXX
glossdef.mixXXXXXc
highlights.mixXXX
indexdiv. component.mixdXXXXe
legalnotice.mixXXXXf
para.mixXXXX
refcomponent. mixXXXXXXXXXX
sidebar.mixXXXXXXXgX
tabentry.mixXXXXh

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.mixXXXXXa
docinfo.char.mixXcbXa
ndxterm.char.mixXXXXXXXXa
para.char.mix (also contains synop.class)XXXXXXXXX
refinline.char.mixXXXXXXXX
refname.char.mixXX
smallcptr.char.mixXba
title.char.mixXXXXXXXXX
word.char.mixXcXXXa

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

Entity

Contexts

Contents

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

Entity

Attribute name(s)

Declared value

Default 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

PrevHomeNext
DocBook ArchitectureUpDocBook Changes Made and Planned