File: ch00.html

package info (click to toggle)
xae 1.0beta6-5
links: PTS
area: main
in suites: sarge
size: 28,184 kB
ctags: 12,210
sloc: java: 27,149; xml: 20,864; lisp: 12,921; perl: 1,054; sh: 237; makefile: 169
file content (859 lines) | stat: -rw-r--r-- 15,702 bytes
parent folder | download | duplicates (2)
<HTML
><HEAD
><TITLE
>Preface</TITLE
><META
NAME="GENERATOR"
CONTENT="Modular DocBook HTML Stylesheet Version 1.45"><LINK
REL="HOME"
TITLE="DocBook"
HREF="docbook.html"><LINK
REL="PREVIOUS"
TITLE="DocBook"
HREF="docbook.html"><LINK
REL="NEXT"
TITLE="Introduction"
HREF="part1.html"><LINK
REL="STYLESHEET"
TYPE="text/css"
HREF="dbtdg.css"></HEAD
><BODY
CLASS="PREFACE"
BGCOLOR="#FFFFFF"
TEXT="#000000"
LINK="#0000FF"
VLINK="#840084"
ALINK="#0000FF"
><DIV
CLASS="NAVHEADER"
><TABLE
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TH
COLSPAN="3"
ALIGN="center"
>DocBook: The Definitive Guide</TH
></TR
><TR
><TD
WIDTH="10%"
ALIGN="left"
VALIGN="bottom"
><A
HREF="docbook.html"
>Prev</A
></TD
><TD
WIDTH="80%"
ALIGN="center"
VALIGN="bottom"
></TD
><TD
WIDTH="10%"
ALIGN="right"
VALIGN="bottom"
><A
HREF="part1.html"
>Next</A
></TD
></TR
></TABLE
><HR
ALIGN="LEFT"
WIDTH="100%"></DIV
><DIV
CLASS="PREFACE"
><H1
><A
NAME="PREFACE"
>Preface</A
></H1
><DIV
CLASS="TOC"
><DL
><DT
><B
>Table of Contents</B
></DT
><DT
>1. <A
HREF="ch00.html#AEN64"
>Why Read This Book?</A
></DT
><DT
>2. <A
HREF="ch00.html#AEN96"
>This Book's Audience</A
></DT
><DT
>3. <A
HREF="ch00.html#AEN110"
>Organization of This Book</A
></DT
><DT
>4. <A
HREF="ch00.html#AEN203"
>Conventions Used in This Book</A
></DT
><DT
>5. <A
HREF="ch00.html#AEN221"
>Getting This Book</A
></DT
><DT
>6. <A
HREF="ch00.html#AEN228"
>Getting Examples from This Book</A
></DT
><DT
>7. <A
HREF="ch00.html#AEN233"
>Getting DocBook</A
></DT
><DT
>8. <A
HREF="ch00.html#PREF-REQ-COMMENTS"
>Request for Comments</A
></DT
><DT
>9. <A
HREF="ch00.html#AEN245"
>Acknowledgements from Norm</A
></DT
><DT
>10. <A
HREF="ch00.html#AEN251"
>Acknowledgements from Lenny</A
></DT
><DT
>11. <A
HREF="ch00.html#AEN256"
>Acknowledgements from Norm and Lenny</A
></DT
></DL
></DIV
><P
>DocBook provides a system for writing structured documents using
<SPAN
CLASS="ACRONYM"
>SGML</SPAN
> or <SPAN
CLASS="ACRONYM"
>XML</SPAN
>. 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 an <SPAN
CLASS="ACRONYM"
>SGML</SPAN
> document type definition (<SPAN
CLASS="ACRONYM"
>DTD</SPAN
>). An
<SPAN
CLASS="ACRONYM"
>XML</SPAN
> version is available now, and an official <SPAN
CLASS="ACRONYM"
>XML</SPAN
> release is in
the works.  Because it is a large and robust <SPAN
CLASS="ACRONYM"
>DTD</SPAN
>, 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 "out of the box" 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 <SPAN
CLASS="ACRONYM"
>DTD</SPAN
>. Dozens of organizations use
DocBook for millions of pages of documentation, in various print
and online formats, worldwide.</P
><DIV
CLASS="SECT1"
><H1
CLASS="SECT1"
><A
NAME="AEN64"
>1. Why Read This Book?</A
></H1
><P
>This book is designed to be the clear, concise, normative reference to
the DocBook <SPAN
CLASS="ACRONYM"
>DTD</SPAN
>. This book is the official documentation for the
DocBook <SPAN
CLASS="ACRONYM"
>DTD</SPAN
>.</P
><P
>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:</P
><P
></P
><UL
><LI
><P
>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.</P
></LI
><LI
><P
>How to write DocBook documents. Where should you start
and what should you do?</P
></LI
><LI
><P
>Parsing and validation. After you've written a
document, how can you tell if it really conforms to the DocBook
<SPAN
CLASS="ACRONYM"
>DTD</SPAN
>?</P
></LI
><LI
><P
>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.</P
></LI
><LI
><P
>Customizing the <SPAN
CLASS="ACRONYM"
>DTD</SPAN
>. Many individuals and
corporations have standardized on the DocBook <SPAN
CLASS="ACRONYM"
>DTD</SPAN
>. Whether your
subject matter is computer software documentation or not,
we explain how you can write a "customization layer" to
tailor DocBook explicitly for your information.</P
></LI
><LI
><P
>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.</P
></LI
><LI
><P
>Stylesheets. Several standard stylesheet
languages are briefly described.</P
></LI
><LI
><P
><SPAN
CLASS="ACRONYM"
>XML</SPAN
> compatability. We outline all of the points that
you'll need to consider
as you or your organization contemplate <SPAN
CLASS="ACRONYM"
>XML</SPAN
> for authoring, publishing, or
both.</P
></LI
><LI
><P
>Additional resources and a
<SPAN
CLASS="ACRONYM"
>CD-ROM</SPAN
>. 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 <SPAN
CLASS="ACRONYM"
>CD-ROM</SPAN
>.</P
></LI
></UL
></DIV
><DIV
CLASS="SECT1"
><H1
CLASS="SECT1"
><A
NAME="AEN96"
>2. This Book's Audience</A
></H1
><P
>We expect that most readers will have some familiarity with <SPAN
CLASS="ACRONYM"
>SGML</SPAN
> or
<SPAN
CLASS="ACRONYM"
>XML</SPAN
>. Even if your experience goes no farther than writing a few
<SPAN
CLASS="ACRONYM"
>HTML</SPAN
> pages, you're probably in good shape.  Although we provide an
introduction to <SPAN
CLASS="ACRONYM"
>SGML</SPAN
>, <SPAN
CLASS="ACRONYM"
>XML</SPAN
>, and structured markup, this book may
not suffice as your only tutorial about <SPAN
CLASS="ACRONYM"
>SGML</SPAN
> and <SPAN
CLASS="ACRONYM"
>XML</SPAN
>. This
depends, naturally, on your needs and experience.  For a list of some
other good resources, consult <A
HREF="appd.html"
>Appendix D</A
>.</P
><P
>Some sections of this book describe tools and applications. For
the most part, these are Microsoft Windows or <SPAN
CLASS="ACRONYM"
>UNIX</SPAN
> applications,
although there's nothing about DocBook that makes it unsuitable for the
Mac or <SPAN
CLASS="ACRONYM"
>VM/CMS</SPAN
> or any other operating system of your
choice.</P
></DIV
><DIV
CLASS="SECT1"
><H1
CLASS="SECT1"
><A
NAME="AEN110"
>3. Organization of This Book</A
></H1
><P
>This book is divided into three parts. <I
CLASS="CITETITLE"
>Part I: Introduction</I
> is an introduction to structured markup and DocBook:</P
><P
></P
><DL
><DT
><B
><A
HREF="ch01.html"
>Chapter 1</A
></B
></DT
><DD
><P
>A quick introduction to structured markup.</P
></DD
><DT
><B
><A
HREF="ch02.html"
>Chapter 2</A
></B
></DT
><DD
><P
>How to make DocBook documents.</P
></DD
><DT
><B
><A
HREF="ch03.html"
>Chapter 3</A
></B
></DT
><DD
><P
>Parsing and validating DocBook documents.</P
></DD
><DT
><B
><A
HREF="ch04.html"
>Chapter 4</A
></B
></DT
><DD
><P
>How to publish DocBook documents.</P
></DD
><DT
><B
><A
HREF="ch05.html"
>Chapter 5</A
></B
></DT
><DD
><P
>How to customize DocBook.</P
></DD
></DL
><P
><I
CLASS="CITETITLE"
>Part II: Reference</I
>
is a complete reference to every element and parameter entity in
the DocBook <SPAN
CLASS="ACRONYM"
>V3.1</SPAN
> <SPAN
CLASS="ACRONYM"
>DTD</SPAN
>.</P
><P
></P
><DL
><DT
><B
><A
HREF="refelem.html"
>Reference I, <I
>DocBook Element Reference</I
></A
></B
></DT
><DD
><P
>A reference guide to the DocBook elements.</P
></DD
><DT
><B
><A
HREF="refpent.html"
>Reference II, <I
>DocBook Parameter Entity Reference</I
></A
></B
></DT
><DD
><P
>A reference guide to the DocBook parameter entities.</P
></DD
><DT
><B
><A
HREF="refchar.html"
>Reference III, <I
>DocBook Character Entity Reference</I
></A
></B
></DT
><DD
><P
>A reference guide to the character entities declared in DocBook.</P
></DD
></DL
><P
><I
CLASS="CITETITLE"
>Part III: Appendixes</I
> discusses other resources:</P
><P
></P
><DL
><DT
><B
><A
HREF="appa.html"
>Appendix A</A
></B
></DT
><DD
><P
>How to install DocBook, Jade, and the stylesheets.</P
></DD
><DT
><B
><A
HREF="appb.html"
>Appendix B</A
></B
></DT
><DD
><P
>DocBook as <SPAN
CLASS="ACRONYM"
>XML</SPAN
>.</P
></DD
><DT
><B
><A
HREF="appc.html"
>Appendix C</A
></B
></DT
><DD
><P
>A guide to DocBook versions, including a summary of the features
expected in future releases.</P
></DD
><DT
><B
><A
HREF="appd.html"
>Appendix D</A
></B
></DT
><DD
><P
>Other resources.</P
></DD
><DT
><B
><A
HREF="appe.html"
>Appendix E</A
></B
></DT
><DD
><P
>What's on the <SPAN
CLASS="ACRONYM"
>CD</SPAN
>?</P
></DD
><DT
><B
><A
HREF="appf.html"
>Appendix F</A
></B
></DT
><DD
><P
>An interchange checklist. Things to consider when you're sharing
DocBook documents with others.</P
></DD
><DT
><B
><A
HREF="quickref.html"
>Appendix G</A
></B
></DT
><DD
><P
>A Quick Reference to the elements in DocBook.</P
></DD
></DL
><P
>At the end of this book you'll find a <A
HREF="dbgloss.html"
>Glossary</A
> and an
<A
HREF="dbindex.html"
>Index</A
>.</P
></DIV
><DIV
CLASS="SECT1"
><H1
CLASS="SECT1"
><A
NAME="AEN203"
>4. Conventions Used in This Book</A
></H1
><P
></P
><UL
><LI
><P
><TT
CLASS="SGMLTAG"
>Garamond Book</TT
> is used for element and
attribute names.</P
></LI
><LI
><P
><TT
CLASS="LITERAL"
>Constant Willison</TT
> is used for program examples, attribute value
literals, start- and end-tags, and source code example text.</P
></LI
><LI
><P
><TT
CLASS="REPLACEABLE"
><I
>Constant Willison Oblique</I
></TT
> is used for
<SPAN
CLASS="QUOTE"
>"replaceable"</SPAN
> text or variables.  Replaceable text is text
that describes something you're supposed to type, like a
<TT
CLASS="REPLACEABLE"
><I
>filename</I
></TT
>, in which the word
"filename" is a placeholder for the actual filename.</P
></LI
><LI
><P
><TT
CLASS="FILENAME"
>Garamond Italic</TT
> is used for filenames and (in the print version
of the book) <SPAN
CLASS="ACRONYM"
>URL</SPAN
>s.</P
></LI
></UL
></DIV
><DIV
CLASS="SECT1"
><H1
CLASS="SECT1"
><A
NAME="AEN221"
>5. Getting This Book</A
></H1
><P
>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 <SPAN
CLASS="ACRONYM"
>SGML</SPAN
> document, and in <SPAN
CLASS="ACRONYM"
>HTML</SPAN
>,
either on the <SPAN
CLASS="ACRONYM"
>CD</SPAN
> that accompanies the bound book or
from this book's web site: <A
HREF="http://docbook.org/"
TARGET="_top"
>http://docbook.org/</A
>.</P
></DIV
><DIV
CLASS="SECT1"
><H1
CLASS="SECT1"
><A
NAME="AEN228"
>6. Getting Examples from This Book</A
></H1
><P
>All of the examples are included on the <SPAN
CLASS="ACRONYM"
>CD-ROM</SPAN
> and
online at the book's web site.  You can get the most up-to-date
information about this book from the web site: <A
HREF="http://docbook.org/"
TARGET="_top"
>http://docbook.org/</A
>.</P
></DIV
><DIV
CLASS="SECT1"
><H1
CLASS="SECT1"
><A
NAME="AEN233"
>7. Getting DocBook</A
></H1
><P
>The DocBook <SPAN
CLASS="ACRONYM"
>DTD</SPAN
>, v3.1, is included <A
HREF="appe.html#APP-CDROM-DOCBOOK"
> on the
<SPAN
CLASS="ACRONYM"
>CD-ROM</SPAN
></A
>. You can get the most up-to-date
version and information about DocBook from the DocBook web page:
<A
HREF="http://www.oasis-open.org/docbook/"
TARGET="_top"
>http://www.oasis-open.org/docbook/</A
>.</P
></DIV
><DIV
CLASS="SECT1"
><H1
CLASS="SECT1"
><A
NAME="PREF-REQ-COMMENTS"
>8. Request for Comments</A
></H1
><P
>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
<A
HREF="http://docbook.org/tdg/errata.html"
TARGET="_top"
>http://docbook.org/tdg/errata.html</A
>.
Email your bug reports and comments to us at <A
HREF="mailto:bookcomments@docbook.org"
TARGET="_top"
>bookcomments@docbook.org</A
>.</P
></DIV
><DIV
CLASS="SECT1"
><H1
CLASS="SECT1"
><A
NAME="AEN245"
>9. Acknowledgements from Norm</A
></H1
><P
>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.</P
><P
>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.</P
><P
>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 <SPAN
CLASS="ACRONYM"
>SGML</SPAN
> 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.</P
></DIV
><DIV
CLASS="SECT1"
><H1
CLASS="SECT1"
><A
NAME="AEN251"
>10. Acknowledgements from Lenny</A
></H1
><P
>My gratitude goes back to Dale Dougherty and Terry Allen, who
long ago encouraged me and the production department at O'Reilly to learn
<SPAN
CLASS="ACRONYM"
>SGML</SPAN
>; and to Lar Kaufman, who also made large contributions to my 
knowledge and appreciation of <SPAN
CLASS="ACRONYM"
>SGML</SPAN
>. 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. </P
></DIV
><DIV
CLASS="SECT1"
><H1
CLASS="SECT1"
><A
NAME="AEN256"
>11. Acknowledgements from Norm and Lenny</A
></H1
><P
>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).</P
></DIV
></DIV
><DIV
CLASS="NAVFOOTER"
><HR
ALIGN="LEFT"
WIDTH="100%"><TABLE
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
><A
HREF="docbook.html"
>Prev</A
></TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="docbook.html"
>Home</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
><A
HREF="part1.html"
>Next</A
></TD
></TR
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
>DocBook</TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
>&nbsp;</TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
>Introduction</TD
></TR
></TABLE
></DIV
><P
><A
HREF="ln41.html"
>Copyright</A
> &copy; 1999 O'Reilly &amp; Associates, Inc. All rights reserved.</P
></BODY
></HTML
>