I. DocBook Element Reference

This reference describes every element in the DocBook DTD. Elements marked are new in DocBook V3.1, which was released in February, 1999.

1. Organization of Reference Pages

The description of each element in this reference is divided into the following sections:


Provides a quick synopsis of the element. The content of the synopsis table varies according to the nature of the element described, but may include any or all of the following sections:

Content Model or Declared Content

Describes the content model of the element in SGML/XML DTD terms. See Section 1.1."


Lists "inclusions." Inclusions are an SGML feature. Included elements can appear anywhere inside the element that includes them, even in places that aren't ordinarily valid. For example, Chapter includes IndexTerm. This means that within a Chapter, IndexTerm can appear inside Emphasis, for instance, even though the content model of Emphasis does not explicitly allow IndexTerms.


Lists "exclusions." Exclusions are an SGML feature. Excluded elements cannot appear anywhere inside the element that excludes them, even in places that are ordinarily valid. For example, Footnote excludes Fotnote. This means that a Footnote cannot appear inside a Para inside a Footnote, even though Footnote appears in the content model of Para.

Lists elements that are excluded from appearing at any level below the element described.


Provides a synopsis of the attributes on the element. For brevity, common attributes are described only once, in this introduction.

Tag Minimization

Indicates if start- or end-tags may be omitted. Tag omission is dependent on both the DTD and your SGML declaration. If a tag is described as ommissable here, it is ommissible if your declaration allows tag omission. The standard DocBook declaration does not.

Parameter Entities

Lists the parameter entities in which the element described appears. Parameter entities are important when you are customizing the DTD.


Describes the semantics of the element in detail.

Processing expectations

Summarizes specific formatting expectations of the element. Many processing expectations are influenced by attribute values. Be sure to consult the description of element attributes as well.

Future changes

Identifies changes that are scheduled for future versions of the DTD. These changes are highlighted because they involve some backward-incompatability that may make currently valid DocBook documents no longer valid under the new version.


Describes the semantics of each attribute in detail.

See Also

Lists similar or related elements.


Provides examples of proper usage for the element. Generally, the smallest example required to reasonably demonstrate the element is used. In many cases, a formatted version of the example is also shown.

All of the examples printed in the book use the SGML version of DocBook. The CD-ROM includes the full text of all of the examples.

Formatted examples are indicated using a vertical bar.

1.1. Understanding Content Models

Each element synopsis begins with a concise description of the elements it can contain. This description is in DTD "content model" syntax, with all parameter entities expanded.

Content models are the way that DTDs describe the name, number, and order of other elements that may be used inside an element. The primary feature of content model syntax is that it is concise, but this conciseness comes at the cost of legibility until you are familiar with the syntax.

There are six components to content model syntax: element names, keywords, repetitions, sequences, alternatives, and groups.

Element names

An element name in a content model indicates that an element of that type may (or must) occur at that position.

A content model of Para indicates that the element must contain a single paragraph.


There are two keywords that occur in the content models of DocBook elements: EMPTY, and #PCDATA.

A content model that consists of the single keyword EMPTY identifes an element as an empty element. Empty elements are not allowed to have any content. In order for the word "EMPTY" to have this special meaning, it must be the first and only word in the content model. The word "EMPTY" at any other place is treated as an element name.

The #PCDATA keyword indicates that text may occur at that position. The text may consist of entity references and any characters that are legal in the document character set. For XML documents, the document character set is always Unicode. In SGML the declaration can identify character sets and ranges that are allowed. DocBook SGML documents use the ISO Latin 1 character set.


An unadorned element name indicates that an element must occur exactly once at that position. A content model can also specify that an element may occur zero or more times, one or more times, or exactly zero or one time. This is accomplished by following the element name with one of the following characters: * for zero or more times, + for one or more times, or ? for exactly zero or one times.

A content model of Para+ indicates that the element must contain at least one paragraph and may contain many.


If element names in a content model are separated by commas, then they must occur in sequence.

A content model of Title, Para indicates that the element must contain a single title followed by a single paragraph.


If element names in a content model are separated by vertical bars (|), then they are alternatives. These are sometimes called "or groups" because they require the selection of one or another element.

