DocBook elements can be divided broadly into these categories:
Sets |
Books |
Divisions, which divide books |
Components, which divide books or divisions |
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
book
s. 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 series of computer systems or the documentation
(tutorial, reference, etc.) for a programming language. Sets are allowed
to contain other sets, though this is not common.
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
around the world, any attempt to impose a strict ordering of elements
would make the content model extremely complex. Therefore, DocBook gives
you free rein. You can use a local customization (see Chapter 5) if you want to impose a more strict
ordering for your applications.
A book
consists of a mixture of the following
elements:
The dedication
pages almost always occur
at the front of a book.
There are a couple of component-level elements
designed for navigation: toc
, for Tables of
Contents and Lists of Titles (for lists of figures, tables,
examples, etc.); and index
, for indexes.
Divisions are the first hierarchical level below
book
. Divisions contain
part
s and reference
s. A
part
contains components. A
reference
contains
refentry
s. These are discussed more thoroughly
in Making a Reference Page.
Books can contain components directly and are not required to contain divisions.
Components are the chapter-like elements of a
book
or part
:
preface
, chapter
, appendix
, glossary
,
and bibliography
. An article
can
also occur at the component level. We describe
article
s in more detail in Making an Article. Components generally contain block elements
and/or sections, and some can contain navigational components and
refentry
s.
There are several flavors of sectioning elements in DocBook:
sect1
, sect2
, sect3
, sect4
, sect5
The sect1
…sect5
elements are sectioning elements. They can occur in most component-level elements. These
numbered section elements must be properly nested
(sect2
s can only occur inside
sect1
s, sect3
s can only
occur inside sect2
s, and so on). There are five
levels of numbered sections.
section
The section
element is an
alternative to numbered sections. The section
element is recursive, meaning that you can nest it to any depth
desired.
simplesect
In addition to numbered sections, there is 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 distinguishing feature of simplesect
is
that it does not occur in the Table of Contents.
bridgehead
A bridgehead
provides a section
title without any containing section.
refsect1
…refsect3
These elements, which occur only in
refentry
s, are analogous to the numbered
section elements in components. There are only three levels of
numbered section elements in a refentry
.
refsection
The refsection
element is a
recursive division in a refentry
. It is an
alternative to the numbered reference section tags
(refsect1
…refsect3
). Like
the section
element, the
refsection
element is recursive.
glossdiv
, bibliodiv
, and
indexdiv
The glossary
,
bibliography
, and index
elements 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, and
many other elements, include a wrapper for meta-information about the
content. That element is named info
. In earlier
versions of DocBook, there were many similarly named elements for this
purpose: bookinfo
, chapterinfo
,
etc. In DocBook V5.0, there is only one.
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.
An info
can contain:
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
subtitle
The subtitle of a document
abstract
A summary
address
A real-world address, generally a postal address
annotation
An annotation
artpagenums
The page numbers of an article as published
author
The name of an individual author
authorgroup
A wrapper for author information when a document has multiple authors or collaborators
authorinitials
The initials or other short identifier for an author
bibliocoverage
The spatial or temporal coverage of a document
biblioid
An identifier for a document
bibliomisc
Untyped bibliographic information
bibliomset
A cooked container for related bibliographic information
bibliorelation
The relationship of a document to another
biblioset
A raw container for related bibliographic information
bibliosource
The source of a document
collab
Identifies a collaborator
confgroup
A wrapper for document meta-information about a conference
contractnum
The contract number of a document
contractsponsor
The sponsor of a contract
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
extendedlink
An XLink extended link
issuenum
The number of an issue of a journal
itermset
A set of index terms in the meta-information of a document
keywordset
A set of keywords describing the content of a document
legalnotice
A statement of legal obligations or requirements
mediaobject
A displayed media object (video, audio, image, etc.)
orgname
The name of an organization
othercredit
A person or entity, other than an author or editor, credited in a document
pagenums
The numbers of the pages in a book, for use in a bibliographic entry
printhistory
The printing history of a document
productname
The formal name of a product
productnumber
A number assigned to a product
pubdate
The date of publication of a document
publisher
The publisher of a document
publishername
The name of the publisher of a document
releaseinfo
Information about a particular release of a document
revhistory
A history of the revisions to a document
seriesvolnums
Numbers of the volumes in a series of books
subjectset
A set of terms describing the subject matter of a document
volumenum
The volume number of a document in a set (as of books in a set or articles in a journal)
The title
, titleabbrev
, and
subtitle
elements can usually appear either
immediately before or inside the info
wrapper (but
not both). This means you don’t need the extra wrapper in the common
case where all you want to specify is a title.
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.
At the paragraph level, it’s convenient to divide elements into two classes, block and inline. From a structural point of view, this distinction is based loosely on their relative size, but it’s easiest to describe the difference in terms of their presentation.
Block elements are usually presented with a paragraph (or larger) break before and after them. Most can contain other block elements, and many can contain character data and inline elements. Paragraphs, lists, sidebars, tables, and block quotations are all common examples of block elements.
Inline elements are generally represented without any obvious breaks. The most common distinguishing mark of inline elements is a font change, but inline elements may present no visual distinction at all. Inline elements contain character data and possibly other inline elements, but they never contain block elements. Inline elements are used to mark up data such as cross-references, filenames, commands, options, subscripts and superscripts, and glossary terms.
There are eight list elements in DocBook:
calloutlist
A list of callout
s and their
descriptions. The callout
s are marks,
frequently numbered and
typically on a graphic (imageobjectco
) or
verbatim environment (programlistingco
or
screenco
), that are described in a
calloutlist
.
bibliolist
A list of bibliography entries
(biblioentry
or
bibliomixed
elements).
glosslist
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
. Segmented lists consist of
segtitle
s, seglistitem
s, and
seg
s.
simplelist
An unadorned list of items.
simplelist
s can be inline or arranged in
columns.
variablelist
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. DocBook
does not impose any specific semantics on the individual admonitions.
For example, DocBook does not mandate that warning
s
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.
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: city
,
country
, fax
,
otheraddr
, personname
,
phone
, pob
,
postcode
, state
, and
street
.
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 ordinarily implied by
literallayout
.
programlisting
and
programlistingco
The programlisting
and
programlistingco
elements are verbatim
environments, usually presented in Courier or some other
fixed-width font, for program sources, code fragments, and
similar listings. The two elements are the same, except that
programlistingco
supports markup for
callouts.
screen
and
screenco
The screen
and
screenco
elements are verbatim or literal
environments for text screen captures, other fragments of an
ASCII display, and similar things.
screen
is also a frequent catchall for any
verbatim text. The two elements are the same, except that
screenco
supports markup for callouts.
screenshot
screenshot
is actually a
wrapper for a mediaobject
intended for
screenshots of a GUI, for example.
synopsis
A synopsis
is a verbatim
environment for command and function synopses.
Examples, figures, and tables are supported with the
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.
DocBook supports CALS tables (defined with
tgroup
, colspec
,
spanspec
, thead
,
tfoot
, tbody
,
row
, entry
,
entrytbl
, and caption
) and HTML
tables (defined with col
,
colgroup
, thead
,
tfoot
, tbody
,
tr
, td
, and
caption
).
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, equation
s are not required to have
titles. However, it may be more difficult for some stylesheet
languages to properly enumerate equation
s if they
lack titles.
Graphics occur most frequently in
figure
s and screenshot
s, but
they can also occur outside those wrappers. DocBook considers a
mediaobject
a block element, even if it occurs in
an inline context. For graphics that you want to be represented
inline, use inlinemediaobject
.
Media objects (and inline media objects) can contain five kinds of content:
audioobject
A wrapper for audio data and its associated
meta-information. (Which contains
audiodata
.)
imageobject
A wrapper for image data and its associated
meta-information. (Which contains
imagedata
.)
imageobjectco
A wrapper for an image object with callouts. (Which
contains imagedata
and callout-related
information).
videoobject
A wrapper for video data and its associated
meta-information. (Which contains
videodata
.)
textobject
A wrapper for a text description of an object and its
associated meta-information. (Which contains
textdata
.)
The audio, image, video, and text data in a media object are, by definition, alternatives.
The qandaset
element is suitable for
FAQs (Frequently Asked Questions) and other similar
collections of questions and answers. Each
qandaentry
contains a question
and its answer
(s). The set of questions and answers
can be divided into sections with qandadiv
.
A procedure
contains
step
s, which may contain
substeps
or
stepalternatives
.
The task
element is a wrapper around
the procedure
element that provides additional,
optional elements, including tasksummary
,
taskprerequisites
, example
, and
taskrelated
.
DocBook provides a number of elements for describing command, function, and class synopses:
cmdsynopsis
A syntax summary for a software command. A
cmdsynopsis
contains arg
,
command
, and group
elements. For long synopses, the sbr
tag can
be used to indicate where a break should occur. Complex synopses
can be composed from synopfragment
s.
funcsynopsis
The syntax summary for a function definition. A
function synopsis consists of one or more
funcprototype
s and may include additional,
literal information in a funcsynopsisinfo
.
Each prototype consists of modifier
s, a
funcdef
, and a collection of
paramdef
, varargs
, and/or
void
elements.
classsynopsis
The syntax summary for a class definition. A class
synopsis consists of one or more ooclass
,
ooexception
, or
oointerface
elements followed by zero or more
constructorsynopsis
,
destructorsynopsis
,
fieldsynopsis
, and
methodsynopsis
elements Like
funcsynopsis
, it may include additional,
literal information, in this case, in a
classsynopsisinfo
.
The following block elements are also available:
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:
abbrev
acronym
An often pronounceable word made from the initial (or selected) letters of a name or phrase.
emphasis
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
quote
trademark
The cross-reference inlines identify both explicit
cross-references, such as link
, and implicit
cross-references, such as glossterm
. You can make
most of the implicit references explicit with a linkend
attribute.
anchor
citation
citerefentry
citetitle
firstterm
glossterm
link
olink
xref
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
literal
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
tag
userinput
DocBook does not define a complete set of elements for
representing equations. The Mathematical Markup Language
(MathML) [MathML]
is a standard that defines a comprehensive grammar for representing
equations. MathML markup may be used in any of the
equation elements
(equation
,informalequation
, and
inlineequation
). For simple mathematics equations
that do not require extensive markup, the
mathphrase
element is an alternative.
Many of the technical inlines in DocBook are related to programming:
classname
The name of a class, in the object-oriented programming sense
constant
errorcode
errorname
errortype
function
The name of a function or subroutine, as in a programming language
literal
msgtext
parameter
property
A unit of data associated with some part of a computer system
replaceable
returnvalue
symbol
token
type
varname
These inlines identify parts of an operating system, or an operating environment: