3.14. Splitting DocBook 5 Documents Into Topics

3.14. Splitting DocBook 5 Documents Into Topics
Prev	Chapter 3. Manipulating DocBook Document Structure	Next

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.

Prev	Up	Next
3.13. Creating an Acronym List	Home	3.15. Assembling Topics