Logical Divisions: The Categories of Elements in DocBook

DocBook elements can be divided broadly into these categories:

Sets
Books
Divisions, which divide books into parts
Components, which divide books or divisions into chapters
Sections, which subdivide components
Meta-information elements
Block elements
Inline elements

In the rest of this section, we'll describe briefly the elements that make up these categories. This section is designed to give you an overview. It is not an exhaustive list of every element in DocBook.

For more information about any specific element and the elements that it may contain, consult the reference page for the element in question.

Sets

A Set contains two or more Books. It's the hierarchical top of DocBook. You use the Set tag, for example, for a series of books on a single subject that you want to access and maintain as a single unit, such as the manuals for an airplane engine or the documentation for a programming language.

Books

A Book is probably the most common top-level element in a document. The DocBook definition of a book is very loose and general. Given the variety of books authored with DocBook and the number of different conventions for book organization used in countries around the world, attempting to impose a strict ordering of elements can make the content model extremely complex. But DocBook gives you free reign. It's very reasonable to use a local customization layer to impose a more strict ordering for your applications.

Books consist of a mixture of the following elements:

Dedication

Dedication pages almost always occur at the front of a book.

Navigational Components

There are a few component-level elements designed for navigation: ToC, for Tables of Contents; LoT, for Lists of Titles (for lists of figures, tables, examples, and so on); and Index, for indexes.

Divisions

Divisions are the first hierarchical level below Book. They contain Parts and References. Parts, in turn, contain components. References contain RefEntrys. These are discussed more thoroughly in the Section called Making a Reference Page”.

Books can contain components directly and are not required to contain divisions.

Components

These are the chapter-like elements of a Book.

Components

Components are the chapter-like elements of a Book or Part: Preface, Chapter, Appendix, Glossary, and Bibliography. Articles can also occur at the component level. We describe Articles in more detail in the section titled the Section called Making an Article”. Components generally contain block elements and/or sections, and some can contain navigational components and RefEntrys.

Sections

There are several flavors of sectioning elements in DocBook:

Sect1Sect5 elements

The Sect1Sect5 elements are the most common sectioning elements. They can occur in most component-level elements. These numbered section elements must be properly nested (Sect2s can only occur inside Sect1s, Sect3s can only occur inside Sect2s, and so on). There are five levels of numbered sections.

Section element

The Section element, introduced in DocBook V3.1, is an alternative to numbered sections. Sections are recursive, meaning that you can nest them to any depth desired.

SimpleSect element

In addition to numbered sections, there's the SimpleSect element. It is a terminal section that can occur at any level, but it cannot have any other sectioning element nested within it.

BridgeHead

A BridgeHead provides a section title without any containing section.

RefSect1RefSect3 elements

These elements, which occur only in RefEntrys, are analogous to the numbered section elements in components. There are only three levels of numbered section elements in a RefEntry.

GlossDiv, BiblioDiv, and IndexDiv

Glossarys, Bibliographys, and Indexes can be broken into top-level divisions, but not sections. Unlike sections, these elements do not nest.

Meta-Information

All of the elements at the section level and above include a wrapper for meta-information about the content. See, for example, BookInfo.

The meta-information wrapper is designed to contain bibliographic information about the content (Author, Title, Publisher, and so on) as well as other meta-information such as revision histories, keyword sets, and index terms.

Block Elements

The block elements occur immediately below the component and sectioning elements. These are the (roughly) paragraph-level elements in DocBook. They can be divided into a number of categories: lists, admonitions, line-specific environments, synopses of several sorts, tables, figures, examples, and a dozen or more miscellaneous elements.

Lists

There are seven list elements in DocBook:

CalloutList

A list of CallOuts and their descriptions. CallOuts are marks, frequently numbered and typically on a graphic or verbatim environment, that are described in a CalloutList, outside the element in which they occur.

GlossList

A list of glossary terms and their definitions.

ItemizedList

An unordered (bulleted) list. There are attributes to control the marks used.

OrderedList

A numbered list. There are attributes to control the type of enumeration.

SegmentedList

A repeating set of named items. For example, a list of states and their capitals might be represented as a SegmentedList.

SimpleList

An unadorned list of items. SimpleLists can be inline or arranged in columns.

VariableList

A list of terms and definitions or descriptions. (This list of list types is a VariableList.)

Admonitions

