Charles Engelke's Blog

February 3, 2004

Creating Multiple HTML Pages

Filed under: docbook — Charles Engelke @ 5:51 pm

One problem using MSXSL as our XSLT
processor becomes apparent when we try to do something a bit
fancier: convert a single DocBook file to multiple HTML pages.
There’s a stylesheet to do that called chunk.xsl,
so we should be able to create the output with the command

msxsl sample1.docbook \
   "c:\Program Files\docbook\xsl\html\chunk.xsl"

But when we try it with our first sample DocBook file, we get an
error message:

Error occurred while executing stylesheet
'c:\Program Files\docbook\xsl\html\chunk.xsl'.

Code:   0x80004005
Don't know how to chunk with Microsoft

Creating multiple output files from a single DocBook source file
is called chunking, and it’s not a
standard feature of XSLT processors. MSXSL can’t do it, so we
just can’t create multiple HTML pages using it. Instead, we can
use some other XSLT processor that can perform this non-standard
function. There are several to choose from, but a lot of the
documentation in the DocBook XSL stylesheets refers to one called
Saxon, so we’ll try that next.

Procedure 3.2. Installing Saxon.

  1. Download the latest stable distribution of the
    Saxon
    XSLT processor
    to a temporary directory. You’ll
    want the ZIP file
    version for Windows machines. As of this writing, the latest
    version is 6.5.3, available
    right
    here
    .

  2. Create a folder called saxon in
    C:\Program Files\docbook.

  3. Extract the files in the ZIP
    file you just downloaded to your
    C:\Program Files\docbook\saxon folder. This
    will create several files and subfolders. The
    Saxon XSLT processor is in
    saxon.jar.

  4. jar files aren’t
    normal Windows executable programs.
    jar stands for
    Java archive”, and Saxon
    is a Java program. So install the latest version of
    Java if you don’t already have
    it. You need the Java 2 Platform, Standard
    Edition
    , known as J2SE.
    You can find it here,
    or google for j2se. Download it and
    follow the instructions to install it.

Now we can use Saxon to convert DocBook
to various formats. The regular conversion isn’t too different
from the MSXSL approach. Recall that
you converted DocBook to HTML with the command:

msxsl -o sample1.html sample1.docbook \
   "c:\Program Files\docbook\xsl\html\docbook.xsl"

(where the \ shows where the text on the second line above should
really be typed). To use Saxon instead, type the command

java -jar "c:\Program Files\docbook\saxon\saxon.jar" \
    -o sample1.html sample1.docbook \
   "c:\Program Files\docbook\xsl\html\docbook.xsl"

It’s verbose, but simple.

Use the same command with the chunk.xsl style
sheet to get multiple pages of output:

java -jar "c:\Program Files\docbook\saxon\saxon.jar" \
    -o sample1.html sample1.docbook \
   "c:\Program Files\docbook\xsl\html\chunk.xsl"

This ignores the -o sample.html parameter,
always naming the main page index.html and
creating names for all other pages.

That’s plenty for today. Next time we will look at creating
Microsoft HTML Help format files from DocBook.

Advertisements

Blog at WordPress.com.

%d bloggers like this: