Docbook icon graphics

Docbook icon graphics
	Chapter 8. Printed output options

The DocBook stylesheets can use icon graphics for these purposes in the print output:

Icons to indicate the different types of admonitions (note, tip, warning, caution, and important).
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 fo/docbook.xsl myfile.xml

This will put an image reference before the word “Note” in the FO output file:

<fo:external-graphic src="url(images/note.png)"/>

When this is subsequently processed with the XSL-FO processor, it will look for that image file in that location to include it in the PDF. The admonition icon graphics are included with the stylesheet distribution in the images directory.

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 FO 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 FO file. The directory could be a single location, so you do not have to copy them to each of your source 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.

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 FO stylesheets use small graphical icons for the numbers (such as ). The stylesheets insert references like the following into the FO output:

<fo:external-graphic src="url(images/callouts/1.svg)"
  content-width="7pt" width="7pt"/>

When this is subsequently processed with the XSL-FO processor, it will look for that image file in that location to include it in the PDF. The callout icon graphics are included with the stylesheet distribution in the images/callouts directory.

The SVG callout icons have been available starting with version 1.73 of the stylesheets. They provide a sharp rendering of the circle and number at any resolution. The SVG icons go up to the number 30. Prior to version 1.73, the callout image files were bitmap PNG graphics, and they do not look good in print because they are not high resolution graphics.

For print, you could also replace the icon graphics with special Unicode characters that are a similar white number on a black disk. To do that, set the callout.unicode parameter to 1 and the callout.graphics parameter to zero. Then the FO output uses character entities like ❶. This entity is rendered by the XSL-FO processor as the callout number. These Unicode numbers also only go up to ten, however.

To replace the callout icons with plain text numbers in parentheses like (1), set the callout.graphics parameter to zero (it is one by default) and the callout.unicode parameter to zero (the default).

If you use callout graphics, then there are four parameters that give you more control over the generated graphics tag.

callout.graphics.extension: Use this parameter to change the icon file extension from .svg to some other extension for which you have icon graphics.
callout.graphics.path: Use this parameter to change the location where the XSL-FO processor should look for the image files. The default value is images/callouts/, which may not work for you unless you copy the images directory from the stylesheet distribution to where your XML files are located. Be sure to include a 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 SVG callout graphics files with numbers up to 30, 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 callout numbers over 30 will still format like (31).
callout.icon.size: The size to render the callout icons. The default value is 7pt.


Cross reference page numbers		Printing one chapter