The process of generating your HTML webpages is basically two steps:
Use the intermediate file to manage the processing of your XML webpage files with one of the Website stylesheets to produce your HTML output files. The stylesheet you use depends on the output style and the processing method you choose.
Choose an output style
In the tabular style of website output, each generated HTML page has a table of contents on the left. The table of contents is an expandable and collapsible list of all the pages in the website. The same list appears on each page, but it may appear somewhat different depending on what is expanded. Also, the current page is marked with an arrow pointing to its title. This list makes it very easy to navigate through the website.
This style is called tabular because a two-column HTML TABLE element is used to form the layout. Unfortunately, webpages that are laid out with a table are difficult for text-only or audio browsers, both important considerations for website access.
In the non-tabular style, no HTML table is used to lay out the page. That enables it to be more easily browsed with a text-only or audio browser. In this style, the navigational links are placed horizontally at the top of each page. For those pages that contain a hierarchy of
tocentry elements in your
layout.xml file, you can put an optional empty
webtoc element somewhere in your
webpage source. This will generate and display the list of subpages at that point.
There are also two processing methods. Both methods attempt to track the dependencies between the input XML and the output HTML. That way if only one XML file changes, you only have to regenerate one HTML file rather than the whole website. Here are the two methods.
Choose a processing method
You let an XSL extension function determine which XML files need processing. It executes a single XSLT process to select the files and apply the stylesheet. It uses parts of the DocBook XSL chunking stylesheets to output multiple HTML files from one XSLT process, although it doesn't actually chunk sections into separate files. This method is easier to use because you don't have to write a
Makefile. It uses an XSL extension function to determine which XML files have changed and need reprocessing. That extension function is currently only available for the Saxon and Xalan processors. You can still use other processors such as xsltproc, but it will have to process all the files each time since it cannot determine which files have changed.
You create a
Makefile to apply the stylesheet only to changed XML files. In this method, a separate XSLT process is executed for each XML file that needs processing. This method requires knowledge of writing and using a
Makefile, but it is more flexible and works with any XSLT processor.
There are four Website stylesheets that cover the combinations of these four options. Use this table to select your stylesheet.
Table 29.1. Website stylesheets
|Using XSLT only||Using make with XSLT|
|Tabular output style||chunk-tabular.xsl||tabular.xsl|
|Non-tabular output style||chunk-website.xsl||website.xsl|
Don't be misled by the word chunk in the filenames. Those stylesheets will not chunk a single XML
webpage file into multiple HTML files. Rather, some of the DocBook chunking templates are borrowed to output multiple HTML files from a single XSLT process that is reading in all the XML
The most popular stylesheet is probably
chunk-tabular.xsl because it uses the easier processing method and produces nicer looking output.
Generate the intermediate file
autolayout.xml from your
layout.xml file. For example:
With Saxon: java \ -cp "/xml/saxon653/saxon.jar" \ com.icl.saxon.StyleSheet \ -o autolayout.xml \ layout.xml \ ../website/xsl/autolayout.xsl With xsltproc: XML_CATALOG_FILES=../website/catalog.xml \ xsltproc \ --output autolayout.xml \ ../website/xsl/autolayout.xsl \ layout.xml
In either command, substitute the actual path to the
autolayout.xsl stylesheet file located in the
xsl subdirectory of the Website distribution. This example includes a reference to the Website catalog file to help resolve addresses.
During the process, a message will indicate each XML webpage filename and its corresponding HTML output filename. Any XML
webpage without an
id attribute will cause the process to fail. Likewise with any
tocentry elements that are missing required attributes.
Create output subdirectories
If you specified
dir attributes in your
layout.xml file, you will need to create the output directories by hand. An XSL processor cannot create new directories. This step only needs to be done once.
Generate HTML output
Process your intermediate
autolayout.xml file with your chosen stylesheet, using a command similar to one of the following:
With Saxon: java \ -cp "/xml/saxon653/saxon.jar:../website/extensions/saxon653.jar" \ com.icl.saxon.StyleSheet \ autolayout.xml \ ../website/xsl/chunk-tabular.xsl \ output-root=htdocs With xsltproc: xsltproc \ --stringparam output-root htdocs \ ../website/xsl/chunk-tabular.xsl \ autolayout.xml
output-root stylesheet parameter to direct the hierarchy of HTML
files to a location other than the current directory.
Notice that the Saxon command's CLASSPATH option now includes an extensions file that is included with the Website distribution. It contains the extension function the stylesheet uses to tell if an XML webpage file has changed and needs to be reprocessed.
If you use xsltproc, then all the XML files will be processed every time. That's because that processor lacks such an extension function at this time.
You may notice that processing is rather slow. If you are not connected to the Internet, it will fail. These problems are caused by the stylesheets including the stock DocBook XSL stylesheet by using a URL over the Internet. See the section “Website with XML catalogs” for help.
Add the graphical icons and CSS stylesheet if you want those. You only need to do this the first time you build the output directory.
Graphical icons are used for tabular style output. Copy the
example/graphics directory from the Website distribution to
. If you are using graphics for your admonitions such as
note, also copy those icon files to the same directory. All references in the generated HTML files will be made relative to that location.
If you have a
style element in your
layout.xml file, copy your CSS stylesheet file to your
output-root. If that element's
src attribute specifies a path, put the file in that path relative to your
output-root. All references in the generated HTML files will be made relative to that location. The sample CSS stylesheet in the distribution is
You should now have a complete set of HTML Website files under your
output-root location. Each file should be in the location specified by the
dir attribute in its
tocentry element in
layout.xml. The navigational features should all work too.
If you change any of your XML
webpage files or your
layout.xml file, then you only need to run step 3 again. It will rebuild only those files that need rebuilding.
Use a text editor to create a
Makefile similar to the example below, which uses xsltproc as the processor.
Execute make depends (this only has to be done once manually).
Execute make. This will build all your Website HTML files.
Thereafter, as you edit
layout.xml or any of your XML
webpage files, you only have to execute make. The dependencies will be automatic (unless you delete
depends.tabular, in which case you will have to run make depends again).
The following is a complete example for a Website
Makefile. You enter some of the dependencies, while others are generated for you.
Example 29.5. Website Makefile using xsltproc
STYLEDIR=../website/xsl all: make website include depends.tabular autolayout.xml: layout.xml xsltproc --output $@ $(STYLEDIR)/autolayout.xsl $< make depends depends: autolayout.xml xsltproc \ --output depends.tabular \ --stringparam output-root htdocs \ $(STYLEDIR)/makefile-dep.xsl \ $< %.html: autolayout.xml xsltproc \ --output $@ \ --stringparam autolayout-file autolayout.xml \ --stringparam output-root htdocs \ $(STYLEDIR)/tabular.xsl \ $(filter-out autolayout.xml,$^) .PHONY : clean
The sequence of processing is as follows. Because Makefiles are not processed sequentially, the following paragraphs are shown in processing order.
When you execute make depends, the
When you execute make, it uses the default target
When make website is executed recursively, it executes the
The newly included
This says that the HTML file should be regenerated if its XML
Any outdated HTML files trigger the
That target processes the associated XML
The result is that the combination of the
Makefile and the
depends.tabular file keep track of the dependencies. Thereafter, you only need to type make to update your Website.
The location of your XML
webpage files is independent of the layout of your HTML output files. But if you put your XML files in multiple directories, you have to make these changes to your setup and processing.
layout.xml file, the
page attribute in each
tocentry needs to provide a path to the XML file. Relative or absolute paths will work. The
dir attribute in
tocentry is applied to the HTML output file, not the input file.
When you process with make, you need to set the stylesheet parameter
autolayout-file to the absolute path of your generated
autolayout.xml file. If you don't, the
stylesheet will look for it in the same location as each XML
webpage file, so it will fail.
This parameter is not needed when using the XSLT-only method, because
all the files are processed in the same pass after the
autolayout.xml file is loaded.
|DocBook XSL: The Complete Guide - 3rd Edition||PDF version available|
Copyright © 2002-2005 Sagehill Enterprises