styling refentry blocks

[Paul Suckling <paul.suckling@gmail.com>]

I am writing a user guide for some software which has an api. We use
refentry blocks to define the api. We have taken the decision to place
the refentry blocks within the relevant sections of the user guide,
interspersing them throughout the text of the document. To make them
stand out as different from the main text, we'd like to give the
refentry blocks a different background colour and border.

I have tried adding the following to my customisation layer:

  <!-- make refentrys have a grey background and border -->
  <xsl:template match="refentry">
   <fo:block background-color="#E8E8E8" border-width="1pt"
border-style="solid" border-color="#575757" padding="3pt">
    <xsl:apply-templates/>
   </fo:block>
  </xsl:template>

Style-wise, it works. However, it breaks all references within the
refentry blocks. For example, I get the lots of warning which look
like the following:

27-Apr-2009 13:39:13 org.apache.fop.area.AreaTreeHandler addOffDocumentItem
WARNING: Bookmarks: Unresolved id reference "RE_Command_NAME" found.

and the refentry blocks no longer appear in the bookmarks of the PDF version.

As an added complication, we have a similar background colour and
border styling applied to verbatim blocks (via shade.verbatim = 1 and
its attribute set). This means that our synopsis element within our
refsynopsisdiv already has a box and border. We'd like to redefine (or
remove) this styling within refentry blocks only.

I'd be grateful for advice on how to achieve what I want. Thank you.