Slashdot Mirror
DocBook 5
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 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.
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.
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.
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.
"I added a new element type for typographical examples for my book on LaTeX, and it only took a few minutes."
Why are you using DocBook for a book on LaTeX?
DocBook is being used for what HTML was originally intended - technical publications. Why not just use HTML? It even supports pictures!
If everyone would just use the sensible choice: EMACS Vi Notepad Pico!
Best Slashdot Co
It's been so long since I visited the bookstore, I forget where it's at. Is DocBook 5 online?
Oh here it is: www.isohunt.com
"I disapprove of what you say, but I will defend to the death your right to say it." - historian Evelyn Beatrice Hall
Does docbook finally have a usable solution for embedding mathematics?
MathML is a hyperverbose turd, especially if you're used to a reasonable markup language like LaTeX.
XML (and SGML before it) is a meta language. From that you derive a description language for the specific use. HTML meets the needs for an on-line presentation of information. HTML is not designed and does not work well for printed materials. DocBook is designed to be used for multiple ways of presenting information and has the features for books and other printed media.
To use a bad analogy, think of XML and C. You can write the "hello world" example in C, but it doesn't replace a database application written in C. C can be used for big or small applications. XML can be used for relatively simple description languages (such as HTML) or very rich description languages for large, complex documents (such as DocBook).
I guess not.
The subtitle "...The Definitive Guide" means this book is for specialists that work with the DocBook publication tag language.
The information in this book isn't for the user of the word processor or editor program.
DocBook is a syntax and tag language and this is a book for people who work with the tag language.
DocBook is probably the absolutely worst document writing format I have ever had the displeasure of working with. It seems to have been born in some deranged xml-lovers wet dream in which "documents" are "self-documenting," semantic structure is more important than content and structure is kept separate from presentation. You know all those generally good ideas that become very dangerous when taken to far, which DocBook exemplifies. The more xml the better, seem to have been their guiding principle. In HTML, P is the tag for paragraphs, not so in DocBook, guess P wasn't descriptive enough so it had to be PARA instead. In HTML, to create a preformatted block you often use PRE. Well obviously that was to simple for DocBook so you have to nest two tags INFORMALEXAMPLE PROGRAMLISTING source code /PROGRAMLISTING /INFORMALEXAMPLE.
Maybe you are asking, who the hell came up with the INFORMALEXAMPLE tag? Well in DocBook you can not just say "give me a block with fixed-width font" you have to be "semantic" because you must separate presentation from structure. This is the reason why the maintainers of the DocBook standard has to continuously invent new tags for use cases they didn't think of. For example, there are all these tags for describing different programming language identifiers: KEYWORD, FUNCTION, CLASSNAME, STRUCTNAME, TOKEN, PROPERTY, TYPE.. etc. They all make it so the word within the tags are formatted using italic text. But what if the programming language you are writing about in the text has a different concept not covered by DocBooks standardized tags? Then you're out of luck. You either cheat and use a different tag which happen to produce the same presentational italicized text you wan't or you submit an enhancement proposal to DocBook and wait for them to standardize your new tag. If you choose the former, you quickly realize that your carefully marked up DocBook text is nothing more than glorified HTML, with retardedly verbose tag names, in the latter case you will never complete your documentation because there will always be tags you'll need that you can't have.
Football Odds
DocBook is being used for what HTML was originally intended - technical publications.
True, DocBook is used mainly for technical publications. Not true, HTML was intended for implementing the hypertext (that's why HT is part of the name) and not specifically for technical publications.
Why not just use HTML? It even supports pictures!
Because DocBook provides much more meaningful elements for technical publications than HTML. Because DocBook is intended mainly for documents published on paper, while HTML is intended for Web pages displayed in a browser. There is a reason why nobody uses HTML for technical publications.
The real question must be, why use DocBook when we already have DITA? While both formats are designed specifically for technical publications, DITA is superior.
How does reStructuredText stack up against DocBook? It's on my "look into later" list for technical documentation. My first impression of it was pretty good, especially combined with the Sphinx document generator.
"already have DITA"
That implies the reverse order of invention as actually occurred. DITA might be superior, I have no idea ... haven't really used either. DocBook seems a bit more actively developed though, no official RelaxNG schema for DITA for instance.
Anyone who has participated in a signifigant document effort or a multiple authorship project understands the need for the DocBook XML schema. To often "authors" depend on MS Word formatting styles which just don't cut it. Worse yet, authors also don't bother to use styles and just format each element in their document individually, leaving someone else to figure out what they meant. DocBook helps facilitate communication between the authoring process and the publishering process.
Just wait until you need to generate HTML help, Text file documentation, a web page manual, and a printed PDF of the same core documentation. The single-source design of DocBook will be much better appreciated then, if you learn how to use it.
I couldn't agree with ebuck more!!!
There's a reason why GNOME docs are moving away from DocBook...
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.
Please be a little indulgent with your self and do not write in *DocBooK or XML: soon you will just stop writing becouse of the pain.
Use something like AsciiDoc: http://www.methods.co.nz/asciidoc/ then convert in DocBook or straight in any of the others supported output languages.
They are switching to something more domain specific though, not to some general alternative.
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.
"I object to doing things that computers can do." -- Olin Shivers, lispers.org
Wait a second... you're writing a book on LaTeX using DocBook?
Does not compute...
Shouldn't you be using LaTeX to write a book on LaTeX?
The real question must be, why use DocBook when we already have DITA
DITA is descended from DocBook in many ways. DITA is an architecture with which a willing participant can, if she tries long and hard enough, come up with a system that can be used for authoring large series of technical documents.
DocBook works right out of the box.
It's actually because good XML editors are expensive. The free ones are designed for XML experts who know all about markup: there are no usable XML editors (free or non-free) for non-experts in markup, as I showed last year.
It's an interest bit of research you are plugging ... but Gnome is switching to Mallard, which is XML+RelaxNG, not switching away from XML.