I. DocBook Element Reference

Table of Contents
  • abbrev — An abbreviation, especially one followed by a period
  • abstract — A summary
  • acronym — An often pronounceable word made from the initial (or selected) letters of a name or phrase
  • affiliation — The institutional affiliation of an individual
  • alt — A text-only annotation, often used for accessibility
  • appendix — An appendix in a book or article
  • 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
  • authorgroup — Wrapper for author information when a document has multiple authors or collaborators
  • authorinitials — The initials or other short identifier for an author
  • bibliodiv — A section of a bibliography
  • bibliography — A bibliography
  • bibliomisc — Untyped bibliographic information
  • bibliomixed — A cooked entry in a bibliography
  • bibliomset — A cooked container for related bibliographic information
  • blockquote — A quotation set off from the main text
  • caption (db.caption) — A caption
  • caption (db.html.caption) — An HTML table caption
  • citetitle — The title of a cited work
  • col — Specifications for a column in an HTML table
  • colgroup — A group of columns in an HTML table
  • colspec — Specifications for a column in a table
  • command — The name of an executable program or other software command
  • computeroutput — Data, generally text, displayed or presented by a computer
  • config — A website configuration parameterV5.0 Website
  • copyright — Copyright information about a document
  • date — The date of publication or revision of a document
  • 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
  • epigraph — A short inscription at the beginning of a document or component
  • example — A formal example, with a title
  • figure — A formal figure, generally an illustration, with a title
  • filename — The name of a file
  • firstname — A given name of a person
  • footnote — A footnote
  • footnoteref — A cross reference to a footnote (a footnote mark)
  • givenname — The given name of a personV5.1
  • head — The head in a webpageV5.0 Website
  • holder — The name of the individual or organization that holds a copyright
  • honorific — The title of a person
  • html:button — A button in an HTML form
  • html:fieldset — A fieldset element in an HTML form
  • html:form — An HTML form
  • html:input — An input element in an HTML form
  • html:label — A label in an HTML form
  • html:legend — A legend in an HTML form fieldset
  • html:option — An option element in an HTML form
  • html:select — A select element in an HTML form
  • html:textarea — A textarea element in an HTML form
  • imagedata — Pointer to external image data
  • imageobject — A wrapper for image data and its associated meta-information
  • info (db.info) — A wrapper for information about a component or other blockV5.0
  • info (db.titleforbidden.info) — A wrapper for information about a component or other block without a titleV5.0
  • info (db.titleonly.info) — A wrapper for information about a component or other block with only a titleV5.0
  • info (db.titleonlyreq.info) — A wrapper for information about a component or other block with only a required titleV5.0
  • info (db.titlereq.info) — A wrapper for information about a component or other block with a required titleV5.0
  • informaltable (db.html.informaltable) — An HTML table without a title
  • informaltable (db.cals.informaltable) — A table without a title
  • inlinemediaobject — An inline media object (video, audio, image, and so on)
  • issuenum — The number of an issue of a journal
  • itemizedlist — A list in which each entry is marked with a bullet or other dingbat
  • keyword — One of a set of keywords describing the content of a document
  • keywords — The keywords for a webpageV5.0 Website
  • keywordset — A set of keywords describing the content of a document
  • 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 (db.link) — A hypertext link
  • headlink — A link in the head of a webpageV5.0 Website
  • 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
  • mediaobject — A displayed media object (video, audio, image, etc.)
  • meta — The meta in a webpage headV5.0 Website
  • multimediaparam — Application specific parameters for a media playerV5.1
  • note — A message set off from the text
  • option — An option for a software command
  • orderedlist — A list in which each entry is marked with a sequentially incremented label
  • orgname — The name of an organization
  • othercredit — A person or entity, other than an author or editor, credited in a document
  • othername — A component of a person's name that is not a first name, surname, or lineage
  • para — A paragraph
  • personblurb — A short description or note about a person
  • personname — The personal name of an individual
  • phrase (db._phrase) — A limited span of text
  • phrase (db.phrase) — A span of text
  • programlisting — A literal listing of all or part of a program
  • pubdate — The date of publication of a document
  • publishername — The name of the publisher of a document
  • quote — An inline quotation
  • rddl:resource — V5.0 Website
  • releaseinfo — Information about a particular release of a document
  • replaceable — Content that may or must be replaced by the user
  • revdescription — A extended description of a revision to a document
  • 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 (db.entrytbl.row) — A row in a table
  • row (db.row) — A row in a table
  • script — A script in the head of a webpageV5.0 Website
  • section — A recursive section
  • sidebar — A portion of a document that is isolated from the main narrative flow
  • spanspec — Formatting information for a spanned column in a table
  • style — A style section in the head of a webpageV5.0 Website
  • 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 H₂O, the molecular formula for water)
  • subtitle — The subtitle of a document
  • summary — A short summary of a webpageV5.0 Website
  • superscript — A superscript (as in x², the mathematical notation for x multiplied by itself)
  • surname — An inherited or family name; in western cultures the last name
  • systemitem — A system-related item or term
  • table (db.html.table) — A formal (captioned) HTML table in a document
  • table (db.cals.table) — A formal table in a document
  • tbody (db.cals.entrytbl.tbody) — A wrapper for the rows of a table or informal table
  • tbody (db.html.tbody) — A wrapper for the rows of an HTML table or informal HTML table
  • tbody (db.cals.tbody) — A wrapper for the rows of a table or informal table
  • td — A table entry in an HTML table
  • term — The word or phrase being defined or described in a variable list
  • textdata — Pointer to external text data
  • textobject — A wrapper for a text description of an object and its associated meta-information
  • tfoot (db.html.tfoot) — A table footer consisting of one or more rows in an HTML table
  • tfoot (db.cals.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
  • th — A table header entry in an HTML table
  • thead (db.cals.entrytbl.thead) — A table header consisting of one or more rows
  • thead (db.html.thead) — A table header consisting of one or more rows in an HTML table
  • thead (db.cals.thead) — A table header consisting of one or more rows
  • 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
  • tr — A row in an HTML table
  • trademark — A trademark
  • userinput — Data entered by the user
  • 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
  • videodata — Pointer to external video data
  • videoobject — A wrapper for video data and its associated meta-information
  • volumenum — The volume number of a document in a set (as of books in a set or articles in a journal)
  • webpage — A page in a websiteV5.0 Website
  • webtoc — Marks the location of a TOC in a webpageV5.0 Website
  • xref — A cross reference to another part of the document
  • year — The year of publication of a document

This reference describes every element in DocBook V5.0.

1. 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 Section 1.1, “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 incompatibility 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 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 epigraph:

epigraph ::= (info?db.titleforbidden.info, attribution?,(literallayout | Paragraph elements)+)

Does the following example match that content model?

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

Yes, it is valid because the following expansion of the content model exactly matches the actual content: choose zero occurrences of info, choose zero occurrences of attribution, choose the alternative 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:

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

2. Common Attributes

There are many common attributes that occur on every DocBook element. They are summarized here for brevity and to make the additional attributes that occur on many elements stand out.

NameType
revisionflag
Enumeration:
changed
added
deleted
off
roletext
versiontext
xml:basetext
xml:idID
xml:langtext
revisionflag

.

changed

added

deleted

off

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.

version

.

xml:base

.

xml:id

.

xml:lang

.

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 vendor.

NameType

The names of the effectivity attributes are suggestive of several classes of common effectivity information. The semantically neutral 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.

2.2. Common RDFa Lite Attributes

The RDFa Lite attributes incorporate support for RDFa into DocBook.

NameType

See RDFa Lite 1.1 for more details about the RDFa Lite attributes.

3. 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.

NameType
linkend/linkendsIDREF/IDREFS
xlink:actuate
Enumeration:
onLoad
onRequest
other
none
xlink:arcroleanyURI
xlink:hrefanyURI
xlink:roleanyURI
xlink:show
Enumeration:
new
replace
embed
other
none
xlink:titletext
xlink:typetext
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.