DocBook 5 68
frisket writes "Definitive guides by the authors or maintainers of software systems tend to have the edge over other documentation because of the insight they provide. DocBook 5 — The Definitive Guide comes well up to scratch. DocBook has long been the de facto standard for computer system documentation in XML (and SGML before that), and Norm Walsh has revised and updated both the language and the documentation in a concise and valuable form, usable both by beginners and by tech doc experts." Read on for the rest of frisket's review.
DocBook is a rich XML vocabulary, primarily for the documentation of software systems. It provides markup both for the structure of your documents and for the descriptive detail of your writing, to an extent that few other XML systems match. Like XML itself, DocBook's popularity rests on its robustness, scope, and extensibility; and Walsh makes it clear that the Technical Committee has tried hard to balance stability and adaptability in releasing a new major version which does have a few backward-incompatible changes.
| DocBook 5: The Definitive Guide | |
| author | Norman Walsh |
| pages | 560 |
| publisher | O'Reilly in conjunction with XML Press |
| rating | 9/10 |
| reviewer | frisket |
| ISBN | 9780596805029 |
| summary | Examines and catalogs the entirety of the DocBook specification. |
This is a reference book, so the initial chapters (1-5) are short (70 pages) but full of clear explanations of how DocBook works, what it does, and how to use it. Part II is 400 pages, covering every element type in the language, with a detailed description of what it is for, how and where to use it, and how it interacts with everything else. Both for the beginner and the expert, these descriptions are the key to effective use, and Walsh's explanations are clear and comprehensive.
For those of you who have been using DocBook in earlier incarnations, the changes are not deal-breakers, and many of them are welcome rationalizations of the way things have grown organically over the years. It still walks like a duck and quacks like a duck (and the book still has a duck on the cover), so it immediately feels like the same format that you're used to — the changes to element types are relatively few. Chapter 1 (Getting Started) has a brief history, a summary of the changes, and an explanation of the namespace and availability.
If you've never used DocBook before, its structure will still be familiar: in Chapter 2 (Creating DocBook Documents) Walsh explains the division of reference material like books, articles, and manuals into chapters, sections, and subsections, with all the conventional features like lists, figures, tables, and references, as well as the technically-oriented features like equations, programming constructs, interface descriptions, and code samples.
There is help in Chapter 3 (Validation) for those who construct or generate DocBook documents without the use of an XML editor (or even with them: more on editors below). The most common problems with misplaced markup (and the error messages they create) are clearly explained with examples.
Chapter 4 (Publishing) very briefly explains the role of stylesheets (CSS, XSL, and XQuery) in displaying and transforming your documents to other formats, but as these all have their own books and manuals, this book doesn't go into them in any detail.
Customizing DocBook is fairly commonplace, either to avoid the need to commit tag abuse, or to extend its structure into other fields (I added a new element type for typographical examples for my book on LaTeX, and it only took a few minutes). Chapter 5 provides some rules and explanation of customization layers and modularity for those who design schemas and DTDs.
The five Appendixes cover Installation, Variants, Resources, Interchange, and the GNU Free Documentation License — yes, you can read the whole thing online at docbook.org, for which Tim, Norm, and many others are to be thanked. It is a rare publisher who groks the need to be able to point someone at a reference, or quote it in email or a tweet, where a paper copy doesn't cut the mustard.
There isn't anything here about actually using an XML editor or about how to choose one. Editors do of course all come with their own documentation (much of it written using DocBook) and editor selection can be a complex business. However, there is a list of some common tools in Appendix C (Resources). Editors are a minefield, as my own research into the usability of editing software for structured documents is showing, so I can understand the omission, but some pointers to editor resources would have been useful.
The chapter on Publishing is useful for those who haven't been in the publication process before, but it could have emphasized more the need for accuracy and consistency. Experienced technical authors know this, but many other writers don't see the need for it, assuming that the publisher (or some elf) will automagically heal everything before publication. DocBook 5 and this book will help enormously, but author-edited documents sometimes unwittingly misuse or abuse the markup, no matter how exhaustive the manuals.
If you write computer documentation, or anything related to it, from a conference paper to a thesis to a book, DocBook 5 is probably what you should use if you want the document to survive and to be usable and reusable; and this is the book to help you do it.
You can purchase DocBook 5: The Definitive Guide from amazon.com. Slashdot welcomes readers' book reviews -- to see your own review here, read the book review guidelines, then visit the submission page.
Re:DocBook - like HTML 1.0, only dumber (Score:3, Informative)
One of the big reasons is that HTML lacks semantic meaning beyond simple paragraph constructs. Documentation-oriented markup languages (of which I'm more familiar with DITA) and schemas can seem arbitrarily complicated to a casual observer, granted; but having an identifier that clarifies "this" paragraph being an instruction that should be executed by the user, and "that" paragraph being merely an example can allow for some rules-based (automated) processing to exist between authorship and production that wouldn't be possible lacking some notion of the semantic purposes of a random collection of raw paragraphs.
Re:Got a link for that? (Score:2, Informative)
Re:DocBook DITA (Score:2, Informative)
I've used both DocBook and DITA. While you can do the same jobs with both of them, DocBook is better, in my experience, for linear documents. while DITA seems to work well for non-linear stuff. DITA also uses topic maps, which can be hard for people to understand.
Docbook (Score:3, Informative)
I have some experience with Docbook, although probably not enough to qualify as an expert. From what I've seen so far:
Pro:
1. Generating pdf, html and (sometimes) man pages from a single source document. This is probably the biggest single win for Docbook.
2. Combining parts of documents with xinclude. If you have four documents of different types which need to contain the same introductory description of a tool (say) or a synopsis of command arguments (book, man page, short article, comprehensive encyclopedia, etc...) you can write the description once in one document and xinclude that specific piece of the document in other documents.
Cons:
1. Toolchain. TeX distributions get this right - install texlive with all the packages and you're done - you can handle any LaTeX document. For Docbook, it's a struggle to figure out what you NEED, never mind how to install it. Once you get it worked out you can integrate it into your build system and forget it, but it takes a while to get there.
2. You need to learn a lot of languages to customize the look of your output documents, and it's not exactly for the faint of heart. I suppose this is kind of a wash between TeX and Docbook, since both don't invite casual tinkering with the look of output, but it's a bit scary. I believe the Firebird RDBMS manual is an example.
3. Finding the "right" tags for what you're trying to do. Price of doing business of course, but there are a LOT of tags to sort through.
LaTeX of course mops the floor with Docbook when it comes to things like mathematics or pstricks, but to be fair about it that's not what Docbook was intended for.