Forgot your password?
typodupeerror
Image

DocBook 5 68

Posted by samzenpus
from the read-all-about-it dept.
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 discussion has been archived. No new comments can be posted.

DocBook 5

Comments Filter:
  • by justleavealonemmmkay (1207142) on Wednesday August 18, 2010 @02:33PM (#33291816)

    one word: chapters.

  • DocBook is horrible (Score:1, Interesting)

    by bjourne (1034822) on Wednesday August 18, 2010 @03:15PM (#33292364) Homepage Journal

    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.

  • by Manhigh (148034) on Wednesday August 18, 2010 @04:45PM (#33293766)

    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.

The most delightful day after the one on which you buy a cottage in the country is the one on which you resell it. -- J. Brecheux

Working...