<chapter id=user01>
<title>Document Hierarchies</title>
<para>DocBook makes available several different document hierarchies and a
large library of markup for the content of documents. In addition, it offers
markup for various kinds of nonlinear information (such as hyperlinks). The
following chapters explain how to choose and apply DocBook markup.</para>
<para>DocBook supports several choices of overall document hierarchy that
give <quote>shape</quote> to a document: <itemizedlist><listitem><para>Books
and Sets (collections of Books)</para>
</listitem><listitem><para>Reference entries</para>
</listitem><listitem><para>Articles</para>
</listitem></itemizedlist></para>
<para>These structures can be used in combination. For example, a reference
entry containing a command's <quote>man page</quote> information might exist
in isolation and also appear in a higher-level structure.</para>
<para>Note that you are not constrained to using the top-level structures
in DocBook; you can start an SGML document at <emphasis>any</emphasis> level
of DocBook's structure, so long as your <firstterm>document element</firstterm>
(top-level element) is reflected in the document type name in your 
<literal>DOCTYPE</literal> declaration. For example:

<programlisting>
<![ CDATA [
<!DOCTYPE Para PUBLIC "-//Davenport//DTD DocBook V3.0//EN">
<Para>
This is an extremely short document, consisting only of a 
single DocBook paragraph.
</Para>
]]>
</programlisting>
</para>
<sect1>
<title>Sets and Books</title>
<sect2>
<title>Sets and Books</title>
<graphic entityref="set-tree"></graphic>
<para>The Set element is the highest possible document element in DocBook.
It contains an optional Title and TitleAbbrev, an optional SetInfo (which
can also contain Title), an optional ToC, two or more Books, and an optional
SetIndex. Note that Set, Book, RefEntry, and Article each have their own containers
for metainformation. In the case of Set, you should choose one place to store
your Set title information: either directly in Set or inside SetInfo.</para>
<para>A typical Set might be structured as follows:<literallayout>Set
  Title
  SetInfo
  Book
  Book
  Book
  SetIndex</literallayout></para>
<para>The Book element is the level at which most DocBook documents start;
even if your documents are delivered in a Set, you need not use Set unless
you want to do processing on the Set markup.</para>
<graphic entityref="book-tree"></graphic>
<para>The structure of Book is relatively complex, to allow for a variety
of configurations of major Book components. The structure assumes that you
will place elements such as ToC and Glossary where you want them to appear
in the output flow of your document. Book's content model has three main segments,
corresponding roughly to the traditional front matter, body, and back matter:<itemizedlist>
<listitem><para>At the beginning, Book can contain an optional Title and TitleAbbrev,
an optional BookInfo (which can also indirectly contain Title and TitleAbbrev),
an optional ToC, zero or more LoTs (lists of titles), and a mixture of zero
or more Bibliography, Glossary, and Preface elements in any order. You should
choose one place to store your Book title information: either directly in
Book or inside BookInfo's BookBiblio element.</para>
</listitem><listitem><para>The body of Book can contain Chapters followed
by any number of References (collections of reference entries), References
only, Parts only (which can contain lower-level components such as Chapters),
or Articles only.</para>
</listitem><listitem><para>At the end, Book can contain zero or more Appendices,
a mixture of zero or more Bibliography and Glossary elements in any order,
a mixture of zero or more Index and SetIndex elements in any order, zero or
more LoTs, and an optional ToC.</para>
</listitem></itemizedlist></para>
<para>Here is a diagram of a fairly typical Book:<literallayout>Book
   BookInfo
   ToC
   LoT          <lineannotation>for figures</lineannotation>
   LoT          <lineannotation>for tables</lineannotation>
   Preface
   Chapter
   Chapter
   Chapter
   Chapter
   Reference
   Appendix
   Appendix
   Glossary
   Bibliography
   Index</literallayout></para>
<para>Books can have Chapters and Appendices grouped in Parts. Note that you
can group Appendices into a Part simply by supplying a Part at the end of
the other Book parts that contains only Appendices. You should not mix Chapters
and Appendices in any one part, though the structure allows you to.<literallayout>
Book
   BookInfo
   Preface
   Part
	 PartIntro
	 Chapter
	 Chapter
   Part
	 PartIntro
	 Chapter
	 Chapter
	 Chapter
   Part
	 PartIntro
	 Appendix
	 Appendix</literallayout></para>
<para>A reference manual might be arranged like this:<literallayout>Book
   BookInfo
   ToC
   LoT
   Preface
   Reference
   Reference
   Reference
   Reference
   Appendix
   Appendix
   Appendix
   Appendix
   Index</literallayout></para>
