DocBook: The Definitive Guide

by Norman Walsh, Leonard Muellner

The Definitive Guide is the complete and official documentation of the DocBook Document Type Definition (DTD) and many of its associated tools. DocBook is a system for writing structured documents using SGML and XML. It provides all the elements you'll need for technical documents of all kinds. A number of computer companies use DocBook for their documentation, as do several Open Source documentation groups, including the Linux Documentation Project (LDP). With the consistent use of DocBook, these groups can readily share and exchange information. With an XML-enabled browser, DocBook documents are as accessible on the Web as in print. The Definitive Guide was written by Norman Walsh, the author of the XML implementation of the DocBook DTD; and Leonard Muellner, the manager of O'Reilly & Associates' Production Tools Group. In this book, you'll In addition, the CDROM Oasis, the organization that is the official maintainer of the DocBook DTD, has identified the Definitive Guide as the official documentation for the DocBook DTD.

Genres: Computers, Programming, Writing, Technical, Reference

644 pages, Paperback

First published October 28, 1999

Reviews

[Jan Jaap]

I'm quite happy with this book. Complex stuff I didn't understand explained. Rather dated but still.

https://tdg.docbook.org/
https://docbook.org/schemas/
https://so.nwalsh.com/

https://www.amazon.com/_/dp/059680502... DocBook5 (2010)

Found it at Utrecht Centraal in the Boekwissel.

[Kai Weber · Rating 2 out of 5]

A reference book as dry and redundant as can be.

[Robert · Rating 4 out of 5]

Note: This book is made freely available on the DocBook site.

First, this book isn't really a book that you read from cover to cover. Only the very beginning has prose, and the rest is provided as a thick database of different documentation tags and their use. Even so, the beginning of this book describes very important thoughts about Technical Documentation and what DocBook tries to accomplish.

Norman Walsh provides a high level summary of what the industry XML schema sets out to do: how to construct a document in a logical and reusable way. It *is* the bible for how to use DocBook elements. Be warned, the book itself has a learning curve, but once you get passed the curve, it becomes indispensable.

== The Good

DocBook The Definitive Guide is just that: Definitive. Even summing all of it's flaws, after using it to author two documents, I considered this book to be the great bible to the specification, and I found myself quickly navigating the reference sections after I figured out its cross referencing system. Before going through the reference section, read very carefully the forward to Part II Reference Elements, and pay special attention to the db. parentheticals, as they provide a cross reference and tag tree requirements.

The detail and examples in the reference section are literally gushing with information on how you can use tags effectively. In fact, I learned how to logically structure a technical manual and learned the lingo of technical writing after reading this book!

== The Bad

=== Examples

DocBook is a huge specification. It's a nightmare to attempt to write your first book in it without having some sort of reference document to go against. Walsh provides several skeleton documents to get things moving, but then quickly rushes into the different element types that can be included. I couldn't help but feel like more examples could have been provided in the first few chapters to help the new guy figure out the construction of the document.

=== Documentation Generation

A common mistake made by individuals is that DocBook is a file format that's ready for publishing / viewing, when in fact it's just a markup language. It depends on a series of tools (called a toolchain) that leads to a documentation pipeline.

In the Appendix, he tersely discusses the DocBook Schema project -- an open source community project -- and how you can use it to construct a documentation pipeline. I feel as though more time should have been spent on this, as it is a very critical element to producing a final product without spending several hours/weeks/months attempting to produce the XSLT sheets to transform the schema to a useable format. While Sagehill has provided a decent set of documentation on this project, I feel as though N. Walsh could have provided more insight to the documentation pipeline in this book.


All in all, if you are going to write in DocBook, this is an essential resource for your desk.

[Ivan · Rating 3 out of 5]

Quite useful.

You can also find it on Google Books, because it's very old.