<preface id="preface">
<?dbhtml filename="ch00.html"?>
<prefaceinfo>
<pubdate>$Date$</pubdate>
<releaseinfo>$Revision$</releaseinfo>
</prefaceinfo>
<title>Preface</title>
<para>
DocBook provides a system for writing structured documents using
&SGML; or &XML;. It is particularly well-suited to books and papers
about computer hardware and software, though it is by no means limited
to them.  DocBook is a document type definition (&DTD;).
Because it is a large and robust &DTD;, and because its
main structures correspond to the general notion of what constitutes a
book, DocBook has been adopted by a large and growing community of
authors. DocBook is supported <quote>out of the box</quote> by a number
of commercial tools, and support for it is rapidly growing in a number
of free software environments. In short, DocBook is an
easy-to-understand and widely used &DTD;. Dozens of organizations use
DocBook for millions of pages of documentation, in various print
and online formats, worldwide.
</para>
<sect1 id="pref-whyread">
<title>Why Read This Book?</title>
<para>
This book is designed to be the clear, concise, normative reference to
the DocBook &DTD;. This book is the official documentation for the
DocBook &DTD;.
</para>
<para>
We hope to answer, definitively, all the questions you might
have about all the elements and entities in DocBook.  In
particular, we cover the following subjects:</para>
<itemizedlist>
<listitem><para>The general nature of DocBook. With over 300 elements,
DocBook can be a bit overwhelming at first. We quickly get you up to
speed on how the pieces fit together.</para>
</listitem>
<listitem><para>How to write DocBook documents. Where should you start
and what should you do?</para>
</listitem>
<listitem><para>Parsing and validation. After you've written a
document, how can you tell if it really conforms to the DocBook
&DTD;?</para>
</listitem>
<listitem><para>How to publish DocBook documents. After you've written
one, what do you do with it? We provide a guide to using some popular
free tools to publish DocBook documents both in print and on the
Web.</para>
</listitem>
<listitem><para>Customizing the &DTD;. Many individuals and
corporations have standardized on the DocBook &DTD;. Whether your
subject matter is computer software documentation or not,
we explain how you can write a <quote>customization layer</quote> to
tailor DocBook explicitly for your information.</para>
</listitem>
<listitem><para>Understanding all of the elements. Each element is
extensively documented, including the intended semantics and the
purpose of all its attributes. An example of proper usage is given
for every element. The parameter entities and character entities are
also described.
</para>
</listitem>
<listitem><para>Stylesheets. Several standard stylesheet
languages are briefly described.</para>
</listitem>
<listitem><para>&XML; compatability. We outline all of the points that
you'll need to consider
as you or your organization contemplate &XML; for authoring, publishing, or
both.</para>
</listitem>
<listitem><para>Additional resources and a
<acronym>CD-ROM</acronym>. Finally, we direct you to other places you
can go for all the latest info, and offer a complete set of online
documentation on the <acronym>CD-ROM</acronym>.</para>
</listitem>
</itemizedlist>
</sect1>

<sect1 id="pref-bookaud">
<title>This Book's Audience</title>
<para>
We expect that most readers will have some familiarity with &SGML; or
&XML;. Even if your experience goes no farther than writing a few
&HTML; pages, you're probably in good shape.  Although we provide an
introduction to &SGML;, &XML;, and structured markup, this book may
not suffice as your only tutorial about &SGML; and &XML;. This
depends, naturally, on your needs and experience.  For a list of some
other good resources, consult <xref linkend="app-resources"/>.
</para>
<para>
Some sections of this book describe tools and applications. For
the most part, these are Microsoft Windows or &UNIX; applications,
although there's nothing about DocBook that makes it unsuitable for the
Mac or <acronym>VM/CMS</acronym> or any other operating system of your
choice.
</para>
</sect1>

