Docbook icon graphics

Docbook icon graphics
	Chapter 6. HTML output options

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.

Admonition graphics

By default, when you process an admonition element such as note, the output displays the label 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 note.png graphics file that is expected to be available in a images subdirectory relative to the HTML file.

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.

Use the admon.graphics.path and 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
Directory	`images/`	`admon.graphics.path` parameter. Include the trailing slash.
Filename prefix	`note`	Admonition element name.
Filename suffix	`.png`	`admon.graphics.extension` parameter. Include the dot.

These parameters change the path written into the HTML file. The directory could be a single website location, so you don't 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.

Note

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 don't, 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.

Custom admonition graphics

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 information.

Navigational icons

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:


Next	Prev	Up	Home

To enable these navigational icons, you set the navig.graphics parameter to nonzero when you process with the chunk stylesheet:

xsltproc  -stringparam  navig.graphics 1  chunk.xsl  myfile.xml

This will replace the word Next, for example, with an HTML tag <img src="images/next.png"> in the header and footer.

Note

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 don't, 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 include the trailing slash. And you can use a different graphics extension by specifying the navig.graphics.extension parameter. Include the period if the extension is like .gif.

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 default).

Callout icons

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 <img 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 images/callouts directory.

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 don't 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 default).

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 img tag.

callout.graphics.extension: Use this parameter to change the icon file extension from .png to something else. Of course, you must have the graphics that match that extension.
callout.graphics.path: Use this parameter to change the generated directory name from the default images/callouts/. Be sure to include the trailing slash.
callout.graphics.number.limit: 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 don't reset this parameter, then any numbers over 15 will still format like (16).