1. Organization of Reference Pages
The description of each element in this reference is divided into the following sections:
- Content Model
Describes the content model of the element, the mixture of things that it can contain. See Section 1.1, “Understanding Content Models”.
- Additional Constraints
Provides a synopsis of any additional constraints on the element. These constraints are expressed using Schematron in the RELAX NG grammar.
- Processing expectations
- Future changes
Identifies changes that are scheduled for future versions of the schema. These changes are highlighted because they involve some backward incompatibility that may make currently valid DocBook documents no longer valid under the new version.
- See Also
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 in the book are valid according to the RELAX NG grammar.
Formatted examples are indicated using a vertical bar.
1.1. 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.
1.1.1. Content models and validity
A validator 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
Does the following example “match” that content model?
1 <epigraph> 2 <para>Some text</para> </epigraph>
Yes, it is valid because the following expansion of the
content model exactly matches the actual content: choose zero
info, choose zero occurrences of
attribution, choose the
para from the
“Paragraph elements” 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:
1 <epigraph> 2 <para>Some text</para> <attribution>John Doe</attribution> 4 </epigraph>
2. Common Attributes
Identifies one or more annotations that apply to this element.
Identifies the direction of text in an element.
Provides the name or similar semantic identifier assigned to the content in some previous markup scheme.
Identifies the revision status of the element.
The element has been changed.
The element is new (has been added to the document).
The element has been deleted.
Explicitly turns off revision markup for this element.
Provides additional, user-specified classification for an element.
roleis 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
roleindependently on different elements.
Specifies the DocBook version of the element and its descendants.
Specifies the base URI of the element and its descendants.
Identifies the unique ID value of the element.
Specifies the natural language of the element and its descendants.
Provides the text that is to be generated for a cross reference to the element.
2.1. Common Effectivity Attributes
The common attributes include a collection of “effectivity attributes.” These attributes are available for authors to identify to whom a particular element applies. Effectivity attributes are often used for profiling: building documents that contain information only relevant to a particular audience.
For example, a section might be identified as available only to
readers with a “top-secret”
security clearance or a paragraph might be
identified as affecting only users running the implementation provided
by a particular
Designates the computer or chip architecture to which the element applies.
Designates the intended audience to which the element applies, for example, system administrators, programmers, or new users..
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. The
conditionattribute is a general-purpose effectivity attribute with no specified semantics.
conditionattribute provides a standard place for application-specific effectivity.
Indicates standards conformance characteristics of the element.
These characteristics are application-specific; DocBook provides no default semantics.
Indicates the operating system to which the element is applicable.
Indicates the editorial revision to which the element belongs.
Indicates something about the security level associated with the element to which it applies.
Indicates the level of user experience for which the element applies.
Indicates the computer vendor to which the element applies..
Indicates the word size (width in bits) of the computer architecture to which the element applies.
The names of the effectivity attributes are suggestive of
several classes of common effectivity information. The semantically
condition attribute was
added to give authors a place to put values that don’t fit neatly into
one of the other alternatives.
In authoring environments where many different kinds of effectivity information are required, it’s not uncommon to see local extensions that add new attributes. It’s also not uncommon to see attributes used without regard to the class of information suggested by the name.