Difficulty: ★☆☆ (easy)
Keywords: splitting, topic, assembly

Problem

You need to create topics of your existing DocBook 5 document to use it with the new assembly and topic elements in DocBook 5.1.

Solution

Use the assembly/topic-maker-chunk.xsl stylesheet to create topics from your current DocBook 5 document. This breaks apart your existing document into modular files and creates an assembly file.

To disassemble an existing book.xml document, use the xsltproc command like this (the variable DB contains the path of your DocBook XSL directory):

xsltproc --xinclude \
    --stringparam assembly.filename  assembly.xml \ 
    --stringparam base.dir topics/ \
    $DB/assembly/topic-maker-chunk.xsl  \
    book.xml

The xsltproc command outputs the master assembly file assembly.xml. The document's content is break up into modular chunks, saved in the topics/ directory. The master file contains a single structure element.

Discussion

The topic-maker-chunk.xsl contains several parameters to influence the chunking process:

Table 3.2. Parameters to Influence Chunking Process Into Topics
Parameter Description
assembly.filename Name of the assembly file (default: myassembly.xml)
base.dir Directory name where to store all generated topic files (default: topics/)
chunk.first.sections Should the first top-level section be chunked? (default: 1 = yes, otherwise no)
chunk.section.depth Depth to which sections should be chunked (default is 3)
manifest.in.base.dir Puts the assembly file into the directory set by base.dir instead of the current directory
topic.elements Elements which are converted into topics (default is preface, chapter, article, and section)
html.ext Extension of the topic files (default is .xml)
root.id.suffix Suffix to add, when root.as.resourceref is set to 0 (default is -info)
root.as.resourceref Should the root element also converted into a topic? (default is 1 = yes, otherwise no)
use.id.as.filename Use xml:id value of chunk elements to create filename? (default: 1 = yes, otherwise no)

The topic-maker-chunk.xsl stylesheet reuses the same chunking algorithm than the XHTML stylesheets. That means, it breaks the document at the same boundaries and you can alter the chunking process with the same parameters than the XHTML stylesheets.

The following subsections shows some specific examples to influence the chunking process.

Influencing where to Store the Assembly File

By default, the topic-maker-chunk.xsl puts the assembly file in the current directory instead of the directory set by base.dir. If you want to have the assembly file and its topics together in the same directory, set the parameter manifest.in.base.dir to 1.

Changing the Chunking Depth

By default, the parameter chunk.section.depth is set to 3 which means, the stylesheet puts each element into a separate file down to sect2. The higher the value, the more file it creates (and vice-versa).

If you need finer control of the chunking process, use the dbhtml stop-chunking processing-instruction as described in http://docbook.sourceforge.net/release/xsl/current/doc/pi/dbhtml_stop-chunking.html.

See Also


Project @Sourceforge.net® Ticket#21 Code @Sourceforge.net®