Next / Previous / Contents / NM Tech homepage

11.5.5. Callouts

A callout is a location in a display that is flagged with a number that refers to an explanatory paragraph elsewhere.

In DocBook, the writer embeds a co element at some location inside a display (typically a programlistingco element) to associate its “id” attribute with that location. Then, elsewhere in the document, they use a calloutlist element as a container for callout elements that contain explanatory material for that location.

Writing documentation with DocBook-XML 5.0 stipulates that the user must have a subdirectory named callouts/ containing graphics that are used to mark the locations of the co elements in the display. Typically these graphics are colored circles or rectangles with numerals inside them. We made our own using Gimp, and here's the procedure:

  1. Create a small rectangle, maybe 20×15 pixels, and paint it some solid color, such as #ff8080 (a darkish pink).

  2. Use the Text tool to put in the numerals.

  3. Save in PNG and PDF format, with the file name equal to the callout number. For example, 16.png and 16.pdf would be the Web and PDF callout images, respectively, for the 16th callout.

In the customization layer, we use callout.graphics.path to specify where to find the callout graphics.

zdp_fo.xsl
<!--Path to the directory with callout graphics-->
<xsl:param name="callout.graphics.path">callouts/</xsl:param>

Then we specify that for PDF output, the callout images will also be in PDF format.

zdp_fo.xsl
<!--File extension used for the callout graphics-->
<xsl:param name="callout.graphics.extension">.pdf</xsl:param>

The default number of callouts is 15. We made 20. It would be easy to make more.

zdp_fo.xsl
<!--Maximum number of callouts-->
<xsl:param name="callout.graphics.number.limit">20</xsl:param>