callouts don't work in various settings

["Krueger, Carsten" <ckr@ti.com>]

I'm about to write documentation that contains parts of a DTD document.
To easy maintaining the documentation I'd like these parts to appear
as unchanged (compared with the original DTD) as possible in the docbook
XML document. So I can visually merge DTD changes into the corresponding
part of the documentation.

The solution I found is to encapsulate the DTD parts in <![CDATA[...]]>
like in http://www.biglist.com/lists/dssslist/archives/199809/msg00002.html

In addition to that I want to use callouts to comment certain parts of the
DTD.
These callouts should not be mixed with the text but somehow stay outside
i.e.
again to ease merging. And I want these parts to appear shaded in the
resulting
documents. A full example of what I expect to work follows:


...
<programlistingco>
<areaspec>
<area coords="2" id="configdef_dtd_c1"/>
<area coords="6" id="configdef_dtd_c2"/>
</areaspec>
<programlisting><![CDATA[
<!ELEMENT configDef     ( property+ )>
<!ATTLIST configDef       name        CDATA #REQUIRED
                          description CDATA #REQUIRED
                          reference   CDATA #REQUIRED>
<!ELEMENT property      EMPTY>
<!ATTLIST property        name        CDATA #REQUIRED
                          value       CDATA #REQUIRED>
]]>
</programlisting>
<calloutlist>
<callout arearefs="configset_dtd_c1">
<para> some text ... </para></callout>
<callout arearefs="configset_dtd_c2">
<para> some text ... </para></callout>
</calloutlist>
</programlistingco>
...


First thing I found is that I have to enable use.extensions in the
stylesheets
(FO and HTML for 1.6.13 and 1.6.24). But that still only partly does the
job.


For the HTML stylesheets it only works if I set shade.verbatim
to 0. Otherwise the callouts appear on column 0 and the text is broken
(after each callout) into differently shaded blocks.


For the FO stylesheets it only works if I set callout.graphics
to 1. Toggling callout.unicode does not help.

When setting callout.graphics to 0 and callout.unicode to 1 a '#' character
is shown where I would expect the callout to appear. I guess the FO output
should be corrected from (_X_ represents a Unicode character):
    ...
    &lt;ELEMENT configDef ( property+ )&gt; _X_
    ...
to
    &lt;ELEMENT configDef ( property+ )&gt; <fo:inline
font-family="ZapfDingbats">_X_</fo:inline>

When setting callout.graphics to 0 and callout.unicode to 0 the callouts are
shown correctly but the callout arearefs have disappeared completely.



Maybe I'm completely on the wrong track. Any help, hints or pointers are
appreciated.


Regards,
Carsten