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
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 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:
- Dedication
The
dedicationpages almost always occur at the front of a book.- Navigational components
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.); andindex, for indexes.- Divisions
Divisions are the first hierarchical level below
book. Divisions containparts andreferences. Apartcontains components. Areferencecontainsrefentrys. These are discussed more thoroughly in Making a Reference Page.Books can contain components directly and are not required to contain divisions.
- Components
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
articles in more detail in 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:
sect1,sect2,sect3,sect4,sect5The
sect1…sect5elements are sectioning elements. They can occur in most component-level elements. These numbered section elements must be properly nested (sect2s can only occur insidesect1s,sect3s can only occur insidesect2s, and so on). There are five levels of numbered sections.sectionThe
sectionelement is an alternative to numbered sections. Thesectionelement is recursive, meaning that you can nest it to any depth desired.simplesectIn addition to numbered sections, there is the
simplesectelement. 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
simplesectis that it does not occur in the Table of Contents.bridgeheadA
bridgeheadprovides a section title without any containing section.refsect1…refsect3These 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 arefentry.refsectionThe
refsectionelement is a recursive division in arefentry. It is an alternative to the numbered reference section tags (refsect1…refsect3). Like thesectionelement, therefsectionelement is recursive.glossdiv,bibliodiv, andindexdivThe
glossary,bibliography, andindexelements 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:
titleThe text of the title of a section of a document or of a formal block-level element
titleabbrevThe abbreviation of a title
subtitleThe subtitle of a document
abstractA summary
addressA real-world address, generally a postal address
annotationAn annotation
artpagenumsThe page numbers of an article as published
authorThe name of an individual author
authorgroupA wrapper for author information when a document has multiple authors or collaborators
authorinitialsThe initials or other short identifier for an author
bibliocoverageThe spatial or temporal coverage of a document
biblioidAn identifier for a document
bibliomiscUntyped bibliographic information
bibliomsetA cooked container for related bibliographic information
bibliorelationThe relationship of a document to another
bibliosetA raw container for related bibliographic information
bibliosourceThe source of a document
collabIdentifies a collaborator
confgroupA wrapper for document meta-information about a conference
contractnumThe contract number of a document
contractsponsorThe sponsor of a contract
copyrightCopyright information about a document
dateThe date of publication or revision of a document
editionThe name or number of an edition of a document
editorThe name of the editor of a document
extendedlinkAn XLink extended link
issuenumThe number of an issue of a journal
itermsetA set of index terms in the meta-information of a document
keywordsetA set of keywords describing the content of a document
legalnoticeA statement of legal obligations or requirements
mediaobjectA displayed media object (video, audio, image, etc.)
orgnameThe name of an organization
othercreditA person or entity, other than an author or editor, credited in a document
pagenumsThe numbers of the pages in a book, for use in a bibliographic entry
printhistoryThe printing history of a document
productnameThe formal name of a product
productnumberA number assigned to a product
pubdateThe date of publication of a document
publisherThe publisher of a document
publishernameThe name of the publisher of a document
releaseinfoInformation about a particular release of a document
revhistoryA history of the revisions to a document
seriesvolnumsNumbers of the volumes in a series of books
subjectsetA set of terms describing the subject matter of a document
volumenumThe 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:
calloutlistA list of
callouts and their descriptions. Thecallouts are marks, frequently numbered and typically on a graphic (imageobjectco) or verbatim environment (programlistingcoorscreenco), that are described in acalloutlist.bibliolistA list of bibliography entries (
biblioentryorbibliomixedelements).glosslistitemizedlistAn unordered (bulleted) list. There are attributes to control the marks used.
orderedlistA numbered list. There are attributes to control the type of enumeration.
segmentedlistA repeating set of named items. For example, a list of states and their capitals might be represented as a
segmentedlist. Segmented lists consist ofsegtitles,seglistitems, andsegs.simplelistAn unadorned list of items.
simplelists can be inline or arranged in columns.variablelistA 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 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.
addressThe
addresselement is intended for postal addresses. In addition to being line-specific,addresscontains additional elements suitable for marking up names and addresses:city,country,fax,otheraddr,personname,phone,pob,postcode,state, andstreet.literallayoutA
literallayoutdoes not have any semantic association beyond the preservation of whitespace and line breaks. In particular, whileprogramlistingandscreenare frequently presented in a fixed-width font, a change of fonts is not ordinarily implied byliterallayout.programlistingandprogramlistingcoThe
programlistingandprogramlistingcoelements 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 thatprogramlistingcosupports markup for callouts.screenandscreencoThe
screenandscreencoelements are verbatim or literal environments for text screen captures, other fragments of an ASCII display, and similar things.screenis also a frequent catchall for any verbatim text. The two elements are the same, except thatscreencosupports markup for callouts.screenshotscreenshotis actually a wrapper for amediaobjectintended for screenshots of a GUI, for example.synopsisA
synopsisis 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, 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 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:
audioobjectA wrapper for audio data and its associated meta-information. (Which contains
audiodata.)imageobjectA wrapper for image data and its associated meta-information. (Which contains
imagedata.)imageobjectcoA wrapper for an image object with callouts. (Which contains
imagedataand callout-related information).videoobjectA wrapper for video data and its associated meta-information. (Which contains
videodata.)textobjectA 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
steps, 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:
cmdsynopsisA syntax summary for a software command. A
cmdsynopsiscontainsarg,command, andgroupelements. For long synopses, thesbrtag can be used to indicate where a break should occur. Complex synopses can be composed fromsynopfragments.funcsynopsisThe syntax summary for a function definition. A function synopsis consists of one or more
funcprototypes and may include additional, literal information in afuncsynopsisinfo. Each prototype consists ofmodifiers, afuncdef, and a collection ofparamdef,varargs, and/orvoidelements.classsynopsisThe syntax summary for a class definition. A class synopsis consists of one or more
ooclass,ooexception, oroointerfaceelements followed by zero or moreconstructorsynopsis,destructorsynopsis,fieldsynopsis, andmethodsynopsiselements Likefuncsynopsis, it may include additional, literal information, in this case, in aclasssynopsisinfo.
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:
abbrevacronymAn often pronounceable word made from the initial (or selected) letters of a name or phrase.
emphasisfootnoteA footnote. The location of the
footnoteelement identifies the location of the first reference to the footnote. Additional references to the same footnote can be inserted withfootnoteref.phrasequotetrademark
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.
anchorcitationciterefentrycitetitlefirsttermglosstermlinkolinkxref
These inlines are used to mark up text for special presentation:
foreignphraseA word or phrase in a language other than the primary language of the document
wordaswordA word meant specifically as a word and not representing anything else
computeroutputliteralmarkupA string of formatting markup in text that is to be represented literally
promptA character or string indicating the start of an input field in a computer display
replaceabletaguserinput
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:
classnameThe name of a class, in the object-oriented programming sense
constanterrorcodeerrornameerrortypefunctionThe name of a function or subroutine, as in a programming language
literalmsgtextparameterpropertyA unit of data associated with some part of a computer system
replaceablereturnvaluesymboltokentypevarname
These inlines identify parts of an operating system, or an operating environment: