DocBook schemas and books

Over the past few evenings, I’ve been trying to catch up on some long overdue DocBook-related tasks.

The Schemas

In addition to DocBook itself, there are four additional customization layers that have, at one time or another, been published on https://docbook.org/:

DocBook Publishers · This is an official work product of the DocBook Technical Committee organized by the DocBook Publishers subcommittee. The last official publication was Publishers 1.0 a customization, I believe, of DocBook V5.0. However, there’s a draft of a version 1.1 floating around, so I’m a little confused about its status. In any event, I’ve updated the customization layer so that it’s (unofficially) a customization of DocBook V5.2b07. For the moment, I’ve left danger in the customization because I believe that Publishers 1.1 includes the other admonitions. I also left formalwrapper in, because that seems likely to be equally useful in Publishers.

Simplified DocBook · This was never an official work product of the technical committee. Back in the 90’s, one often heard the complaint that the problem with DocBook was that it had too many tags, as compared to HTML. Simplified DocBook was an attempt to pare DocBook down to roughly the same size as HTML. I’ve updated Simplified so that it’s a customization of V5.2b07.

DocBook Slides · This was never an official work product of the technical committee. Slides adds a few elements (slides, foil, etc.) for producing presentations. There’s a small community of folks who use it. I’ve updated Slides so that it’s a customization of V5.2b07.

DocBook Website · Publishing a book or article or other bit of narrative prose on the web is straightforward. Representing a non-linear collection of web pages is a bigger challenge. Website adds a few elements (webpage, mostly, and some conventions for page metadata) in an attempt to support building websites with DocBook. It’s the source for https://nwalsh.com/ and a few other sites that I made. I have no idea if it caught on more widely than that. I’ve updated Website so that it’s a customization of V5.2b07.

The Books

DocBook: The Definitive Guide (an official reference for DocBook V4.5) was published by O’Reilly back in the late nineties. In the ’aughts, a version was published for DocBook 5.0. (I’d link to the O’Reilly catalog but it seems to be offline due to fires in California.)

The online version of the book attempts to track the changes made by the technical committee. I spent some time recently bringing it up-to-date with respect to DocBook V5.2. (Bob Stayton has provided some very valuable review comments, especially with respect to the new assembly work; I’m unclear if I’ve correctly incorporated all of them.)

There are online versions of the books for derivative schemas as well. They’ve languished for a while in various states of completion. In the course of cleaning up the repository, I fixed the most egregious errors in them and arranged for them to be published regularly as well.

You can find them all at tdg.docbook.org.

The Sources

The master branch on the docbook repository now reflects all of the schema changes described above. (I confess, I accidentally merged a pull request back to master; I decided not to try to undo that. After DocBook 5.2 is officially published by the TC, I’ll look at sorting this out.)

The book sources are currently on the docbook-5.2 branch of the defguide repository. I’m tempted to merge those back on to master as well, just for consistency.

Questions, comments, pull requests, etc. most humble solicited.