Generating your webpages

Generating your webpages
	Chapter 29. Website

The process of generating your HTML webpages is basically two steps:

Process your layout.xml file with the autolayout.xsl stylesheet to produce an intermediate file named autolayout.xml.
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

Tabular pages

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.

Non-tabular pages

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

Use XSLT only: 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.
Use a make utility with XSLT: 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 webpage files.

The most popular stylesheet is probably chunk-tabular.xsl because it uses the easier processing method and produces nicer looking output.

Build with XSLT only

With this method, you process your Website in two steps:

Generate autolayout.xml
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
```
- In either command, substitute the actual path to the chunk-tabular.xslstylesheet file. If you want the non-tabular style, replace chunk-tabular.xsl with chunk-website.xsl.
- Set the 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 output-root/graphics. 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 example/example.css.
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.

Build with make

To build with make, you need to write a Makefile and the execute make commands.

Use a text editor to create a Makefile similar to the example below, which uses xsltproc as the processor.
Create an empty depends.tabular file.
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 `autolayout.xml` file is generated first, because the `depends` target has a dependency on it. It processes the `layout.xml` file with the `autolayout.xsl` stylesheet to produce `autolayout.xml`.
	Then the `depends` target itself is processed. It processes the `autolayout.xml` file with the `makefile-dep.xsl` stylesheet to produce the `depends.tabular` file. That file establishes the individual dependency lines between each XML `webpage` file and its HTML output file, as initially specified in `layout.xml`. The `depends.tabular` file also includes the `website` target, which has dependencies on all the HTML output files.
	When you execute make, it uses the default target `all`, which then triggers a make website command to recursively load the `Makefile`.
	When make website is executed recursively, it executes the `include depends.tabular` instruction, which this time loads the generated file `depends.tabular` with its targets for each HTML file. The newly included `depends.tabular` file has a `website` target. Its dependencies are all the HTML output files, so each one of those is checked for further dependencies. The included `depends.tabular` targets has a line for each HTML file that looks like this: html/productlist.html: products.xml This says that the HTML file should be regenerated if its XML `webpage` file is more recent.
	Any outdated HTML files trigger the `%.html:` target.
	That target processes the associated XML `webpage` file with the `tabular.xsl` stylesheet to produce the selected HTML file (indicated by `$@`).

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.

Source files in multiple directories

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.

In your 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.