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
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
callouts/ containing graphics
that are used to mark the locations of the
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:
Create a small rectangle, maybe 20×15
pixels, and paint it some solid color, such as
#ff8080 (a darkish pink).
Use the Text tool to put in the numerals.
Save in PNG and PDF format, with the file name
equal to the callout number. For example,
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.
<!--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.
<!--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.
<!--Maximum number of callouts--> <xsl:param name="callout.graphics.number.limit">20</xsl:param>