<bridgehead>Set and Book Metainformation</bridgehead>
<para>SetInfo and BookInfo allow you to supply document information (also
known as metainformation) on Sets and Books, respectively. SetInfo allows
you to choose whatever document information elements are appropriate and supply
them in any order. BookInfo, by contrast, imposes an order on its subelements.
It contains zero or more Graphics that illustrate or represent the topic of
the Book, a required BookBiblio (which also imposes a strict internal order
on its subelements), zero or more LegalNotices, and zero or more ModeSpecs
for the storage of information associated with OLink linking elements.</para>
<para>While you can use LegalNotice as a generic container for many kinds
of metainformation, it's better to try to store the information in one of
the BookBiblio elements if an appropriate element, such as Copyright or ProductNumber,
is available. BookInfo has an optional Contents attribute, which points to
the list of IDs of the major components making up the Book.</para>
<para>BookBiblio is used in BookInfo and ArtHeader to supply information about
a Book or article, and is also used in BiblioEntry to supply information about
a cited work.</para>
<graphic entityref="bookbiblio-tree"></graphic>
<bridgehead>Set and Book Attributes</bridgehead>
<para>Set and Book have an optional FPI attribute, which can be used to supply
a formal public identifier for the Set or Book. Book also has an optional
Label attribute</para>
</sect2>
<sect2>
<title>Book Components</title>
<para>Appendix, Chapter, Index, Part, Preface, SetIndex, and Reference are
components allowed inside Books. Bibliography and Glossary can appear as Book
components and also as parts of Book components.</para>
<para>A Book's main body can be organized starting at one of two logical levels.
It can contain Book components such as Chapters, Appendices, and References
directly, or it can contain groups of those components organized in Parts.
</para>
<bridgehead>Part</bridgehead>
<graphic entityref="part-tree"></graphic>
<para>The content model of Part is very broad: it contains an optional DocInfo,
a Title, an optional TitleAbbrev, an optional PartIntro, and a mixture of
one or more Appendices, Chapters, Bibliographies, Glossaries, Prefaces, RefEntries,
and References, in any order. You should not, however, mix these components
inappropriately when using Parts.</para>
<bridgehead>Reference</bridgehead>
<graphic entityref="reference-tree"></graphic>
<para>Reference is a special-purpose component for grouping collections of
RefEntries. References can be used, for example, to organize <trademark>UNIX
</trademark> man pages into their traditional numbered sections. Reference
contains an optional DocInfo, a Title, an optional TitleAbbrev, an optional
PartIntro (which is also used in Parts), and one or more RefEntry elements.
The Label attribute on Reference may have as its value a nonnumeric keyword
(such as <quote>CMD</quote>), rather than a number, for use in constructing
formal object prefixes, page number prefixes, and so on.</para>
<bridgehead>Preface</bridgehead>
<graphic entityref="preface-tree"></graphic>
<para>The content models of Preface, Chapter, and Appendix are similar. Preface
contains an optional DocInfo, a Title, an optional TitleAbbrev, any number
of object-level elements from the <sgmltag class="paramentity">divcomponent.mix
</sgmltag> mixture, and optionally a group of Sect1s or SimpleSects or a group
of RefEntries (so long as some content is present). A Book may have multiple
Prefaces, for example, one containing an acknowledgments section and another
containing a foreword; these may be distinguished by their titles. Even if
you always have a single Preface and always want it to be titled <quote>Preface,
</quote> you should supply Title text, as formatting applications are unlikely
to generate it for you.</para>
<bridgehead>Chapter</bridgehead>
<graphic entityref="chapter-tree"></graphic>
<para>Chapter contains an optional DocInfo, a Title, an optional TitleAbbrev,
an optional ToCchap for holding a Chapter-level table of contents, any number
of object-level elements from the <sgmltag class="paramentity">divcomponent.mix
</sgmltag> mixture, any number of Sect1, RefEntry, or SimpleSect elements
(so long as at least some content is supplied), and zero or more Indices,
Glossaries, and Bibliographies. Note that the choice of Sect1, RefEntry, or
SimpleSect precludes using any of the others at the same level: directly inside
any one chapter, you can organize your information only as formal sections,
reference entries, or simple sections.</para>
<bridgehead>Appendix</bridgehead>
<graphic entityref="appendix-tree"></graphic>
<para>Appendix has the same content model as Chapter, except that it can't
contain Index, Glossary, and Bibliography at the end.</para>
<bridgehead>DocInfo</bridgehead>
<graphic entityref="docinfo-tree"></graphic>
<para>DocInfo contains metainformation for the Book component in which it
appears. DocInfo is similar to BookInfo in that its contents have a fixed
order: It contains zero or more Graphics that illustrate the component, a
Title, an optional TitleAbbrev, an optional SubTitle, zero or more AuthorGroups,
zero or more Abstracts, an optional RevHistory, and zero or more LegalNotices.
</para>
</sect2>
</sect1>
<sect1>
<title>General-Purpose Sections</title>
<para>Five levels of normal section are available: Sect1, Sect2, Sect3, Sect4,
and Sect5. These must be nested in proper order. In addition, SimpleSect can
be used within any of the numbered levels, and BridgeHead can be used to simulate
a section structure. For example, the same information might be organized
as:<literallayout>Sect1
    Sect2
        Sect3</literallayout>or:<literallayout>Sect1
    Sect2
        SimpleSect</literallayout>or:</para>