<sect1 id="pref-organization">
<title>Organization of This Book</title>
<para>This book is divided into three parts. <citetitle>Part I: Introduction
</citetitle> is an introduction to structured markup and DocBook:</para>
<variablelist>
<varlistentry><term><xref linkend="ch-gssgml"/></term>
<listitem>
<para>A quick introduction to structured markup.</para>
</listitem>
</varlistentry>
<varlistentry><term><xref linkend="ch-create"/></term>
<listitem>
<para>How to make DocBook documents.</para>
</listitem>
</varlistentry>
<varlistentry><term><xref linkend="ch-parse"/></term>
<listitem>
<para>Parsing and validating DocBook documents.</para>
</listitem>
</varlistentry>
<varlistentry><term><xref linkend="ch-publish"/></term>
<listitem>
<para>How to publish DocBook documents.</para>
</listitem>
</varlistentry>
<varlistentry><term><xref linkend="app-customizing"/></term>
<listitem>
<para>How to customize DocBook.</para>
</listitem>
</varlistentry>
</variablelist>

<para condition="refpages"><citetitle>Part II: Reference</citetitle>
<phrase condition="online">
is a complete reference to every element and parameter entity in
the DocBook &dtd.version; &DTD;.
</phrase>
<phrase condition="print">
is a complete reference to every element in the DocBook
&dtd.version; &DTD; and provides a concise summary of the
parameter entities. For a detailed reference to the parameter
entities, consult the online version available either on <link
linkend="app-cdrom">the <acronym>CD-ROM</acronym></link> or the
<ulink url="http://docbook.org/">web site</ulink>.
</phrase>
</para>

<variablelist condition="refpages">
<varlistentry><term><xref linkend="ref-element"/></term>
<listitem>
<para>A reference guide to the DocBook elements.</para>
</listitem>
</varlistentry>
<varlistentry><term><xref linkend="ref-parement"/></term>
<listitem>
<para>A reference guide to the DocBook parameter entities.</para>
</listitem>
</varlistentry>
<varlistentry><term><xref linkend="ref-charent"/></term>
<listitem>
<para>A reference guide to the character entities declared in DocBook.</para>
</listitem>
</varlistentry>
</variablelist>

<para><citetitle>Part III: Appendixes</citetitle> discusses other resources:
</para>
<variablelist>
<varlistentry><term><xref linkend="app-install"/></term>
<listitem>
<para>How to install DocBook, Jade, and the stylesheets.</para>
</listitem>
</varlistentry>
<varlistentry><term><xref linkend="app-xml"/></term>
<listitem>
<para>DocBook as &XML;.</para>
</listitem>
</varlistentry>
<varlistentry><term><xref linkend="app-versions"/></term>
<listitem>
<para>A guide to DocBook versions, including a summary of the features
expected in future releases.</para>
</listitem>
</varlistentry>
<varlistentry><term><xref linkend="app-resources"/></term>
<listitem>
<para>Other resources.</para>
</listitem>
</varlistentry>
<varlistentry><term><xref linkend="app-cdrom"/></term>
<listitem>
<para>What's on the <acronym>CD</acronym>?</para>
</listitem>
</varlistentry>
<varlistentry><term><xref linkend="app-interchange"/></term>
<listitem>
<para>An interchange checklist. Things to consider when you're sharing
DocBook documents with others.</para>
</listitem>
</varlistentry>
<varlistentry><term><xref linkend="quickref"/></term>
<listitem>
<para>A Quick Reference to the elements in DocBook.</para>
</listitem>
</varlistentry>
</variablelist>
<para>At the end of this book you'll find a <link linkend="glossary">Glossary
</link> and an
<!-- YES, THIS IS DUPLICATED ONCE WITH THE LINK AND ONCE WITHOUT: -->
<phrase condition="online"><link linkend="index">Index</link>.</phrase>
<phrase condition="print">Index.</phrase>
</para>
</sect1>

<sect1 id="pref-conventions">
<title>Conventions Used in This Book</title>

