DOCBOOK-APPS: transforming fragments specific to the format?

[Erik Hennum <erik.hennum@informix.com>]

Honored DocBook and XSLT experts:

Does anyone know an XSLT trick for inserting a 
document fragment in the input document before 
applying the transformation?

In particular, the output format should determine 
which document fragment to insert and transform.

The usage case:  we want to describe the formatting
conventions (typography, icons, etcetera) used in 
the manuals.  Some of the descriptions are specific 
to the format while others (such as the description 
of the formatting for computer output) are generic.  
That is, if we could transform a generic description
as usual, we could reuse it for many output formats.

The input document could reference entities for the 
generic descriptions.  However, that would make it 
hard to maintain a coherent blend of format-specific 
and generic descriptions.  Also, the blend would have 
to remain good for all formats.

So, my naive impulse was to apply templates 
to the input fragment, as in:

<?xml version='1.0'?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
                version="1.1">

<xsl:import href="/path/to/html/docbook.xsl"/>

<!-- replace a placeholder paragraph in the input
     document with the conventions for this format -->
<xsl:template match="para[ @id = 'idOfPlaceholder' ]">

  <!-- a generic convention (eventually to be supplied
       by reference to an external entity) -->
  <xsl:variable name="genericConvention">
    <para>
      computer output looks like
      <computeroutput>this</computeroutput>
    </para>
  </xsl:variable>

  <p>Here are the typographic conventions in this book.</p>
  <p>A convention specific to this format</p></li>

  <!-- format the generic convention -->
  <xsl:apply-templates select="$genericConvention"/>

  <p>Another convention specific to this format</p>
</xsl:template>

</xsl:stylesheet>

Xalan points out that I'm trying to convert 
a result tree fragment into a node list.  

Saxon appears to convert silently to a node list, but 
the XSLT scripts emit a new HTML tree for each 
top-level node in the fragment.

I've thought of writing a little XSLT utility script that 
generates HTML and FO fragments for the generic
descriptions.  Then, the main XSLT script could 
include the formatted generic descriptions via 
external entities.  But that would introduce a new
level of configuration management complexity.

Can anyone suggest another approach?  

For instance, is there a way to reference entities
in the input document but redefine them in the 
stylesheet?


Thanks in advance for any suggestions,


Erik Hennum
erik.hennum@informix.com