Preface

$Revision: 1.2 $

$Date: 2002/12/29 19:37:30 $

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 “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 DTD. Dozens of organizations use DocBook for millions of pages of documentation, in various print and online formats, worldwide.

Why Read This Book?

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.

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:

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.
How to write DocBook documents. Where should you start and what should you do?
Parsing and validation. After you've written a document, how can you tell if it really conforms to the DocBook DTD?
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.
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 “customization layer” to tailor DocBook explicitly for your information.
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.
Stylesheets. Several standard stylesheet languages are briefly described.
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.
Additional resources and a CD-ROM. 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 CD-ROM.

This Book's Audience

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 Appendix D, Resources.

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 VM/CMS or any other operating system of your choice.

Organization of This Book

This book is divided into three parts. Part I: Introduction is an introduction to structured markup and DocBook:

Chapter 1, Getting Started with SGML/XML: A quick introduction to structured markup.
Chapter 2, Creating DocBook Documents: How to make DocBook documents.
Chapter 3, Parsing DocBook Documents: Parsing and validating DocBook documents.
Chapter 4, Publishing DocBook Documents: How to publish DocBook documents.
Chapter 5, Customizing DocBook: How to customize DocBook.

DocBook Element Reference: A reference guide to the DocBook elements.
DocBook Parameter Entity Reference: A reference guide to the DocBook parameter entities.
DocBook Character Entity Reference: A reference guide to the character entities declared in DocBook.

Part III: Appendixes discusses other resources:

Appendix A, Installation: How to install DocBook, Jade, and the stylesheets.
Appendix B, DocBook and XML: DocBook as XML.
Appendix C, DocBook Versions: A guide to DocBook versions, including a summary of the features expected in future releases.
Appendix D, Resources: Other resources.
Appendix E, What's on the CD-ROM?: What's on the CD?
Appendix F, Interchanging DocBook Documents: An interchange checklist. Things to consider when you're sharing DocBook documents with others.
Appendix G, DocBook Quick Reference: A Quick Reference to the elements in DocBook.

At the end of this book you'll find a Glossary and an Index.

Conventions Used in This Book

Garamond Book is used for element and attribute names.
Constant Willison is used for program examples, attribute value literals, start- and end-tags, and source code example text.
Constant Willison Oblique is used for “replaceable” text or variables. Replaceable text is text that describes something you're supposed to type, like a filename, in which the word “filename” is a placeholder for the actual filename.
Garamond Italic is used for filenames and (in the print version of the book) URLs.
URLs are presented in parentheses after the name of the resource they describe in the print version of the book.

Getting This Book

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 CD that accompanies the bound book or from this book's web site: http://docbook.org/.

Getting Examples from This Book

All of the examples are included on the CD-ROM and online at the book's web site. You can get the most up-to-date information about this book from the web site: http://docbook.org/.

Getting DocBook

The DocBook DTD is included on the CD-ROM. You can get the most up-to-date version and information about DocBook from the DocBook web page: http://www.oasis-open.org/docbook/.

Request for Comments

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 http://docbook.org/tdg/errata.html. Email your bug reports and comments to us at bookcomments@docbook.org.

Acknowledgements from Norm

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.

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.

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.

Acknowledgements from Lenny

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.

Acknowledgements from Norm and Lenny

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).