There are five types of admonitions in DocBook: Caution, Important, Note, Tip, and Warning.

All of the admonitions have the same structure: an optional Title followed by paragraph-level elements. The DocBook DTD does not impose any specific semantics on the individual admonitions. For example, DocBook does not mandate that Warnings be reserved for cases where bodily harm can result.

Line-specific environments

These environments preserve whitespace and line breaks in the source text. DocBook does not provide the equivalent of HTML's BR tag, so there's no way to interject a line break into normal running text.

Address

The Address element is intended for postal addresses. In addition to being line-specific, Address contains additional elements suitable for marking up names and addresses.

LiteralLayout

A LiteralLayout does not have any semantic association beyond the preservation of whitespace and line breaks. In particular, while ProgramListing and Screen are frequently presented in a fixed-width font, a change of fonts is not necessarily implied by LiteralLayout .

ProgramListing

A ProgramListing is a verbatim environment, usually presented in Courier or some other fixed-width font, for program sources, code fragments, and similar listings.

Screen

A Screen is a verbatim or literal environment for text screen-captures, other fragments of an ASCII display, and similar things. Screen is also a frequent catch-all for any verbatim text.

ScreenShot

ScreenShot is actually a wrapper for a Graphic intended for screen shots of a GUI for example.

Synopsis

A Synopsis is a verbatim environment for command and function synopsis.

Examples, figures, and tables

Examples, Figures, and Tables are common block-level elements: Example, InformalExample, Figure, InformalFigure, Table, and InformalTable.

The distinction between formal and informal elements is that formal elements have titles while informal ones do not. The InformalFigure element was introduced in DocBook V3.1. In prior versions of DocBook, you could only achieve the effect of an informal figure by placing its content, unwrapped, at the location where the informal figure was desired.

Paragraphs

There are three paragraph elements: Para, SimPara (simple paragraphs may not contain other block-level elements), and FormalPara (formal paragraphs have titles).

Equations

There are two block-equation elements, Equation and InformalEquation (for inline equations, use InlineEquation).

Informal equations don't have titles. For reasons of backward-compatibility, Equations are not required to have titles. However, it may be more difficult for some stylesheet languages to properly enumerate Equations if they lack titles.

Graphics

Graphics occur most frequently in Figures and ScreenShots, but they can also occur without a wrapper. DocBook considers a Graphic a block element, even if it appears to occur inline. For graphics that you want to be represented inline, use InlineGraphic.

DocBook V3.1 introduced a new element to contain graphics and other media types: MediaObject and its inline cousin, InlineMediaObject. These elements may contain video, audio, image, and text data. A single media object can contain several alternative forms from which the presentation system can select the most appropriate object.

Questions and answers

DocBook V3.1 introduced the QandASet element, which is suitable for FAQs (Frequently Asked Questions) and other similar collections of Questions and Answers.

Miscellaneous block elements

The following block elements are also available:

BlockQuote

A block quotation. Block quotations may have Attributions.

CmdSynopsis

An environment for marking up all the parameters and options of a command.

Epigraph

A short introduction, typically a quotation, at the beginning of a document. Epigraphs may have Attributions.

FuncSynopsis

An environment for marking up the return value and arguments of a function.

Highlights

A summary of the main points discussed in a book component (chapter, section, and so on).

MsgSet

A set of related error messages.

Procedure

A procedure. Procedures contain Steps, which may contain SubSteps.

Sidebar

A sidebar.

Inline Elements

Users of DocBook are provided with a surfeit of inline elements. Inline elements are used to mark up running text. In published documents, inline elements often cause a font change or other small change, but they do not cause line or paragraph breaks.

In practice, writers generally settle on the tagging of inline elements that suits their time and subject matter. This may be a large number of elements or only a handful. What is important is that you choose to mark up not every possible item, but only those for which distinctive tagging will be useful in the production of the finished document for the readers who will search through it.

The following comprehensive list may be a useful tool for the process of narrowing down the elements that you will choose to mark up; it is not intended to overwhelm you by its sheer length. For convenience, we've divided the inlines into several subcategories.

The classification used here is not meant to be authoritative, only helpful in providing a feel for the nature of the inlines. Several elements appear in more than one category, and arguments could be made to support the placement of additional elements in other categories or entirely new categories.

Traditional publishing inlines

These inlines identify things that commonly occur in general writing:

Abbrev

An abbreviation, especially one followed by a period.

