[docbook-apps] callouts don't work in various settings

["Krueger, Carsten" <ckr at ti dot 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

To unsubscribe from this list, send a post to docbook-apps-unsubscribe@lists.oasis-open.org, or visit http://www.oasis-open.org/mlmanage/.