<literallayout>Sect1
    Sect2
        BridgeHead</literallayout>
<comment>Graphic for numbered sections TBS.</comment>
<bridgehead>Sections</bridgehead>
<para>The section elements (Sect1 through Sect5) contain, in fixed order,
a Title, an optional TitleAbbrev, any number of <sgmltag class="paramentity">
nav.class</sgmltag> elements, any number of object-level elements from the <sgmltag
class="paramentity">divcomponent.mix</sgmltag> mixture, and optionally either
a group of the next lower level of section (in the case of Sect1 through Sect4),
a group of RefEntries, or a group of SimpleSects, followed by any number of <sgmltag
class="paramentity">nav.class</sgmltag> elements. A section must contain at
least some object-level or subsection content.</para>
<para>The section elements have an optional Label attribute and an optional
Renderas attribute, which indicates the desired appearance of the section's
Title (Sect1 through Sect5).</para>
<comment>Graphic for SimpleSect TBS.</comment>
<bridgehead>SimpleSect</bridgehead>
<para>SimpleSects are atomic (<quote>leaf-level</quote>) sections that cannot
contain subsections, although they may contain BridgeHeads.</para>
<para>SimpleSect contains a Title, an optional TitleAbbrev, and one or more
object-level elements from the <sgmltag class="paramentity">divcomponent.mix
</sgmltag> mixture.</para>
<comment>Graphic for bridging heads TBS.</comment>
<para>BridgeHead provides a Title for a particular spot in the text without
changing the document hierarchy. BridgeHeads should not appear in a table
of contents.</para>
<para>BridgeHead contains one or more elements from the <sgmltag class="paramentity">
title.char.mix</sgmltag> mixture.</para>
<para>BridgeHead has an optional Renderas attribute, which indicates the desired
appearance of the Bridgehead's content (Sect1 through Sect5).</para>
</sect1>
<sect1>
<title>Reference Entries</title>
<para>RefEntry is a specialized section intended to contain reference material
for a software construct. Its content model is much stricter than that for
sections. It is intended to accommodate traditional <trademark>UNIX</trademark>
man pages and other similar structures. In order create a <quote>true</quote>
man page, you should supply a value for the ManVolNum element in the RefMeta
element corresponding to the man page's traditional section number (and optional
suffix).</para>
<para>RefEntries may be organized as collections, for example, by including
them in sections of Chapters or in References.</para>
<graphic entityref="refentry-tree"></graphic>
<para>RefEntry contains, in fixed order, an optional DocInfo, an optional
RefMeta, any number of Comments or elements from the <sgmltag class="paramentity">
link.char.class</sgmltag>, a RefNameDiv, an optional RefSynopsisDiv, and one
or more RefSect1s.</para>
<bridgehead>RefEntry Metainformation</bridgehead>
<para>DocInfo and RefMeta are intended for document metainformation, whereas
RefNameDiv should contain metainformation about the software construct being
described.</para>
<para>RefMeta contains, in fixed order, a RefEntryTitle, an optional ManVolNum,
and any number of RefMiscInfo elements. RefMiscInfo is intended to store special
information associated with traditional man pages (such as chip architecture,
original vendor or distributor, and so on, which often appear in printed man
page headers and footers). The Class attribute may be used to subclass the
kind of information supplied; interchange partners must agree on the Class
attribute values that are meaningful to them.</para>
<para>RefNameDiv contains, in fixed order, an optional RefDescriptor (for
a generic name grouping several software constructs), one or more RefNames
(for each construct being documented), a RefPurpose (for permuted indexes
and quick lookup of reference information), any number of RefClasses (for
describing the applicability of the software construct or constructs on different
system configurations), and any number of comments or elements from the <sgmltag
class="paramentity">link.char.class</sgmltag>.</para>
<bridgehead>RefEntry Content</bridgehead>
<para>RefSynopsisDiv may be used to contain synopsis information that can
be assembled into a quick reference that can be processed separately. It has
roughly the same model as RefSect1, as synopsis information can come in all
sorts of packages. It contains an optional Title, an optional TitleAbbrev,
one or more object-level components from the <sgmltag class="paramentity">
ref component.mix</sgmltag> mixture, and any number of RefSect2 elements.
If there is no Title, it is assumed that a standard title (such as <quote>
Synopsis,</quote> <quote>Syntax,</quote> or <quote>Format</quote>) will be
generated on output.</para>
<para>Three levels of reference section are provided: RefSect1-3. For a traditional
man page structure, use RefSect1 Title elements to indicate each top-level
section, such as Description, Options/Flags, and References/See Also.</para>
<comment>Graphic for numbered reference sections TBS.</comment>
<para>The RefSect elements contain a Title, an optional TitleAbbrev, one or
more object-level components from the <sgmltag class="paramentity">ref.component.mix
</sgmltag> mixture, and any number of lower-level reference sections (in the
case of RefSect1 and RefSect2).</para>
</sect1>
<sect1>
<title>Articles</title>
<comment>Article description and graphic TBS.</comment></sect1>
<sect1>
<title>Document Navigational Information</title>
<sect2>
<title>Tables of Contents and Lists of Titles</title>
<para>DocBook offers markup to store navigation information such as tables
of contents and indices. This information can be handcrafted, or it can be
generated, organized into SGML form, and used to populate an SGML document
(a process sometimes known as augmentation).</para>
<para>A ToC, or table of contents, can be a Book component on its own or can
occur within other Book components. ToC is subdivided to follow the structure
of a Book: following an optional DocInfo, Title, and TitleAbbrev, a ToC may
have any number of ToCfronts, which are the entries for the front matter.
Following the ToCfronts, if any, a ToC must have either one or more ToCparts
(entries for Parts) or ToCchaps (entries for Chapters and Appendices), and
may have any number of ToCbacks (entries for back matter). A ToCpart begins
with one or more ToCentries (a wrapper for the actual table of contents entry),
then contains any number of ToCchaps. ToCentry has a PageNum attribute, which
may have the value of a physical page number. A ToCchap begins with one or
more ToCentries, then may have any number of ToClevel1s, which are entries
for Sect1s. A ToClevel1 begins with one or more ToCentries, then may have
any number of ToClevel2s, and so on down to ToClevel5, which may have only
one or more ToCentries. Thus if you have a Table of Contents that shows section
headings, the second-level entries are nested within the first-level entries,
and so on. You could make a link of all or part of the contents of a ToCentry.