A content model of Phrase | Para indicates that the element must contain either a single phrase or a single paragraph.

In SGML, there is another connector: the ampersand (&). The ampersand is a kind of combination of alternative and sequence, which means that all of the elements must occur, but they can occur in any order. DocBook does not have any content models that use the ampersand connector. XML does not allow it.


Finally, parenthesis may be used around part of a content model. A group formed this way can have repetition indicators and may occur as part of a sequence.

A content model of (Literal | Replaceable)+ indicates that either Literal or Replaceable must occur and they can be repeated (and mixed) any number of times.

1.1.1. Content models and validity

A parser uses the content models to determine if a given document is valid. In order for a document to be valid, the content of every element in the document must "match" the content model for that element.

In practical terms, match means that it must be possible to expand the content model until it exactly matches the sequence of elements in the document.

For example, consider the content model of the Epigraph element: Attribution?, (FormalPara | Para | SimPara)+. This indicates that the following document fragment is valid:

<para>Some text</para>

It is valid because the following expansion of the content model exactly matches the actual content: choose zero occurances of Attribution, choose the alternative Para from the group, and choose to let the "+" match once.

By the same token, this example is not valid because there is no expansion of the content model that can match it:

<para>Some text</para>
<attribution>John Doe</attribution>

There is one additional restriction on the matching ability of the parser: it is not allowed to "look ahead." This means that there are many useful content models that are ambiguous.

1.1.2. Ambiguity

Ambiguity is not allowed. The parser must always be able to choose exactly what to match based upon the next input token. Consider the following content model: Meta*, Title?, Meta*.

The intent is clear: to allow some meta-information and a single, optional Title. But this content model is ambiguous for the following reason: if the document content begins with a Meta element, it is impossible to tell if it matches the Meta before the Title or after without looking ahead.

Ambiguous content models are detected by the parser when it reads the DTD. It is not sufficient that your document simply be unambiguous; it must not be possible to construct any ambiguous document.

1.1.3. #PCDATA and repetition

The #PCDATA keyword can always match the empty string. This makes it impossible to force an element that may contain characters not to be empty. In other words, the following content model does not guarantee that the element is not empty: (#PCDATA)+.

In XML, the #PCDATA keyword is only allowed in optional, repeatable "or groups", and it must be the first member of the group.

2. Common Attributes

The following attributes occur on all elements. They are summarized here once for brevity and to make the additional attributes that occur on many elements stand out.






a. On a few elements, the ID is required, but on most it is not.


Arch designates the computer or chip architecture to which the element applies.


Conformance indicates standards conformance characteristics of the item contained in the element. These characteristics are application-specific. DocBook provides no defaults.


ID is an identifying string for the element. It must be unique at least within the document and must begin with a letter.


Lang should be a language code drawn from ISO 639 (perhaps extended with a country code drawn from ISO 3166, as en_US). Use it when you need to signal your application to change hyphenation and other display characteristics.


OS indicates the operating system to which the element is applicable.


Remap contains an element name or similar semantic identifier assigned to the content in a previous markup scheme.


Role contains a string used to classify or subclassify an element.

While Role is a common attribute in the sense that it occurs on almost all elements, it is not part of either of the common attributes parameter entities (%common.attrib; or %idreq.common.attrib;). It is parameterized differently because it is useful to be able to subclass Role independently on different elements.


Revision indicates the editorial revision to which the element belongs.


RevisionFlag indicates the revision status of element; the default is that the element hasn't been revised. RevisionFlag is intended only for simple revision management: to track the entire history of a document use a proper revision control system. Use RevisionFlag for indicating changes from one version to the next, no more.


UserLevel indicates the level of user experience to which element applies.


Vendor indicates the computer vendor to which the element applies.


XrefLabel holds text to be used when a cross reference (XRef) is made to the element.

3. Attribute Types

SGML offers a small selection of attribute types. (XML offers a subset of these.) For convenience, a brief description of each of these types is provided here:


A string of characters.


A number. Numbers must begin with a hyphen or digit and can include the decimal point.


A sequence of name characters (letters, digits, hyphens, and periods). This differs from a CDATA attribute because it cannot contain spaces, punctuation, or other non-name characters.


