Next / Previous / Contents / NM Tech homepage

7. zdp_html.xsl: HTML customization layer

The zdp_html.xsl file is an XSLT script that lies on top of the DocBook-XSL Stylesheets, specifying the local customizations for our HTML presentation.

It starts with the usual xsl:stylesheet root element. Attributes include:

zdp_html.xsl
<?xml version="1.0"?>
<xsl:stylesheet
    version="1.0"
    xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
    xmlns:d="http://docbook.org/ns/docbook"
    xmlns:date="http://exslt.org/dates-and-times"
    extension-element-prefixes="date"
    exclude-result-prefixes="date d">
  <!-- XSL-HTML stylesheet customization layer.
   !   Do not edit this file directly.  It is extracted automatically
   !   from the documentation:
   !       http://www.nmt.edu/~shipman/doc/doc5style/
   !-->

Next we import the html/chunk.xsl stylesheet from the stock DocBook-XSL Stylesheets. Stayton discusses this in the chapter on HTML customization, the section on chunking: this file is the root HTML stylesheet for chunked HTML output (as opposed to one huge page).

zdp_html.xsl
<!--Select chunked HTML output.-->
<xsl:import
    href="http://www.nmt.edu/~shipman/doc/docbook-xsl-ns-1.78.1/html/chunk.xsl"/>

A number of common strings, such as the organization name that appears in the navigational links, are declared in a separate file, fo_params.xsl. This allows you to supply your own branding for these style features. For the contents of this file, see Section 8, “The html_params.xsl file: HTML branding”.

zdp_html.xsl
<!--Branding parameters-->
<xsl:import href="html_params.xsl" />

Specify output in HTML.

zdp_html.xsl
<!--Select HTML output.-->
<xsl:output method="html"/>

Write the current version on the controlling terminal. The xsl:message construct is allowed only with a template, variable, or param, so we enclose it in a dummy param.

zdp_html.xsl
<xsl:param name="greeting">
  <xsl:message>=== doc5style (HTML) 1.0 ===</xsl:message>  
</xsl:param>

The remaining local customizations are divided into these sections:

7.1. HTML general page layout

The first general customization we need is to link to the CSS stylesheet that customizes the appearance of all DocBook-generated Web pages. The content of the html.stylesheet parameter appears as S in the generated style sheet link: “<link rel="stylesheet" href="S" type="text/css">

zdp_html.xsl
<!--html.stylesheet-->
<xsl:param name="html.stylesheet"
  >http://www.nmt.edu/~shipman/doc/doc5style/docbook5.css</xsl:param>

The color scheme defined in the stock html/docbook.xsl file is black text on a white background. Because our color scheme is defined in the CSS style sheet, docbook5.css we need to get rid of the stock color scheme. To do this, we define an empty body.attributes template to replace the template by that name that contains the color definitions.

zdp_html.xsl
<!--body.attributes-->
<xsl:template name="body.attributes"/>

In early 2009, a lot of browsers started rendering the non-break space character (&nbsp;) as a dark lozenge with a question mark inside it. This turns out to have been caused by an incorrect encoding scheme. This issue is discussed in Stayton, 3rd ed., p. 298, in the chapter “Languages, characters, and encoding,” the section entitled “Output encoding.” The default encoding is ISO-8859-1, but it should be UTF-8. The chunker.output.encoding variable controls the encoding that appears in the meta tag for chunked output.

zdp_html.xsl
<!--chunker.output.encoding: Specify UTF-8 encoding for
 !  proper character entity rendering.
 !-->
<xsl:param name="chunker.output.encoding"
  >UTF-8</xsl:param>

The logo.url parameter specifies the URL of the logo.

zdp_html.xsl
<!--Location of the logo image-->
<xsl:param name="html.logo"
  >http://www.nmt.edu/~shipman/zdplogo.png</xsl:param>