The DocBook stylesheets can use icon graphics for these purposes in the HTML output:
Icons to indicate the different types of admonitions (note, tip, warning, caution, and important).
Icons to indicate Next, Previous, Up, and Home for navigating among chunked output.
Numbered icons for callouts.
By default, when you process an admonition element such as
note, the output displays the
Note in the appropriate language, followed by the text of the
note. You can add a distinctive admonition graphic before the label
by setting the
admon.graphics parameter to non-zero:
xsltproc --stringparam admon.graphics 1 docbook.xsl myfile.xml
This will generate an HTML element
<img src="images/note.png>. This references a
file that is expected to be available in a
images subdirectory relative to the HTML
Other options include:
If you want to display just the icon alone without the text label, then set the
admon.textlabel stylesheet parameter to zero.
admon.graphics.extension parameters to change the generated pathname
to the image file. The pathname written to the HTML file is built up
from three components, two of which can be changed with parameters.
Here is how the default
images/note.png pathname is generated:
|Path component||Example||Comes from|
|Filename prefix||Admonition element name.|
These parameters change the path written into the HTML file. The directory could be a single website location, so you do not have to copy them to each of your HTML output directories. Being able to change the filename extension is useful when you have created your own admonition graphics and they are in a different format. They all have to use the same extension, however.
The HTML stylesheet does not create or copy the actual image files to the specified location. It just creates references to the images in the HTML files. If you turn on admonition graphics, you will need to put the image files in the appropriate place in the output. If you do not, then your HTML files will have unresolved image references. Using a Makefile makes it easier to not forget this chore each time you generate your output.
You may want to replace the stock DocBook admonition graphics with those of your own design. That's easy to do. When you create your image files, just name them after the admonition element they represent, such as
note.png. Then you just copy your graphics files to the HTML output directory and they will be used. If your graphics use a different filename extension such as
.jpg, then set the stylesheet parameter
admon.graphics.extension parameter to
.jpg to indicate that. If your graphics are larger or smaller
than the stock graphics, then you can customize the template named
admon.graphic.width. See the section “Customizing admonitions” for more
When you chunk your output into multiple HTML files, each file is given a header and footer that helps readers navigate among the multiple files. The header and footer indicate the Next and Previous files, in document order, as well as Up and Home to move up in the hierarchy of content. The default output uses words (in the appropriate language) to indicate these options, but you can use icons like these instead:
To enable these navigational icons, you set the
navig.graphics parameter to nonzero when you process with
xsltproc --stringparam navig.graphics 1 chunk.xsl myfile.xml
This will replace the word Next, for example, with an HTML tag
in the header and footer.
The stylesheet does not create or copy the actual image files to the specified location. It just creates references to the images in the HTML files. If you turn on navigational graphics, you will need to put the image files in the appropriate place in the output. If you do not, then your HTML files will have unresolved image references. Using a Makefile makes it easier to not forget this chore each time you generate your output.
You can change the directory path by resetting the
navig.graphics.path parameter to a new directory, but be sure to
trailing slash. And you can use a different graphics extension by
navig.graphics.extension parameter. Include the period if the
extension is like
The header and footer also shows the titles of the other files
by default. If you want a very clean presentation with just the icons
and not the titles, then you can set the
navig.showtitles parameter to zero (it is one by
Callouts are used to connect annotation comments to points in a program listing or literallayout. They are like numbered footnotes, in that a user follows a given number label in the display to a specific comment by matching the numbers. See the section “Callouts” for more information on using callouts.
By default the HTML stylesheets use small graphical icons for
the numbers (such as ). The
stylesheets insert HTML tags like
src="images/callouts/1.png"> in the display and next to
the callout annotation. The icon graphics are included with the
stylesheet distribution in the
As with the other icons in the output, the stylesheets do not create or copy the actual image files to the output location. If you use callouts but do not copy the provided image files, then you will have unresolved graphics references in your HTML output. You may choose to replace the icons with ordinary numbers to avoid having to deal with the icon graphics. Another reason to switch is when you have more than ten callouts in a single list. The distribution only includes icons for the numbers 1 through 10.
To replace the icon graphics with text numbers like
(1), set the
callout.graphics parameter to zero (it is one by
Another option is to replace the icons with special Unicode
characters that are similar. To do that, set the
callout.unicode parameter to 1 and the
callout.graphics parameter to zero. Then the HTML output looks like
❶. This entity is rendered by the browser as the callout
number. These numbers also only go up to ten, however.
If you use callout graphics, then there are three parameters
that give you more control over the generated
Use this parameter to change the icon file extension
something else. Of course, you must have the graphics that match that
Use this parameter to change the generated directory
name from the
images/callouts/. Be sure to include the trailing slash.
Use this parameter to set the highest number for which you have a callout graphic. The stylesheets are distributed with callout graphics files with numbers up to 15, but you could create graphics with additional numbers if you need them. If you have more numbers but you do not reset this parameter, then any numbers over 15 will still format like
|DocBook XSL: The Complete Guide - 4th Edition||PDF version available|
Copyright © 2002-2007 Sagehill Enterprises