[Chapter 2] 2.6 DocBook Entities

Chapter 2. Overview of the DocBook DTD

2.6 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

notationtypes notation.class

commonatts common.attrib

yesorno yesorno.attvals

yes yes.attval

no no.attval

appendix.gp appendix.class

book.gp book.class

chapter.gp chapter.class

index.gp index.class

bookcontent.gp partcontent.mix

ndxterm.gp ndxterm.class

xref.gp xref.char.class

links.gp link.char.class

basechar.gp base.char.class No #PCDATA directly in entity

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

bookinfo.content.gp setinfo.char.mix Now contains ModeSpec; omission was an oversight

docinfo.content.gp docinfo.char.class

words.gp word.char.class

computerterms.gp cptr.char.class

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

inlinechar.gp Removed in V2.4; see para.char.mix In V2.3, was inline.char.mix

eqncontent.gp equation.content No more local.equations

tblcontent.gp table.content No more local.tables

list.gp list.class

admonition.gp admon.class

code.example.gp linespecific.class

synop.gp synop.class

object.gp (informal.class + linespecific.class + synop.class) No single replacement entity

para.gp para.class

formalobject.gp formal.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.gp refclass.char.mix

nav.gp nav.class

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

sect1.gp bookcomponent. content In V2.3, was sect1.content

ubiq.gp ubiq.mix

primsee (none)

secsee (none)

argchcatt (none)

grpchcatt (none)

repatt (none)

Original Entity	New Entity	Comments
notationtypes	notation.class
commonatts	common.attrib
yesorno	yesorno.attvals
yes	yes.attval
no	no.attval
appendix.gp	appendix.class
book.gp	book.class
chapter.gp	chapter.class
index.gp	index.class
bookcontent.gp	partcontent.mix
ndxterm.gp	ndxterm.class
xref.gp	xref.char.class
links.gp	link.char.class
basechar.gp	base.char.class	No #PCDATA directly in entity
phrase.gp	Removed in V2.4	In V2.3, was phrase.char.mix (other.char.class + base.char.class + link.char.class)
bookinfo.content.gp	setinfo.char.mix	Now contains ModeSpec; omission was an oversight
docinfo.content.gp	docinfo.char.class
words.gp	word.char.class
computerterms.gp	cptr.char.class
cptrphrase.gp	cptr.char.mix (cptr.char.class + other.char.class + base.char.class + link.char.class)
inlinechar.gp	Removed in V2.4; see para.char.mix	In V2.3, was inline.char.mix
eqncontent.gp	equation.content	No more local.equations
tblcontent.gp	table.content	No more local.tables
list.gp	list.class
admonition.gp	admon.class
code.example.gp	linespecific.class
synop.gp	synop.class
object.gp	(informal.class + linespecific.class + synop.class)	No single replacement entity
para.gp	para.class
formalobject.gp	formal.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.gp	refclass.char.mix
nav.gp	nav.class
inlineobj.gp	para.char.mix (inline.char.mix + inlineobj.char.class + synop.class)
sect1.gp	bookcomponent. content	In V2.3, was sect1.content
ubiq.gp	ubiq.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.class Caution, Important, Note, Tip, Warning

appendix.class Appendix

article.class Article

base.char.class Anchor

book.class Book

chapter.class Chapter

compound.class MsgSet, 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.class Abstract, AuthorBlurb, Epigraph

docinfo.char.class Author, AuthorInitials, CorpAuthor, ModeSpec, OtherCredit, ProductName, ProductNumber, RevHistory

formal.class Equation, Example, Figure, Table

genobj.class Anchor, BridgeHead, Comment, Highlights

index.class Index, SetIndex

informal.class Address, BlockQuote, Graphic, GraphicCO, InformalEquation, InformalExample, InformalTable

inlineobj.char.class InlineGraphic, InlineEquation

linespecific.class LiteralLayout, ProgramListing, ProgramListingCO, Screen, ScreenCO, ScreenShot

link.char.class Link, OLink, ULink

list.class CalloutList, GlossList, ItemizedList, OrderedList, SegmentedList, SimpleList, VariableList

nav.class ToC, LoT, Index, Glossary, Bibliography

ndxterm.class IndexTerm

notation.class BMP, 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.class Comment, Subscript, Superscript

para.class FormalPara, Para, SimPara

refentry.class RefEntry

synop.class Synopsis, CmdSynopsis, FuncSynopsis

word.char.class Abbrev, Acronym, Citation, CiteTitle, CiteRefEntry, Emphasis, FirstTerm, ForeignPhrase, GlossTerm, Footnote, Phrase, Quote, Trademark, WordAsWord

xref.char.class FootnoteRef, XRef

