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.
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.
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 pages almost always occur at the front of a book.
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 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.
These are the chapter-like elements of a Book.
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.
There are several flavors of sectioning elements in DocBook:
The Sect1…Sect5 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.
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.
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.
A BridgeHead provides a section title without any containing section.
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.
Glossarys, Bibliographys, and Indexes can be broken into top-level divisions, but not sections. Unlike sections, these elements do not nest.
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.
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.
There are seven list elements in DocBook:
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.
An unordered (bulleted) list. There are attributes to control the marks used.
A numbered list. There are attributes to control the type of enumeration.
A repeating set of named items. For example, a list of states and their capitals might be represented as a SegmentedList.
An unadorned list of items. SimpleLists can be inline or arranged in columns.
A list of terms and definitions or descriptions. (This list of list types is a VariableList.)
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.
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.
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.
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 .
A ProgramListing is a verbatim environment, usually presented in Courier or some other fixed-width font, for program sources, code fragments, and similar listings.
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 is actually a wrapper for a Graphic intended for screen shots of a GUI for example.
A Synopsis is a verbatim environment for command and function synopsis.
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.
There are three paragraph elements: Para, SimPara (simple paragraphs may not contain other block-level elements), and FormalPara (formal paragraphs have titles).
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 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.
DocBook V3.1 introduced the QandASet element, which is suitable for FAQs (Frequently Asked Questions) and other similar collections of Questions and Answers.
The following block elements are also available:
A block quotation. Block quotations may have Attributions.
An environment for marking up all the parameters and options of a command.
A short introduction, typically a quotation, at the beginning of a document. Epigraphs may have Attributions.
An environment for marking up the return value and arguments of a function.
A summary of the main points discussed in a book component (chapter, section, and so on).
A procedure. Procedures contain Steps, which may contain SubSteps.
A sidebar.
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.
These inlines identify things that commonly occur in general writing:
An often pronounceable word made from the initial (or selected) letters of a name or phrase.
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.
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.
These inlines are used to mark up text for special presentation:
A word or phrase in a language other than the primary language of the document.
A word meant specifically as a word and not representing anything else.
A string of formatting markup in text that is to be represented literally.
A character or string indicating the start of an input field in a computer display.
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.
A superscript (as in x2, the mathematical notation for x multiplied by itself).
These elements describe aspects of a user interface:
The text of a label in a GUI.
The internal, frequently numeric, identifier for a key on a keyboard.
A key combination for an action that is also accessible through a menu.
Many of the technical inlines in DocBook are related to programming.
The name of a class, in the object-oriented programming sense.
The name of a function or subroutine, as in a programming language.
A unit of data associated with some part of a computer system.
The name of a structure (in the programming language sense).
These inlines identify parts of an operating system, or an operating environment:
The name of an executable program or other software command.
A name that identifies the physical medium on which some information resides.
A character or string indicating the start of an input field in a computer display.
There are also a number of general-purpose technical inlines.
An object containing or pointing to graphical data that will be rendered inline.
A name that identifies the physical medium on which some information resides.