Using CSS to style HTML

You may want to change the way the generated HTML output looks. The best way to do that is with a Cascading Style Sheet (CSS), which modern browsers support. Font family, type size, colors, and other styles can be controlled with CSS for each kind of element.

You use a text editor to create a separate CSS stylesheet file that contains all the style information, and then associate that stylesheet with all of your HTML files. If you look at the HTML output from DocBook, you'll see a lot of <div class="element"> tags, where element is the DocBook element that produced that <div>. You write your css stylesheet to associate CSS styles with specific combinations of HTML element names and DocBook class attributes (see a good CSS reference to learn how to do that). Here is a short sample that styles DocBook note output:

P.note {
  font-family: Helvetica,Arial,sans-serif;
}
H3.note {
  font-family: Helvetica,Arial,sans-serif;
  font-weight: bold;
  font-size: 12;
}

To connect the CSS stylesheet with your HTML files, you set the html.stylesheet parameter to the name of your stylesheet file. That parameter causes an HTML <LINK> element to be inserted into each generated HTML file that associates your CSS stylesheet with that HTML file. Then just make sure the stylesheet file gets copied to each HTML output directory.

For example, this command sets the parameter as it chunks the file:

xsltproc --stringparam html.stylesheet  corpstyle.css  chunk.xsl  myfile.xml

Then each HTML file has this in its <HEAD> element:

<link rel="stylesheet" href="corpstyle.css" 
      type="text/css"> 

Using CSS to style your HTML is a nice system because you can control all the formatting for all of your output from a single CSS file. And you do not have to customize the DocBook XSL stylesheets to do it.

If you need to specify more than one CSS stylesheet for your HTML files, you can put all the pathnames in the html.stylesheet parameter separated by spaces. When processed, each pathname will be output in its own HTML link element, in the order they appear in the parameter. That order is significant since it determines style precedence in CSS.

Styling section headings with CSS

By default, the HTML stylesheets generate H2 headings for both chapter and sect1 titles. That's because H1 is reserved for book titles. The basic problem is that there are too few HTML heading levels to map uniformly to the deeper structure that DocBook provides. But if you are willing to use CSS, then you can style the HTML headings as you like. Take a look at the HTML output, and you will see that each title is wrapped in HTML div elements with class attributes:

<div class="chapter" lang="en">
  <div class="titlepage">
    <div>
      <div>
        <h2 class="title">
           <a name="Catalogs"></a>Chapter 3. XML catalogs
        </h2>
      </div>
   ...

Here is a CSS specification that increases the font size for chapter title H2 headings and adds other style properties:

div.chapter div.titlepage h2 {
    font-size: 180%;
    font-family: Helvetica;
    font-weight: Bold;
    color: #444444
}

If you examine the HTML output, there are additional div wrappers around the h2. Those are artifacts of the way the titlepage templates are handled. They are not needed in the CSS selector syntax to establish the ancestry of the h2 as a chapter title.

You can write similar specifications for section heading levels, using different class values. The nice thing about this feature is that you do not have to customize the XSL stylesheets at all. You just need to put the styles in a CSS file and reference that from your HTML output by setting the html.stylesheet parameter.

Styling displays with CSS

You may want to apply styles to block displays such as programlisting and other elements. For example, you might want to set a background color and draw a border around each program listing. You could use the shade.verbatim stylesheet parameter to turn on the background color, but that parameter also affects screen and literallayout elements. The preferred method is to use CSS.

The HTML output for a programlisting looks like the following:

<div class="programlisting">
<pre class="programlisting">Text of the program
...
</pre>
</div>

You could create a selector and set styles in your CSS stylesheet like the following:

pre.programlisting {
  background-color: #FFFF99 ;
  border: 1px solid #006600 ;
}

Adding custom class attributes

The default class attributes in the HTML output may not provide you with sufficient control of your formatting. You may want to treat some element instances differently, for example, or you may need to use predefined class names from an existing CSS stylesheet. The HTML stylesheets provide two methods for defining your own class names for HTML output:

  • Using role attribute as class name. Use this method when individual elements need a different class name.

  • Custom template in mode="class.value". Use this method when tailoring class names to specific types of elements.

Each of these methods is described in more detail in the following sections.

Using role as class name

You may need to designate certain element instances as needing special formatting in your HTML output. The XSL stylesheets automatically generate class attributes on HTML DIV and SPAN elements that identify the DocBook element they came from. But those are applied uniformly, so they do not give you control over particular instances that need different handling.

The HTML stylesheets have a feature that let you control the class attribute value that is output for certain DocBook elements. If the right parameter is turned on, then the value of the element's role attribute is copied as the HTML class attribute value. The DocBook elements are emphasis, entry (table cell), para, and phrase. Each of them has a corresponding stylesheet parameter that controls the feature for that element.

Note

If the element whose class you want to change is not emphasis, entry, para, or phrase, then you can still use the other method described in the section “Generate custom class values”.

For example, if you set the para.propagates.style parameter to a nonzero value, then you get this behavior.

DocBook XML:
<para role="primary">This feature of the product ...</para>

HTML output:
<p class="primary">This feature of the product ...</p>

Then you can write a CSS selector like P.primary that styles such paragraphs differently from ordinary paragraphs.

In a similar manner, you can set any of the entry.propagates.style, emphasis.propagates.style, and phrase.propagates.style parameters to get similar behavior for role values on those DocBook elements.

The following is an example of generating an emphasis style using small capital letters. Process this file with the emphasis.propagates.style parameter set to 1.

DocBook XML:
Using an SQL <emphasis role="sqlsyntax">select</emphasis> statement

HTML output:
Using an SQL <span class="sqlsyntax">select</span> statement

CSS stylesheet entry:
.sqlsyntax {font-variant: small-caps;}

For print output, however, this parameter will have no effect because there is no downstream CSS stylesheet. If you also want small caps in your print output, you will need to add something like the following to your fo stylesheet customization layer:

<xsl:template match="emphasis[@role = 'sqlsyntax']">
  <fo:inline font-variant="small-caps">
    <xsl:apply-templates/>
  </fo:inline>
</xsl:template>

For general use, the phrase.propagates.style permits you to add custom class values to just about any part of your output. You may want certain titles to be distinguished, for example. You can wrap the text in the DocBook title element in a phrase with a role attribute. The HTML will have an HTML SPAN element with

DocBook XML:
<title><phrase role="primary">Using a Mouse</phrase><title>

HTML output:
...<span class="primary">Using a Mouse</span>...

Then you can write an appropriate CSS selector to style such titles differently from other titles.

If you need further customization of HTML class names, then see the section “Generate custom class values”

Generating id attributes

Modern browsers also support CSS selectors on the id attribute of HTML elements. An id attribute differs from the class attribute in that it is unique in the HTML file.

By default, the stylesheets do not output id attributes because some older browsers could not locate cross references by id attribute. They only worked with named anchors like <a name="foo">. Modern browsers can locate content by id, so the stylesheets provide an option to output the id value from the DocBook XML to the corresponding HTML element. Set the stylesheet parameter generate.id.attributes to 1 to turn on this feature.

Even when this parameter is used, not all id attributes in the source document are passed through to the HTML output. Only the major components get an id:

appendixcolophonpreface
articleglossaryset
bibliographyindexsetindex
bookpart 
chapterpartintro