DocBook NG: The “PTO” Release

Volume 8, Issue 105; 24 Jul 2005; last modified 08 Oct 2010

On the road to DocBook V5.0α1. This is very likely to be the last “NG” release before the DocBook Technical Committee releases an official V5.0 alpha.

Testing can show the presence of errors, but not their absence.

E. Dijkstra

Paula's Texas Orange, “PTO” is the fourteenthWhat about “N” and “O”? Well, two things really: I couldn't think of any good names starting with those letters that fit the theme and I really wanted to get to “P” before the NG series came to an end. Delicious in its own right, Paula's Texas Orange makes the finest of margaritas. That goes double if you can get Paula to mix one up for you. If you're going to pass through Austin, pick up a case for me, will you? release of DocBook NG.

It is very likely that the DocBook Technical Committee will approve publication of “PTO” as DocBook V5.0 (alpha release 1) in August, 2005.

There are two significant changes in the “PTO” release. First, the content models associated with sections have been reworked. Second, support for XInclude, first introduced in Mezcal, has been moved into a separate schema. It will be part of the DocBook schema distribution, but it will not be part of the normative DocBook schema.

To understand how and why the section content models have been reorganized, it's important to recall the intended distinction between simplesect and the other sectioning elements: simplesect does not appear in the Table of Contents (ToC).

What, you may ask, is the point of that? Well, consider a long document where every chapter or major section always ends with subsections named “Summary”, “Exercises”, and “See Also”. The author or production editor for such a document might conclude that the ToC is shorter and more helpful to the reader if it does not include these three section titles over and over again. By using simplesect for these sections, they are suppressed them from the ToC.

Problem is, since the introduction of simplesect, they have always appeared as an alternative to the other sectioning elements. In other words, a chapter could contain either section+ or simplesect+. That greatly reduces their utility since it prevents a chapter from containing a few “normal” sections followed by “simple sections”.

In “PTO”, I've replaced this forced choice with groups of the form

(section+, simplesect*) | simplesect+

allowing simplesects to occur at the same level as, but after, other sections. I think this will make simplesect much more useful.

I've also released “PTO” versions of Simplified NG, Slides NG, and Website NG.


Your latest work on DocBook is the best stuff in years for tech pubs, and I hope it takes off quickly. Is there a "best practice" for migrating older DocBook (DTD based) content to using this new schema described anywhere? Congratulations on all your hard work to get to the final stages for v.5. Looks like you're just "tweaking" your own "nice to haves" at this point.

—Posted by Dorothy Hoskins on 02 Aug 2005 @ 01:36 UTC #