Chunking with Docbook

Dan York

You can set a parameter to use the id attribute as the filename. In your customization layer, add this line:

Then make sure that each <chapter> and <sect1> tag include an id attribute (since those are the ones that will be chunked):

In most of my docs, my preference is to NOT put the 'ch01' in there... I use ids that are related to whatever is in the chapter, but that is mostly a matter of personal style. (And the fact that if I rearrange sections I do not want to go back through and manually change id strings.)

Jeff Beal

Filenames are computed by templates in the "chunk-filename" and "recursive-chunk-filename" modes located in 'chunk-common.xsl'. Most of the work for determining the name of the file happens in recursive-chunk-filename, which follows these precedence rules (for "chunking" elements).

1. If there is a filename specified by a <?dbhtml?> processing instruction, use it

2. If the element has an *explicit* id (i.e. it uses the @id attribute, not the generate-id() function) and the use.id.as.filename parameter is non-zero, construct a filename by appending the $html.ext parameter to the element's ID

3. Otherwise, construct a hierarchical filename that (roughly) follows the pattern bk??ch??s??.html where the ?? indicates the element's position within the parent. For example, bk04ch12s03.html is the file generated by Section 12.3 in the 4th book of a set. If you are building from a book instead of a set, the bk?? is left off. Different elements will generate a different prefix, <article/>, for example, inserts an 'ar??' into the filename, <preface/> is 'pr', <part/> is 'pt'.

This method can certainly create long filenames. We build some of our documentation using a section chunking level of 3 and we get files named 'bk03ch07s01s02s07.html'. If, however, you're only building a single book and chunking down to top-level sections, your filenames would be ch??s??.html.

DaveP and Bob Stayton

Another option is to put each qandaset in its own section element, and chunk on the sections. Put the title on the section instead of the qandaset. That way you can get whatever depth of hierarchy you need in your question collection, and the titles will automatically appear in the table of contents.

The stylesheets don't include qandaset in the list of elements to chunk on. Adding them is not so easy because you have to handle all the Next and Previous and TOC stuff for chunks as well.