DocBook Element Reference

This reference describes every element in the DocBook schema.

Organization of Reference Pages

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

Synopsis

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

Content Model

Describes the content model of the element, the mixture of things that it can contain. See the section called “Understanding Content Models”.

Attributes

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

Additional Constraints

Provides a synopsis of any additional constraints on the element. These constraints are expressed using Schematron in the RELAX NG grammar.

Description

Describes the semantics of the element.

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 schema. These changes are highlighted because they involve some backward-incompatability that may make currently valid DocBook documents no longer valid under the new version.

Attributes

Describes the semantics of each attribute.

See Also

Lists similar or related elements.

Examples

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 are valid according to the RELAX NG grammar.

Formatted examples are indicated using a vertical bar.

Understanding Content Models

Each element synopsis begins with a description of its content model. Content models are the way that grammars describe the name, number, and order of other elements that may be used inside an element. This description is presented as a series of nested lists. The rules of RELAX NG are considerably more powerful than the rules of DTDs and I've seen no obvious way to expose them. Suggestions welcome.

Each level of list is introduced by a description of how elements are selected from it:

One of:: Exactly one selection must be taken from the list.
Optionally one of:: Like “one of” but may be omitted entirely.
Sequence of:: One selection must be made for each member of the list and those selections must be presented in the order they appear in the list.
Optional sequence of:: Like “sequence of” but may be omitted entirely.
Zero or more of:: Any number of selections, including none, can be made from the list. Selections can be made in any order, without restriction on order or number of occurrences.
One or more of:: Any number of selections can be made from the list. Selections can be made in any order, without restriction on order or number of occurrences except that at least one must be selected.
Optional one or more of:: Like “one or more of” but may be omitted entirely.
Interleave of:: All of the members of the list must be selected exactly once, but they can be selected in any order.
Optional interleave of:: Like “interleave of” but may be omitted entirely.

Individual elements in the list may be followed by an occurrence indicator. If the indicator is “?” the element is optional. Note that this can have an effect on the meaning of the list as a whole. For example, a sequence that consists of only optional elements may have none. This differs, in subtle and unimportant ways, from an optional sequence.

Some of the lists, especially ones that would otherwise be quite long, are subdivided into groups. For example:

Sequence of:
- info? (db.titleforbidden.info)
- attribution?
- One or more of:
  - literallayout
  - Paragraph elements
    
    anchor
    
    formalpara
    
    para
    
    simpara

This extra levels of list (e.g., Paragraph elements) are just a convenience for readers, they don't have any effect on the content model. An epigraph can contain one or more of “literallayout”, “anchor”, “formalpara”, “para”, or “simpara”.

In online versions of this document, rendered with a user agent that supports JavaScript, these lists can be opened and closed dynamically, or removed altogether.

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, above, and this example:

<epigraph>
<para>Some text</para>
</epigraph>

It is valid because the following expansion of the content model exactly matches the actual content: choose zero occurrences of info, zero occurrences of attribution, choose the alternative para from the choice, and choose to let the “one or more” match once.

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

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

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.

Name Type

annotations text

arch text

audience text

condition text

conformance text

dir

Enumeration:

ltr

rtl

lro

rlo

os text

remap text

revision text

revisionflag

Enumeration:

changed

added

deleted

off

role text

security text

userlevel text

vendor text

version text

wordsize text

xml:base anyURI

xml:id ID

xml:lang text

xreflabel text

annotations

Identifies one or more annotations that apply to this element.

arch

Designates the computer or chip architecture to which the element applies.

audience

Designates the intended audience to which the element applies, for example, system administrators, programmers, or new users..

condition

provides a standard place for application-specific effectivity.

Many DocBook users observed that in order to add an effectivity condition that was unique to their environment required “abusing” the semantics of one of the existing attributes, or adding their own, making their customization an extension rather than a subset. Thecondition attribute is a general-purpose effectivity attribute with no specified semantics.

Thecondition attribute provides a standard place for application-specific effectivity.

conformance

Indicates standards conformance characteristics of the element.

These characteristics are application-specific; DocBook provides no default semantics.

dir

Identifies the direction of text in an element.

ltr: Left-to-right text
rtl: Right-to-left text
lro: Left-to-right override
rlo: Right-to-left override

os

Indicates the operating system to which the element is applicable.

remap

Provides the name or similar semantic identifier assigned to the content in some previous markup scheme.

revision

Indicates the editorial revision to which the element belongs.

revisionflag

Identifies the revision status of the element.

changed: The element has been changed.
added: The element is new (has been added to the document).
deleted: The element has been deleted.
off: Explicitly turns off revision markup for this element.

role

Provides additional, user-specified classification for an element.

While role is a common attribute in the sense that it occurs on all DocBook elements, customizers will find that it is not part of any of the “common attribute” patterns. It is parameterized differently because it is useful to be able to subclass role independently on different elements.

security

Indicates something about the security level associated with the element to which it applies.

userlevel

Indicates the level of user experience for which the element applies.

vendor

Indicates the computer vendor to which the element applies..

version

Specifies the DocBook version of the element and its descendants.

wordsize

Indicates the word size (width in bits) of the computer architecture to which the element applies.

xml:base

Specifies the base URI of the element and its descendants.

xml:id

Identifies the unique ID value of the element.

xml:lang

Specifies the natural language of the element and its descendants.

xreflabel

Provides the text that is to be generated for a cross reference to the element.

Common Linking Attributes

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

Name Type

linkend/linkends IDREF/IDREFS

xlink:actuate

Enumeration:

onLoad

onRequest

other

none

xlink:arcrole anyURI

xlink:href anyURI

xlink:role anyURI

xlink:show

Enumeration:

new

replace

embed

other

none

xlink:title text

xlink:type text

linkend/linkends

Points to an internal link target by identifying the value of its xml:id attribute.

xlink:actuate

Identifies the XLink actuate behavior of the link.

onLoad: An application should traverse to the ending resource immediately on loading the starting resource.
onRequest: An application should traverse from the starting resource to the ending resource only on a post-loading event triggered for the purpose of traversal.
other: The behavior of an application traversing to the ending resource is unconstrained by this specification. The application should look for other markup present in the link to determine the appropriate behavior.
none: The behavior of an application traversing to the ending resource is unconstrained by this specification. No other markup is present to help the application determine the appropriate behavior.

xlink:arcrole

Identifies the XLink arcrole of the link.

xlink:href

Identifies a link target with a URI.

xlink:role

Identifies the XLink role of the link.

DocBook uses the XLink role value http://docbook.org/xlink/role/olink to identify linking elements with OLink semantics. That means the part of xlink:href before the number sign (#) is to be interpreted as equivalent to the olink targetdoc attribute value, and the part after the number sign as the olink targetptr attribute value.

xlink:show

Identifies the XLink show behavior of the link.

new: An application traversing to the ending resource should load it in a new window, frame, pane, or other relevant presentation context.
replace: An application traversing to the ending resource should load the resource in the same window, frame, pane, or other relevant presentation context in which the starting resource was loaded.
embed: An application traversing to the ending resource should load its presentation in place of the presentation of the starting resource.
other: The behavior of an application traversing to the ending resource is unconstrained by XLink. The application should look for other markup present in the link to determine the appropriate behavior.
none: The behavior of an application traversing to the ending resource is unconstrained by this specification. No other markup is present to help the application determine the appropriate behavior.

xlink:title

Identifies the XLink title of the link.

xlink:type

Identifies the XLink link type.


Part II. Reference		abbrev