<itemizedlist>
<listitem><para>
<sgmltag>Garamond Book</sgmltag> is used for element and
attribute names.
</para></listitem>
<listitem><para>
<literal>Constant Willison</literal>
is used for program examples, attribute value
literals, start- and end-tags, and source code example text.
</para></listitem>
<listitem><para>
<replaceable>Constant Willison Oblique</replaceable> is used for
<quote>replaceable</quote> text or variables.  Replaceable text is text
that describes something you're supposed to type, like a
<replaceable>filename</replaceable>, in which the word
<quote>filename</quote> is a placeholder for the actual filename.</para>
</listitem>
<listitem><para>
<filename>Garamond Italic</filename> is used for filenames and (in the print version
of the book) <acronym>URL</acronym>s.
</para></listitem>
<listitem condition="print"><para>
<ulink url="http://docbook.org/"><acronym>URL</acronym>s</ulink> are
presented in parentheses after the name of the resource they describe
in the print version of the book.
</para></listitem>
</itemizedlist>
</sect1>
<sect1 id="pref-getbook"><title>Getting This Book</title>
<para>
If you want to hold this book in your hand and flip through its pages,
you have to buy it as you would any other book. You can also get this
book in electronic form, as a DocBook &SGML; document, and in &HTML;,
either on the <acronym>CD</acronym> that accompanies the bound book or
from this book's web site:
<ulink url="http://docbook.org/"/>.
</para>
</sect1>

<sect1 id="pref-getexamples">
<title>Getting Examples from This Book</title>
<para>
All of the examples are included on the <acronym>CD-ROM</acronym> and
online at the book's web site.  You can get the most up-to-date
information about this book from the web site: <ulink
url="http://docbook.org/">http://docbook.org/</ulink>.</para>
</sect1>

<sect1 id="pref-getdocbook">
<title>Getting DocBook</title>
<para>
The DocBook &DTD; is included <link linkend="app-cdrom-docbook">on the
<acronym>CD-ROM</acronym></link>. You can get the most up-to-date
version and information about DocBook from the DocBook web page:
<ulink url="http://www.oasis-open.org/docbook/">http://www.oasis-open.org/docbook/</ulink>.</para>
</sect1>

<sect1 id="pref-req-comments">
<title>Request for Comments</title>
<para>
Please help us improve future editions of this book by reporting any
errors, inaccuracies, bugs, misleading or confusing statements, and
plain old typos that you find. An online errata list is maintained at
<ulink
url="http://docbook.org/tdg/errata.html">http://docbook.org/tdg/errata.html</ulink>.
Email your bug reports and comments to us at <ulink role="online"
url="mailto:bookcomments@docbook.org">bookcomments@docbook.org</ulink>.</para>
</sect1>
<sect1 id="pref-acknorm">
<title>Acknowledgements from Norm</title>
<para>This book has been in the works for a long
time. It could not have been completed without the help and
encouragement of a lot of people, most especially my wife,
Deborah, who supported me through the long hours and the late
nights.
</para>
<para>
I also want to thank Lenny for collaborating with me and developing
real prose out of my rough outlines, cryptic email messages, and
scribbled notes.</para>
<para>
A number of people contributed technical feedback as this book
was being written, in particular Terry Allen and Eve Maler. I
owe most of what I know about &SGML; to them, and to the other
members of the Davenport Group who answered all my questions so
many years ago, especially Jon Bosak, Eduardo Guttentag, and
Murray Maloney. Paul Prescod, Mark Galassi, and Dave Pawson also
provided invaluable feedback on the technical review draft. It's
a better book because of them.
</para>
</sect1>
<sect1 id="pref-acklen">
<title>Acknowledgements from Lenny</title>
<para>My gratitude goes back to Dale Dougherty and Terry Allen, who
long ago encouraged me and the production department at O'Reilly to learn
&SGML;; and to Lar Kaufman, who also made large contributions to my 
knowledge and appreciation of &SGML;. But my greatest debt of thanks goes to 
Norm for all that he patiently taught me about DocBook, and for his
supreme graciousness in keeping me a part of this project. 
</para>
</sect1>
<sect1 id="pref-ackboth">
<title>Acknowledgements from Norm and Lenny</title>
<para>
Thanks finally to the great people at O'Reilly who encouraged us to
write it (Frank Willison and Sheryl Avruch), agreed to edit it
(Frank), helped design it (Alicia Cech, who worked on the interior
design, and Edie Freeman, who designed the cover), proofed and
produced it (Chris Maden, Madeline Newell, and David Futato), and
indexed it (Ellen Troutman).
</para>
</sect1>
</preface>

<!--
Local Variables:
mode:sgml
sgml-parent-document: ("book.sgm" "preface")
End:
-->