    | DocBook: The Definitive Guide 0.0.12 for DocBook V5.0b1 (Alpha) |
| | DocBook: The Definitive Guide 0.0.12 for DocBook V5.0b1 (Alpha) |
This reference describes every element in the DocBook schema.
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 varies according to the nature of the element described, but may include any or all of the following sections:
Describes the content model of the element, the mixture of things that it can contain. See the section called “Understanding Content Models”.
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.
Provides a synopsis of any additional constraints on the element. These constraints are expressed using Schematron in the RELAX NG grammar.
Describes the semantics of the element.
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.
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.
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.
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:
Exactly one selection must be taken from the list.
Like “one of” but may be omitted entirely.
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.
Like “sequence of” but may be omitted entirely.
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.
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.
Like “one or more of” but may be omitted entirely.
All of the members of the list must be selected exactly once, but they can be selected in any order.
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.
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:
info? (db.titleforbidden.info)attribution?<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>
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 | Default | |||||
|---|---|---|---|---|---|---|---|
arch | text | None | |||||
condition | text | None | |||||
conformance | text | None | |||||
dir |
| None | |||||
os | text | None | |||||
remap | text | None | |||||
revision | text | None | |||||
revisionflag |
| None | |||||
role | text | None | |||||
security | text | None | |||||
userlevel | text | None | |||||
vendor | text | None | |||||
version | text | None | |||||
wordsize | text | None | |||||
xreflabel | text | None | |||||
xml:base | text | None | |||||
xml:id | ID | None/Required[a] | |||||
xml:lang | text | None | |||||
[a] On a
few elements, the | |||||||
FIXME: correct the following list
Arch
Arch designates the
computer or chip architecture to which the element applies.
Condition
Condition is a general-purpose
effectivity attribute with no specified semantics. 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.
The Condition attribute
provides a standard place for application-specific effectivity.
Conformance
Conformance indicates
standards conformance characteristics of the item contained in the
element. These characteristics are application-specific. DocBook
provides no defaults.
ID
ID is an identifying string
for the element. It must be unique at least within the document and
must begin with a letter.
Lang
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
OS indicates the operating
system to which the element is applicable.
Remap
Remap contains an element
name or similar semantic identifier assigned to the content in a
previous markup scheme.
Role
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
Revision indicates the
editorial revision to which the element belongs.
RevisionFlag
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.
Security
Security identifies something about
the security level associated with the element to which it applies.
UserLevel
UserLevel indicates the
level of user experience to which element applies.
Vendor
Vendor indicates the
computer vendor to which the element applies.
XrefLabel
XrefLabel holds text to be
used when a cross reference (XRef) is made to the
element.
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 | Default | |||||
|---|---|---|---|---|---|---|---|
linkend | IDREF | None | |||||
xlink:href | text | None | |||||
xlink:type | “simple” | None | |||||
xlink:role | anyURI | None | |||||
xlink:arcrole | anyURI | None | |||||
xlink:title | text | None | |||||
xlink:show |
| None | |||||
xlink:actuate |
| None |
FIXME: add a description list
| | | |
| Part II. Reference | | abbrev |