DocBook Entities

Guide to the DocBook DTD
Prev	Chapter 2. Understanding, Using, and Maintaining DocBook	Next

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)

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

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

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

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

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

Prev	Home	Next
DocBook Architecture	Up	DocBook Changes Made and Planned