Docbook icon graphics

Docbook icon graphics
	Chapter 7. 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 don't 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 this into the FO output:

<fo:external-graphic src="url(images/callouts/1.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 callout icon graphics are included with the stylesheet distribution in the images/callouts directory.

The problem with the provided image files is that they are bitmap graphics, and don't look that good in print. For print, you can replace the icons with special Unicode characters that are 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 icon graphics with text numbers like (1), set the callout.graphics parameter to zero (it is one by default). Use this option when you have more than 10 callouts.

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

callout.graphics.extension: Use this parameter to change the icon file extension from .png to something else. For example, you might create vector graphics in SVG so the callouts look smoother in print. Then you would specify this parameter's value as .svg (include the period).
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/. 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 10, 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 callout numbers over 10 will still format like (11).


Cross reference page numbers		Printing one chapter