Class Entity	Contents
admon.class	Caution, Important, Note, Tip, Warning
appendix.class	Appendix
article.class	Article
base.char.class	Anchor
book.class	Book
chapter.class	Chapter
compound.class	MsgSet, 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.class	Abstract, AuthorBlurb, Epigraph
docinfo.char.class	Author, AuthorInitials, CorpAuthor, ModeSpec, OtherCredit, ProductName, ProductNumber, RevHistory
formal.class	Equation, Example, Figure, Table
genobj.class	Anchor, BridgeHead, Comment, Highlights
index.class	Index, SetIndex
informal.class	Address, BlockQuote, Graphic, GraphicCO, InformalEquation, InformalExample, InformalTable
inlineobj.char.class	InlineGraphic, InlineEquation
linespecific.class	LiteralLayout, ProgramListing, ProgramListingCO, Screen, ScreenCO, ScreenShot
link.char.class	Link, OLink, ULink
list.class	CalloutList, GlossList, ItemizedList, OrderedList, SegmentedList, SimpleList, VariableList
nav.class	ToC, LoT, Index, Glossary, Bibliography
ndxterm.class	IndexTerm
notation.class	BMP, 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.class	Comment, Subscript, Superscript
para.class	FormalPara, Para, SimPara
refentry.class	RefEntry
synop.class	Synopsis, CmdSynopsis, FuncSynopsis
word.char.class	Abbrev, Acronym, Citation, CiteTitle, CiteRefEntry, Emphasis, FirstTerm, ForeignPhrase, GlossTerm, Footnote, Phrase, Quote, Trademark, WordAsWord
xref.char.class	FootnoteRef, 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

list adm line syn para inf form cmpd gen desc

admon.mix X X X X X X a b

component.mix X X X X X X X X X X

divcomponent. mix X X X X X X X X X X

example.mix X X X X X

figure.mix X X X

footnote.mix X X X X X

glossdef.mix X X X X X c

highlights.mix X X X

indexdiv. component.mix d X X X X e

legalnotice.mix X X X X f

para.mix X X X X

refcomponent. mix X X X X X X X X X X

sidebar.mix X X X X X X X g X

tabentry.mix X X X X h

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

	list	adm	line	syn	para	inf	form	cmpd	gen	desc
admon.mix	X		X	X	X	X	X	a	b
component.mix	X	X	X	X	X	X	X	X	X	X
divcomponent. mix	X	X	X	X	X	X	X	X	X	X
example.mix	X		X	X	X	X
figure.mix			X	X		X
footnote.mix	X		X	X	X	X
glossdef.mix	X		X	X	X	X		c
highlights.mix	X	X			X
indexdiv. component.mix	d		X	X	X	X			e
legalnotice.mix	X	X	X		X	f
para.mix	X		X	X		X
refcomponent. mix	X	X	X	X	X	X	X	X	X	X
sidebar.mix	X	X	X	X	X	X	X	g	X
tabentry.mix	X	X	X		X	h
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

#P X W L C B D O I

cptr.char.mix X X X X X a

docinfo.char.mix X c b X a

ndxterm.char.mix X X X X X X X X a

para.char.mix (also contains synop.class) X X X X X X X X X

refinline.char.mix X X X X X X X X

refname.char.mix X X

smallcptr.char.mix X b a

title.char.mix X X X X X X X X X

word.char.mix X c X X X a

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

	#P	X	W	L	C	B	D	O	I
cptr.char.mix	X			X	X	X		X	a
docinfo.char.mix	X		c		b			X	a
ndxterm.char.mix	X	X	X	X	X	X	X	X	a
para.char.mix (also contains synop.class)	X	X	X	X	X	X	X	X	X
refinline.char.mix	X	X	X	X	X	X	X	X
refname.char.mix	X				X
smallcptr.char.mix	X				b				a
title.char.mix	X	X	X	X	X	X	X	X	X
word.char.mix	X		c	X		X		X	a
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:

The mixture ubiq.mix contains ndxterm.class and BeginPage.
The mixture person.ident.mix contains Honorific, FirstName, Surname, Lineage, OtherName, Affiliation, AuthorBlurb, and Contrib.
The mixture partcontent.mix contains appendix.class, chapter.class, nav.class, Preface, refentry.class, and Reference.
The mixture setinfo.char.mix contains #PCDATA, docinfo.char.class, Title, Copyright, CorpName, Date, Editor, Edition, InvPartNumber, ISBN, LegalNotice, OrgName, PrintHistory, Publisher, PubsNumber, ReleaseInfo, SubTitle, and VolumeNum.

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.content Chapter-level elements, PartIntro, and Article A divcomponent mixture followed by either Sect1s, RefEntries, or SimpleSects

bookcomponent.title.content Chapter-level divisions, ToC, LoT, Part, Reference, Bibliography, Glossary, Index, SetIndex An optional DocInfo, followed by Title, followed optionally by TitleAbbrev

div.title.content Set, Book, PartIntro, DocInfo, SeriesInfo, ArtHeader Title followed optionally by TitleAbbrev

equation.content Equation, InformalEquation One or more Graphics

formalobject.title.content Formal objects, Procedure, Sidebar, SegmentedList, VariableList Title followed optionally by TitleAbbrev

inlineequation.content InlineEquation One or more Graphics

programlisting.content ProgramListing A mixture of CO, LineAnnotation and inline.char.mix

refsect.title.content Reference entry sections Title followed optionally by TitleAbbrev

screen.content Screen A mixture of CO, LineAnnotation and inline.char.mix

sect.title.content Sections Title followed optionally by TitleAbbrev

Entity	Contexts	Contents
bookcomponent.content	Chapter-level elements, PartIntro, and Article	A divcomponent mixture followed by either Sect1s, RefEntries, or SimpleSects
bookcomponent.title.content	Chapter-level divisions, ToC, LoT, Part, Reference, Bibliography, Glossary, Index, SetIndex	An optional DocInfo, followed by Title, followed optionally by TitleAbbrev
div.title.content	Set, Book, PartIntro, DocInfo, SeriesInfo, ArtHeader	Title followed optionally by TitleAbbrev
equation.content	Equation, InformalEquation	One or more Graphics
formalobject.title.content	Formal objects, Procedure, Sidebar, SegmentedList, VariableList	Title followed optionally by TitleAbbrev
inlineequation.content	InlineEquation	One or more Graphics
programlisting.content	ProgramListing	A mixture of CO, LineAnnotation and inline.char.mix
refsect.title.content	Reference entry sections	Title followed optionally by TitleAbbrev
screen.content	Screen	A mixture of CO, LineAnnotation and inline.char.mix
sect.title.content	Sections	Title 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.attrib Arch CDATA #IMPLIED

common.attrib id.attrib, lang.attrib, remap.attrib, role.attrib, xreflabel.attrib, revisionflag.attrib, effectivity.attrib

effectivity.attrib arch.attrib, os.attrib, revision.attrib, userlevel.attrib, vendor.attrib

graphics.attrib All attributes related to specifying graphics

id.attrib Id ID #IMPLIED

idreq.attrib Id ID #REQUIRED

idreq.common.attrib idreq.attrib, lang.attrib, remap.attrib, role.attrib, xreflabel.attrib

label.attrib Label CDATA #IMPLIED

lang.attrib Lang CDATA #IMPLIED

linespecific.attrib Format NOTATION linespecific linespecific

linkend.attrib Linkend IDREF #IMPLIED

linkendreq.attrib Linkend IDREF #REQUIRED

linkends.attrib Linkends IDREFS #IMPLIED

linkendsreq.attrib Linkends IDREF #REQUIRED

mark.attrib Mark CDATA #IMPLIED

moreinfo.attrib MoreInfo (RefEntry| None) None

os.attrib OS CDATA #IMPLIED

pagenum.attrib PageNum CDATA #IMPLIED

remap.attrib Remap CDATA #IMPLIED

revision.attrib Revision CDATA #IMPLIED

revisionflag.attrib RevisionFlag (Changed |Added |Deleted) #IMPLIED

role.attrib Role CDATA #IMPLIED

userlevel.attrib UserLevel CDATA #IMPLIED

vendor.attrib Vendor CDATA #IMPLIED

xreflabel.attrib XRefLabel CDATA #IMPLIED

Entity	Attribute name(s)	Declared value	Default value
arch.attrib	Arch	CDATA	#IMPLIED
common.attrib	id.attrib, lang.attrib, remap.attrib, role.attrib, xreflabel.attrib, revisionflag.attrib, effectivity.attrib
effectivity.attrib	arch.attrib, os.attrib, revision.attrib, userlevel.attrib, vendor.attrib
graphics.attrib	All attributes related to specifying graphics
id.attrib	Id	ID	#IMPLIED
idreq.attrib	Id	ID	#REQUIRED
idreq.common.attrib	idreq.attrib, lang.attrib, remap.attrib, role.attrib, xreflabel.attrib
label.attrib	Label	CDATA	#IMPLIED
lang.attrib	Lang	CDATA	#IMPLIED
linespecific.attrib	Format	NOTATION linespecific	linespecific
linkend.attrib	Linkend	IDREF	#IMPLIED
linkendreq.attrib	Linkend	IDREF	#REQUIRED
linkends.attrib	Linkends	IDREFS	#IMPLIED
linkendsreq.attrib	Linkends	IDREF	#REQUIRED
mark.attrib	Mark	CDATA	#IMPLIED
moreinfo.attrib	MoreInfo	(RefEntry\| None)	None
os.attrib	OS	CDATA	#IMPLIED
pagenum.attrib	PageNum	CDATA	#IMPLIED
remap.attrib	Remap	CDATA	#IMPLIED
revision.attrib	Revision	CDATA	#IMPLIED
revisionflag.attrib	RevisionFlag	(Changed \|Added \|Deleted)	#IMPLIED
role.attrib	Role	CDATA	#IMPLIED
userlevel.attrib	UserLevel	CDATA	#IMPLIED
vendor.attrib	Vendor	CDATA	#IMPLIED
xreflabel.attrib	XRefLabel	CDATA	#IMPLIED

[Prev] DocBook Architecture
[Next] DocBook Changes Made and Planned
[Overview Home] [Davenport Group Home]