<programlisting>
<![ CDATA [
<toc>
<title>Table of Contents</title>
<tocchap>
<tocentry>Acknowledgements</tocentry>
<toclevel1>
<tocentry>How to Get the DocBook DTD Online</tocentry>
</toclevel1></tocchap>
<tocchap>
<tocentry>Development of the DocBook DTD</tocentry>
</tocchap>
</toc>
]]>
</programlisting>
</para>

<para>An LoT is like a ToC except that it is used for lists of tables, figures,
or the like, and has no hierarchy. An LoT contains LoTentries, which could
contain links, just like ToCentries. LoTentries have a PageNum attribute and
a SrcCredit attribute, the latter for providing a credit for the source of, <foreignphrase>
e.g.</foreignphrase>, an illustration.</para>
</sect2>
<sect2>
<title>Index and SetIndex</title>
<comment>Index and SetIndex descriptions and graphics TBS.</comment></sect2>
<sect2>
<title>Bibliography</title>
<graphic entityref="bibliography-tree"></graphic>
<para>Bibliography contains an optional DocInfo, Title and TitleAbbrev, any
number of object-level elements from the <sgmltag class="paramentity">component.mix
</sgmltag> mixture, and either one or more BiblioDiv or one or more BiblioEntry
elements.</para>
<para>BiblioDiv contains a Title, an optional TitleAbbrev, any number of object-level
elements from the <sgmltag class="paramentity">component.mix</sgmltag> mixture,
and one or more BiblioEntry elements.</para>
<para>BiblioEntry contains an optional BiblioMisc, followed by an ArtHeader,
BookBiblio, or SeriesInfo, followed by an optional BiblioMisc.</para>
</sect2>
<sect2>
<title>Glossary</title>
<comment>Glossary description and graphic TBS.</comment></sect2>
</sect1>
</chapter>