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.
Wait, what? (Score:1, Insightful)
"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?
Re: (Score:2)
Maybe his book is titled "From LaTex to DocBook: How To Escape From the Asylum"? ~
Re:Wait, what? (Score:4, Insightful)
Or "From the Frypan, into the Fire"?
Re: (Score:2)
Why are you using DocBook for a book on LaTeX?
Because (a) I write in XML as a matter of course, and (b) the book is available online (HTML) as well as PDF (LaTeX), so it made sense to author it in something that could easily be transformed to multiple outputs.
DocBook - like HTML 1.0, only dumber (Score:1)
DocBook is being used for what HTML was originally intended - technical publications. Why not just use HTML? It even supports pictures!
Re: (Score:2)
Not only that, it sounds like a horrible format if you need documentation to write in the documentation language. Just looking at their What is DocBook [docbook.org] page leaves me wondering what the hell it really is...
Re: (Score:2)
Not only that, it sounds like a horrible format if you need documentation to write in the documentation language. Just looking at their What is DocBook [docbook.org] page leaves me wondering what the hell it really is...
Even how to write English is documented in English, so why do you argue that any language which can use itself to document how to make more of itself is bad?
Re: (Score:2)
When writing documentation in word or open office I don't need to read an entire book in how to do it. That's why this bloated design by committee xml language is a complete waste of time. You analogy fails because it's not even slightly related and doesn't at all translate to real life. When typing this comment is wasn't constantly referring to a dictionary.
Re: (Score:1)
If you are one person writing a 50 page document Word may very well be perfect. However, imagine you have 20 people who need to collaborate on keeping a 1000 page documentation set updated.
Now imaginge doing this in Word.
Re: (Score:2)
Google Docs, you fail.
Re: (Score:2)
DocBook is being used for what HTML was originally intended - technical publications. Why not just use HTML? It even supports pictures!
HTML was originally meant as a subset or replacement of SGML. The primary goal was to be able to share documents; technical or not. Tim Berners-Lee's main goal in creating HTML was to have a way to share information easily.
Re: (Score:3, Interesting)
one word: chapters.
Re: (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
Re: (Score:1, Insightful)
"HTML+CSS+CMS > My woefully inadequate understanding of DocBook"
FTFY.
Re: (Score:3, Insightful)
if you want rules-based automated processing, you can do that with html
You can, the same way that you can write a book in PostScript.
But if you want all the internal checks on consistency and effectivity that make a piece of documentation robust and persistent, you probably don't want to do it in HTML and CSS.
Re: (Score:1)
Re: (Score:2)
...some of the elements that are relevant when publishing a *book*; elements for citations, bibliographies, indexing, callouts, glossaries, etc. HTML does not provide these elements.
Earlier versions of HTML did provide a lot of these, but the W3C took 'em all out (deprecated them) becase it was clear that no-one in their right minds would author a complex technical book in HTML.
DocBook DITA (Score:1)
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
Re: (Score:2)
"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.
Re: (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.
Re: (Score:2)
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.
Re: (Score:2)
Of course you can abuse HTML for anything you want...just look at the web :-)
Editors are a minefield (Score:2)
If everyone would just use the sensible choice: EMACS Vi Notepad Pico!
Re: (Score:2)
Only one of those comes with a validating XML editor built in. And, sadly, it only comes with a schema for DocBook 4, though it should be simple enough to update.
Re: (Score:2)
...it only comes with a schema for DocBook 4, though it should be simple enough to update.
Takes all of 30 seconds to download DocBook5, unzip it, and declare it in a new document.
Got a link for that? (Score:1)
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
Re: (Score:2, Informative)
language != application (Score:2)
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
It is for Docbook specialists (Score:1)
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.
Re: (Score:2)
The subtitle "...The Definitive Guide" means this book is for specialists that work with the DocBook publication tag language.
Correct, but not exclusively specialists.
The information in this book isn't for the user of the word processor
Correct: people who use wordprocessors either have a team of expensive editors to format their documents for publication, or are only interested in making it look pretty, rather than correct (and pretty).
or editor program.
Incorrect: the book is for anyone writing technical documents in the field of computing who needs or wants to use XML to do it
DocBook is a syntax and tag language and this is a book for people who work with the tag language.
Yep, either writing, editing, formatting, publishing, archiving, or transforming the document to new target formats.
DocBook is horrible (Score:1, Interesting)
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
Re: (Score:2)
There's a reason why GNOME docs are moving away from DocBook...
Re: (Score:2)
They are switching to something more domain specific though, not to some general alternative.
Re: (Score:2)
Re: (Score:2)
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.
Re:DocBook is horrible (Score:5, Insightful)
My experiences are quite different; DocBook is simply awesome.
If you start selecting tags to make the output look the way you want it to look, you don't understand XML (and subsequently shouldn't be using DocBook).
Any sane documentation project separates the formatting from the content; because, when you need to update the look of the documentation, you don't want to spend days checking each individual document element to determine if it is the correct font, point, weight, etc. Only the novices create documentation that doesn't permit consistent formatting. Using something that goes half way there (inconsistently applied style sheets) eventually leaves you with the same amount of work to make sure your documentation shows as it should. Style sheets may be applied consistently, but you can't know for sure without paying the "verify the whole document" price.
With XML, there is no formatting in the document. All of the formatting is done with the XSL document. If you didn't like the format, layout, font, italics, or whatever of the output documentation, the correct choice was to change the XSL document used to build the output, not to go on a happy hunting DocBook tag search for the tags that made it look how you wanted it.
The fact that you couldn't find the <code> tag but could find the other tags you've mentioned is just depressing, especially when those tags are most often sub-tags of a code tag block.
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.
Re: (Score:3)
Well, to *me* it sounded as if the grandparent understood it well enough -- he just thought it sucked.
Re: (Score:2)
Well, to *me* it sounded as if the grandparent understood it well enough -- he just thought it sucked.
I'm not so sure. It sounded as he still thought it was some kind of programming language, and he clearly believed that the semantics of the element types were irrevocably bound to the formatting that he saw in his application: a common mistake.
Re: (Score:2, Flamebait)
If you start selecting tags to make the output look the way you want it to look, you don't understand XML (and subsequently shouldn't be using DocBook).
Anyone who was some experience writing documentation knows that the main objective is to write beautiful and readable documentation, not choosing the right markup...
The fact that you couldn't find the tag but could find the other tags you've mentioned is just depressing, especially when those tags are most often sub-tags of a code tag block.
The CODE tag is new in DocBook 4.3. Version of jade shipped with Ubuntu 9.10 is 1.2.1 and it does not know about the CODE tag. That's another problem with DocBook, it is a moving target with a standard that moves faster than the tools that support it.
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 doubt most people who express that belief has actually tried to publish the same documentation
Re: (Score:1)
The CODE tag is new in DocBook 4.3. Version of jade shipped with Ubuntu 9.10 is 1.2.1 and it does not know about the CODE tag. That's another problem with DocBook, it is a moving target with a standard that moves faster than the tools that support it.
Don't use the latest version unless you need something only it provides.
DocBook produces PDF by first converting the document to LaTeX
It can do that, but any time I've used DocBook, I've generated the PDF using XSL-FO and FOP. No LaTeX involved.
Re: (Score:2)
If you start selecting tags to make the output look the way you want it to look, you don't understand XML (and subsequently shouldn't be using DocBook).
Anyone who was some experience writing documentation knows that the main objective is to write beautiful and readable documentation, not choosing the right markup...
It's not usually the author's job to do the beautification unless it's for self-publication through Lulu or for internal consumption. Conventional publishing houses have sets of standards governing how things must appear in their series, and the author does not get much chance to influence that except on special occasions.
Any author who is spending more time making it look pretty than actually writing readable, usable text needs firing. And they shouldn't have to spend time choosing the right markup (althou
Re: (Score:2)
There are alternatives. tbook [sourceforge.net] is another xml application that succeeds very well at this. Its author explains in detail why he didn't just use docbook: the main reason is that it forces you to write deeply nested tags to express simple things.
Re: (Score:2)
You say that like it's a bad thing.
Re: (Score:2)
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.
You could use SCREEN /SCREEN.
Re: (Score:2)
It sounds as if you have been seriously damaged by incompetent software, incompetent programmers, incompetent teachers, or incompetent managers, possibly all four.
...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.
Semantic structure usually outlasts content, so in a sense it is more important. If you have ever had to publish someone else's work which was done using a wordprocessor or HTML, you'll know that you do indeed need to separate presentation out to a separately-manageable layer.
[...] 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.
DocBook started around the time that HTML was becoming popular. At that
What about reStructuredText? (Score:1)
Re: (Score:2)
Re:What about reStructuredText? (Score:4, Interesting)
I use Sphinx for all of my Python development and am really happy with it. Autogeneration forces me to write reasonable docstrings into my code, and I'm pretty pleased with the HTML output.
I still think I'd prefer LaTex for large scale, intended-for-print documents, though.
Re: (Score:1)
Thanks for the tip, AsciiDoc looks really good, too.
I don't need all the features of DocBook, as my writing is internal documentation of software operation, api docs and various processes, and usually viewed onscreen. Not books or anything significantly complex.
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.
LaTeX using DocBook? (Score:2)
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?
Re: (Score:2)