programlistingco is fake

Don't use programlistingco and other co-elements of DocBook. They are not supported in full by the DocBook XSL stylesheets.

Callouts, such as numbered bullets, are an annotation mechanism. For details, see description and an example. I put program listings to my documentation, and I want to add comments to code through callouts.

It's hard to combine XML listings and callouts in DocBook. The main problem is the need to escape the XML special symbols. Listings become hairy, and small changes in listings cause rework.

When I found that elements programlistingco and areaspec can be used to separate a listing and its callouts, I was happy. But it didn't work. I tried several variants, copied an example from "DocBook: The Definitive Guide", and finally found (emphasis is my):

You have to wrap your programlisting and calloutlist in a programlistingco element, because it supports the use of an areaspec to provide the coordinates. You also must use either Saxon or Xalan to process the files, because placing the callouts at the coordinates takes an XSLT extension function that is not available in xsltproc. To enable this function in Saxon or Xalan, you must set the stylesheet parameters use.extensions=1 and callouts.extension=1. Both must be set for it to work. Don't forget to include the appropriate DocBook XSL extensions jar file in your CLASSPATH as well.

I'm using xsltproc. I'm not going to switch to Saxon or Xalan. No programlistingco for me.

Categories:

Updated: