Single file options with onechunk

Single file options with onechunk
	Chapter 7. HTML output options

The chunking stylesheet gives you several options you do not have with the nonchunking docbook.xsl stylesheet that generates a single HTML output file. These extra features come from the XSLT extension functions used to generate multiple output files from a single DocBook document. This is not a standard feature of the XSLT 1.0 standard, but each XSLT processor provides such an extension because it is so useful.

The DocBook XSL distribution includes a special stylesheet named onechunk.xsl that uses the same extension function to generate a single HTML file. This is most useful when you want your output in a single file, but you want to set one or more of these options:

Specify the output filename. See the section “Name the file using an id”.
Specify the output directory. See the section “Putting the file elsewhere”.
Specify the output encoding. See the section “Output encoding for chunk HTML”.
Specify the output document type (DTD). See the section “Specifying the output DOCTYPE”.

Name the file using an id

You can name the output file after the id value of the main document element in your XML input file. That way you do not have to specify the output filename on the command line, and you get a consistent output filename for that input file. The trick is to use the onechunk.xsl stylesheet instead of docbook.xsl. It uses the chunking stylesheet mechanism but only outputs one chunk. That lets you use the chunking options, which include naming the output file. Here is how you do it:

Add an id value to your document root element:

<?xml version="1.0"?>
<!DOCTYPE chapter SYSTEM "docbook.dtd">
<chapter  id="intro">
...

Process the document with the html/onechunk.xsl stylesheet file instead of the standard html/docbook.xsl stylesheet. Use the following stylesheet parameters with it:
```
xsltproc \
   --stringparam  use.id.as.filename 1 \
   --stringparam  root.filename  ''  \
   onechunk.xsl  myfile.xml
```

The output filename in this case will be intro.html. The use.id.as.filename parameter tells the stylesheet to use the element's id value in the filename. Setting the root.filename parameter to blank tells the stylesheet to not use the default root filename of index.html. The html.ext parameter could also be used to specify a different filename extension, such as .htm instead of the default .html.

Putting the file elsewhere

The base.dir parameter can specify an output directory for the file produced by html/onechunk.xsl. This is useful since an id value cannot include '/' characters. For example:

xsltproc \
   --stringparam  base.dir  /usr/apache/htdocs  \
   --stringparam  use.id.as.filename 1 \
   --stringparam  root.filename  ''  \
   onechunk.xsl  myfile.xml

Using the example above, the output file would be /usr/apache/htdocs/intro.html. This parameter has no effect when using the standard html/docbook.xsl stylesheet, which has no knowledge of the output filename.

Specify the output encoding and DOCTYPE

If you want to specify the output encoding of your onechunk output file, see chunker.output.encoding parameter described in the section “Output encoding for chunk HTML”.

If you want to specify the DOCTYPE of your onechunk output file, see chunker.output.doctype-public and chunker.output.doctype-system parameters described in the section “Generating XHTML”