A sequence of one or more space-delimited NMTOKEN values.


A sequence of number characters (digits, hyphens, and periods). This differs from a NUMBER field because it is not required to begin with a digit or a hyphen.


An entity name. The value of an ENTITY attribute must be the name of a declared entity.


A name. A name must begin with a letter and can consist of letters, digits, hyphens, and periods.


A sequence of one or more space-delimited NAME values.


An ID. IDs are names that must be globally unique within the document. The ID attribute declares the ID.


An single ID. IDs are names that must be globally unique within the document. The value of an IDREF attribute must be the name of an ID attribute defined in the document.


A sequence of one or more space-delimited ID values.

Table of Contents
Abbrev An abbreviation, especially one followed by a period
Abstract A summary
Accel A graphical user interface (GUI) keyboard shortcut
Ackno Acknowledgements in an Article
Acronym An often pronounceable word made from the initial (or selected) letters of a name or phrase
Action A response to a user event
Address A real-world address, generally a postal address
Affiliation The institutional affiliation of an individual
Alt Text representation for a graphical element
Anchor A spot in the document
Answer An answer to a question posed in a QandASet
Appendix An appendix in a Book or Article
Application The name of a software program
Area A region defined for a Callout in a graphic or code example
AreaSet A set of related areas in a graphic or code example
AreaSpec A collection of regions in a graphic or code example
Arg An argument in a CmdSynopsis
ArtHeader Meta-information for an Article
Article An article
ArtPageNums The page numbers of an article as published
Attribution The source of a block quote or epigraph
AudioData Pointer to external audio data
AudioObject A wrapper for audio data and its associated meta-information
Author The name of an individual author
AuthorBlurb A short description or note about an author
AuthorGroup Wrapper for author information when a document has multiple authors or collabarators
AuthorInitials The initials or other short identifier for an author
BeginPage The location of a page break in a print version of the document
BiblioDiv A section of a Bibliography
BiblioEntry An entry in a Bibliography
Bibliography A bibliography
BiblioMisc Untyped bibliographic information
BiblioMixed An entry in a Bibliography
BiblioMSet A "cooked" container for related bibliographic information
BiblioSet A "raw" container for related bibliographic information
BlockQuote A quotation set off from the main text
Book A book
BookBiblio Meta-information about a book used in a bibliographical citation
BookInfo Meta-information for a Book
BridgeHead A free-floating heading
Callout A "called out" description of a marked Area
CalloutList A list of Callouts
Caption A caption
Caution A note of caution
Chapter A chapter, as of a book
Citation An inline bibliographic reference to another published work
CiteRefEntry A citation to a reference page
CiteTitle The title of a cited work
City The name of a city in an address
ClassName The name of a class, in the object-oriented programming sense
CmdSynopsis A syntax summary for a software command
CO The location of a callout embedded in text
Collab Identifies a collaborator
CollabName The name of a collaborator
Colophon Text at the back of a book describing facts about its production
colspec Specifications for a column in a table
Command The name of an executable program or other software command
Comment A comment intended for presentation in a draft manuscript
ComputerOutput Data, generally text, displayed or presented by a computer
ConfDates The dates of a conference for which a document was written
ConfGroup A wrapper for document meta-information about a conference
ConfNum An identifier, frequently numerical, associated with a conference for which a document was written
ConfSponsor The sponsor of a conference for which a document was written
ConfTitle The title of a conference for which a document was written
Constant A programming or system constant
ContractNum The contract number of a document
ContractSponsor The sponsor of a contract
Contrib A summary of the contributions made to a document by a credited source
Copyright Copyright information about a document
CorpAuthor A corporate author, as opposed to an individual
CorpName The name of a corporation
Country The name of a country
Database The name of a database, or part of a database
Date The date of publication or revision of a document
Dedication A wrapper for the dedication section of a book
DocInfo Meta-data for a book component
Edition The name or number of an edition of a document
Editor The name of the editor of a document
Email An email address
Emphasis Emphasized text
entry A cell in a table
entrytbl A subtable appearing in place of an Entry in a table
EnVar A software environment variable
Epigraph A short inscription at the beginning of a document or component
Equation A displayed mathematical equation
ErrorCode An error code
ErrorName An error message
ErrorType The classification of an error message
Example A formal example, with a title
Fax A fax number
Figure A formal figure, generally an illustration, with a title
Filename The name of a file
FirstName The first name of a person
FirstTerm The first occurrence of a term
Footnote A footnote
FootnoteRef A cross reference to a footnote (a footnote mark)
ForeignPhrase A word or phrase in a language other than the primary language of the document
FormalPara A paragraph with a title
FuncDef A function (subroutine) name and its return type
FuncParams Parameters for a function referenced through a function pointer in a synopsis
FuncPrototype The prototype of a function
FuncSynopsis The syntax summary for a function definition
FuncSynopsisInfo Information supplementing the FuncDefs of a FuncSynopsis
Function The name of a function or subroutine, as in a programming language
Glossary A glossary
GlossDef A definition in a GlossEntry
GlossDiv A division in a Glossary
GlossEntry An entry in a Glossary or GlossList
GlossList A wrapper for a set of GlossEntrys
GlossSee A cross-reference from one GlossEntry to another
GlossSeeAlso A cross-reference from one GlossEntry to another
GlossTerm A glossary term
Graphic A displayed graphical object (not an inline)
GraphicCO A graphic that contains callout areas
Group A group of elements in a CmdSynopsis
GUIButton The text on a button in a GUI
GUIIcon Graphic and/or text appearing as a icon in a GUI
GUILabel The text of a label in a GUI
GUIMenu The name of a menu in a GUI
GUIMenuItem The name of a terminal menu item in a GUI
GUISubmenu The name of a submenu in a GUI
Hardware A physical part of a computer system
Highlights A summary of the main points of the discussed component
Holder The name of the individual or organization that holds a copyright
Honorific The title of a person
ImageData Pointer to external image data
ImageObject A wrapper for image data and its associated meta-information
ImageObjectCO A wrapper for an image object with callouts
Important An admonition set off from the text
Index An index
IndexDiv A division in an index
IndexEntry An entry in an index
IndexTerm A wrapper for terms to be indexed
InformalEquation A displayed mathematical equation without a title
InformalExample A displayed example without a title
InformalFigure A untitled figure
InformalTable A table without a title
InlineEquation A mathematical equation or expression occurring inline
InlineGraphic An object containing or pointing to graphical data that will be rendered inline
InlineMediaObject An inline media object (video, audio, image, and so on)
Interface An element of a GUI
InterfaceDefinition The name of a formal specification of a GUI
InvPartNumber An inventory part number
ISBN The International Standard Book Number of a document
ISSN The International Standard Serial Number of a periodical
IssueNum The number of an issue of a journal
ItemizedList A list in which each entry is marked with a bullet or other dingbat
ITermSet A set of index terms in the meta-information of a document
JobTitle The title of an individual in an organization
KeyCap The text printed on a key on a keyboard
KeyCode The internal, frequently numeric, identifier for a key on a keyboard
KeyCombo A combination of input actions
KeySym The symbolic name of a key on a keyboard
Keyword One of a set of keywords describing the content of a document
KeywordSet A set of keywords describing the content of a document
Label A label on a Question or Answer
LegalNotice A statement of legal obligations or requirements
Lineage The portion of a person's name indicating a relationship to ancestors
LineAnnotation A comment on a line in a verbatim listing
Link A hypertext link
ListItem A wrapper for the elements of a list item
Literal Inline text that is some literal value
LiteralLayout A block of text in which line breaks and white space are to be reproduced faithfully
LoT A list of the titles of formal objects (as tables or figures) in a document
LoTentry An entry in a list of titles
ManVolNum A reference volume number
Markup A string of formatting markup in text that is to be represented literally
MediaLabel A name that identifies the physical medium on which some information resides
MediaObject A displayed media object (video, audio, image, etc.)
MediaObjectCO A media object that contains callouts
Member An element of a simple list
MenuChoice A selection or series of selections from a menu
ModeSpec Application-specific information necessary for the completion of an OLink
MouseButton The conventional name of a mouse button
Msg A message in a message set
MsgAud The audience to which a message in a message set is relevant
MsgEntry A wrapper for an entry in a message set
MsgExplan Explanatory material relating to a message in a message set
MsgInfo Information about a message in a message set
MsgLevel The level of importance or severity of a message in a message set
MsgMain The primary component of a message in a message set
MsgOrig The origin of a message in a message set
MsgRel A related component of a message in a message set
MsgSet A detailed set of messages, usually error messages
MsgSub A subcomponent of a message in a message set
MsgText The actual text of a message component in a message set
Note A message set off from the text
ObjectInfo Meta-information for an object
OLink A link that addresses its target indirectly, through an entity
Option An option for a software command
Optional Optional information
OrderedList A list in which each entry is marked with a sequentially incremented label
OrgDiv A division of an organization
OrgName The name of an organization other than a corporation
OtherAddr Uncategorized information in address
OtherCredit A person or entity, other than an author or editor, credited in a document
OtherName A component of a persons name that is not a first name, surname, or lineage
PageNums The numbers of the pages in a book, for use in a bibliographic entry
Para A paragraph
ParamDef Information about a function parameter in a programming language
Parameter A value or a symbolic reference to a value
Part A division in a book
PartIntro An introduction to the contents of a part
Phone A telephone number
Phrase A span of text
POB A post office box in an address
Postcode A postal code in an address
Preface Introductory matter preceding the first chapter of a book
Primary The primary word or phrase under which an index term should be sorted
PrimaryIE A primary term in an index entry, not in the text
PrintHistory The printing history of a document
Procedure A list of operations to be performed in a well-defined sequence
ProductName The formal name of a product
ProductNumber A number assigned to a product
ProgramListing A literal listing of all or part of a program
ProgramListingCO A program listing with associated areas used in callouts
Prompt A character or string indicating the start of an input field in a computer display
Property A unit of data associated with some part of a computer system
PubDate The date of publication of a document
Publisher The publisher of a document
PublisherName The name of the publisher of a document
PubsNumber A number assigned to a publication other than an ISBN or ISSN or inventory part number
QandADiv A titled division in a QandASet
QandAEntry A question/answer set within a QandASet
QandASet A question-and-answer set
Question A question in a QandASet
Quote An inline quotation
RefClass The scope or other indication of applicability of a reference entry
RefDescriptor A description of the topic of a reference page
RefEntry A reference page (originally a UNIX man-style reference page)
RefEntryTitle The title of a reference page
Reference A collection of reference entries
RefMeta Meta-information for a reference entry
RefMiscInfo Meta-information for a reference entry other than the title and volume number
RefName The name of (one of) the subject(s) of a reference page
RefNameDiv The name, purpose, and classification of a reference page
RefPurpose A short (one sentence) synopsis of the topic of a reference page
RefSect1 A major subsection of a reference entry
RefSect1Info Meta-information for a RefSect1
RefSect2 A subsection of a RefSect1
RefSect2Info Meta-information for a RefSect2
RefSect3 A subsection of a RefSect2
RefSect3Info Meta-information for a RefSect3
RefSynopsisDiv A syntactic synopsis of the subject of the reference page
RefSynopsisDivInfo Meta-information for a RefSynopsisDiv
ReleaseInfo Information about a particular release of a document
Replaceable Content that may or must be replaced by the user
ReturnValue The value returned by a function
RevHistory A history of the revisions to a document
Revision An entry describing a single revision in the history of the revisions to a document
RevNumber A document revision number
RevRemark A description of a revision to a document
row A row in a table
SBR An explicit line break in a command synopsis
Screen Text that a user sees or might see on a computer screen
ScreenCO A screen with associated areas used in callouts
ScreenInfo Information about how a screen shot was produced
ScreenShot A representation of what the user sees or might see on a computer screen
Secondary A secondary word or phrase in an index term
SecondaryIE A secondary term in an index entry, rather than in the text
Sect1 A top-level section of document
Sect1Info Meta-information for a Sect1
Sect2 A subsection within a Sect1
Sect2Info Meta-information for a Sect2
Sect3 A subsection within a Sect2
Sect3Info Meta-information for a Sect3
Sect4 A subsection within a Sect3
Sect4Info Meta-information for a Sect4
Sect5 A subsection within a Sect4
Sect5Info Meta-information for a Sect5
Section A recursive section
SectionInfo Meta-information for a recursive section
See Part of an index term directing the reader instead to another entry in the index
SeeAlso Part of an index term directing the reader also to another entry in the index
SeeAlsoIE A "See also" entry in an index, rather than in the text
SeeIE A "See" entry in an index, rather than in the text
Seg An element of a list item in a segmented list
SegListItem A list item in a segmented list
SegmentedList A segmented list, a list of sets of elements
SegTitle The title of an element of a list item in a segmented list
SeriesInfo Information about the publication series of which a book is a part
SeriesVolNums Numbers of the volumes in a series of books
Set A collection of books
SetIndex An index to a set of books
SetInfo Meta-information for a Set
SGMLTag A component of SGML markup
ShortAffil A brief description of an affiliation
Shortcut A key combination for an action that is also accessible through a menu
Sidebar A portion of a document that is isolated from the main narrative flow
SimPara A paragraph that contains only text and inline markup, no block elements
SimpleList An undecorated list of single words or short phrases
SimpleSect A section of a document with no subdivisions
spanspec Formatting information for a spanned column in a table
State A state or province in an address
Step A unit of action in a procedure
Street A street address in an address
StructField A field in a structure (in the programming language sense)
StructName The name of a structure (in the programming language sense)
Subject One of a group of terms describing the subject matter of a document
SubjectSet A set of terms describing the subject matter of a document
SubjectTerm A term in a group of terms describing the subject matter of a document
Subscript A subscript (as in H2O, the molecular formula for water)
SubSteps A wrapper for steps that occur within steps in a procedure
Subtitle The subtitle of a document
Superscript A superscript (as in x2, the mathematical notation for x multiplied by itself)
Surname A family name; in western cultures the "last name"
Symbol A name that is replaced by a value before processing
SynopFragment A portion of a CmdSynopsis broken out from the main body of the synopsis
SynopFragmentRef A reference to a fragment of a command synopsis
Synopsis A general-purpose element for representing the syntax of commands or functions
SystemItem A system-related item or term
Table A formal table in a document
tbody A wrapper for the rows of a table or informal table
Term The word or phrase being defined or described in a variable list
Tertiary A tertiary word or phrase in an index term
TertiaryIE A tertiary term in an index entry, rather than in the text
TextObject A wrapper for a text description of an object and its associated meta-information
tfoot A table footer consisting of one or more rows
tgroup A wrapper for the main content of a table, or part of a table
thead A table header consisting of one or more rows
Tip A suggestion to the user, set off from the text
Title The text of the title of a section of a document or of a formal block-level element
TitleAbbrev The abbreviation of a Title
ToC A table of contents
ToCback An entry in a table of contents for a back matter component
ToCchap An entry in a table of contents for a component in the body of a document
ToCentry A component title in a table of contents
ToCfront An entry in a table of contents for a front matter component
ToClevel1 A top-level entry within a table of contents entry for a chapter-like component
ToClevel2 A second-level entry within a table of contents entry for a chapter-like component
ToClevel3 A third-level entry within a table of contents entry for a chapter-like component
ToClevel4 A fourth-level entry within a table of contents entry for a chapter-like component
ToClevel5 A fifth-level entry within a table of contents entry for a chapter-like component
ToCpart An entry in a table of contents for a part of a book
Token A unit of information
Trademark A trademark
Type The classification of a value
ULink A link that addresses its target by means of a URL (Uniform Resource Locator)
UserInput Data entered by the user
VarArgs An empty element in a function synopsis indicating a variable number of arguments
VariableList A list in which each entry is composed of a set of one or more terms and an associated description
VarListEntry A wrapper for a set of terms and the associated description in a variable list
VarName The name of a variable
VideoData Pointer to external video data
VideoObject A wrapper for video data and its associated meta-information
Void An empty element in a function synopsis indicating that the function in question takes no arguments
VolumeNum The volume number of a document in a set (as of books in a set or articles in a journal)
Warning An admonition set off from the text
WordAsWord A word meant specifically as a word and not representing anything else
XRef A cross reference to another part of the document
Year The year of publication of a document

Copyright © 1999 O'Reilly & Associates, Inc. All rights reserved.