Acronym

An often pronounceable word made from the initial (or selected) letters of a name or phrase.

Emphasis

Emphasized text.

Footnote

A footnote. The location of the Footnote element identifies the location of the first reference to the footnote. Additional references to the same footnote can be inserted with FootnoteRef.

Phrase

A span of text.

Quote

An inline quotation.

Trademark

A trademark.

Cross references

The cross reference inlines identify both explicit cross references, such as Link, and implicit cross references like GlossTerm. You can make the most of the implicit references explicit with a LinkEnd attribute.

Anchor

A spot in the document.

Citation

An inline bibliographic reference to another published work.

CiteRefEntry

A citation to a reference page.

CiteTitle

The title of a cited work.

FirstTerm

The first occurrence of a term.

GlossTerm

A glossary term.

Link

A hypertext link.

OLink

A link that addresses its target indirectly, through an entity.

ULink

A link that addresses its target by means of a URL (Uniform Resource Locator).

XRef

A cross reference to another part of the document.

Markup

These inlines are used to mark up text for special presentation:

ForeignPhrase

A word or phrase in a language other than the primary language of the document.

WordAsWord

A word meant specifically as a word and not representing anything else.

ComputerOutput

Data, generally text, displayed or presented by a computer.

Literal

Inline text that is some literal value.

Markup

A string of formatting markup in text that is to be represented literally.

Prompt

A character or string indicating the start of an input field in a computer display.

Replaceable

Content that may or must be replaced by the user.

SGMLTag

A component of SGML markup.

UserInput

Data entered by the user.

Mathematics

DocBook does not define a complete set of elements for representing equations. No one has ever pressed the DocBook maintainers to add this functionality, and the prevailing opinion is that incorporating MathML using a mechanism like namespaces is probably the best long-term solution.

InlineEquation

A mathematical equation or expression occurring inline.

Subscript

A subscript (as in H2O, the molecular formula for water).

Superscript

A superscript (as in x2, the mathematical notation for x multiplied by itself).

User interfaces

These elements describe aspects of a user interface:

Accel

A graphical user interface (GUI) keyboard shortcut.

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.

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.

MenuChoice

A selection or series of selections from a menu.

MouseButton

The conventional name of a mouse button.

Shortcut

A key combination for an action that is also accessible through a menu.

Programming languages and constructs

Many of the technical inlines in DocBook are related to programming.

Action

A response to a user event.

ClassName

The name of a class, in the object-oriented programming sense.

Constant

A programming or system constant.

ErrorCode

An error code.

ErrorName

An error name.

ErrorType

The classification of an error message.

Function

The name of a function or subroutine, as in a programming language.

Interface

An element of a GUI.

InterfaceDefinition

The name of a formal specification of a GUI.

Literal

Inline text that is some literal value.

MsgText

The actual text of a message component in a message set.

Parameter

A value or a symbolic reference to a value.

Property

A unit of data associated with some part of a computer system.

Replaceable

Content that may or must be replaced by the user.

ReturnValue

The value returned by a function.

StructField

A field in a structure (in the programming language sense).

StructName

The name of a structure (in the programming language sense).

Symbol

A name that is replaced by a value before processing.

Token

A unit of information.

Type

The classification of a value.

VarName

The name of a variable.

Operating systems

These inlines identify parts of an operating system, or an operating environment:

Application

The name of a software program.

Command

The name of an executable program or other software command.

EnVar

A software environment variable.

Filename

The name of a file.

MediaLabel

A name that identifies the physical medium on which some information resides.

MsgText

The actual text of a message component in a message set.

Option

An option for a software command.

Parameter

A value or a symbolic reference to a value.

Prompt

A character or string indicating the start of an input field in a computer display.

SystemItem

A system-related item or term.

General purpose

There are also a number of general-purpose technical inlines.

Application

The name of a software program.

Database

The name of a database, or part of a database.

Email

An email address.

Filename

The name of a file.

Hardware

A physical part of a computer system.

InlineGraphic

An object containing or pointing to graphical data that will be rendered inline.

Literal

Inline text that is some literal value.

MediaLabel

A name that identifies the physical medium on which some information resides.

Option

An option for a software command.

Optional

Optional information.

Replaceable

Content that may or must be replaced by the user.

Symbol

A name that is replaced by a value before processing.

Token

A unit of information.

Type

The classification of a value.