Processing instructions

A processing instruction is a means of passing hints to the XSLT processor about how to handle something. XML permits the placement of processing instructions just about anywhere in a document. A processing instruction (sometimes referred to as a PI) uses a special syntax, <?name content ?>, to indicate that it is not an element, comment, or text. For example:

<?dbfo bgcolor="#EEEEEE" ?>

The first word in a PI is the name. In this example, the name of the processing instruction is dbfo and the content is bgcolor="#EEEEEE". This style of PI content could be called a “pseudo attribute”, because it provides a name-value pair similar to a real attribute (which only elements can have). You can put several such pseudo attributes in one PI, or you can put each of them in their own PI.

The DocBook stylesheets accept certain predefined processing instructions to specify information for which no DocBook element or attribute exists. In this example, it specifies the background color for a table cell, as described in the section “Cell background color”. DocBook processing instructions use the naming convention dbhtml to mean processing instructions intended for the HTML stylesheets, and dbfo for those PIs intended for the FO stylesheets. See the index for a list of predefined PIs of each type.

You can add your own processing instructions as part of your customization. If you use the DocBook PI name (dbhtml or dbfo) and the pseudo attribute style of content, then you can use some of the stylesheet machinery to parse the content. Here is an example of how the DocBook stylesheet gets the value of the above example:

Example 8.3. Custom processing instruction

<xsl:variable name="backgroundcolor">  1
  <xsl:call-template name="dbfo-attribute">  2
    <xsl:with-param name="pis"  
         select="ancestor-or-self::entry/processing-instruction('dbfo')"/>  3
    <xsl:with-param name="attribute" select="'bgcolor'"/>  4
  </xsl:call-template>
</xsl:variable>
1

Put the selected value into a stylesheet variable named backgroundcolor for use later in the template.

2

Call the template named dbfo-attribute, which is used to process dbfo PIs. There is a similar template named dbhtml-attribute for processing dbhtml PIs. Each requires two parameters that are specified on the next two lines.

3

The pis parameter should select the candidate processing instructions in a given location. The syntax for specifying a PI in an XSL select statement is processing-instruction('name'). This looks like a function, but it is really a way of specifying this special kind of node in the document. In this case, it is looking for all PIs whose names are dbfo that are contained in the current entry element.

4

The above selection step could get several PIs, each of which could have several pseudo attributes. The attribute parameter specifies which of those pseudo attribute values is needed here. The dbfo-attribute template searches through all the selected PIs for the given pseudo attribute and returns its value, which gets stored in the variable for use by the stylesheet.

To create processing instructions of your own, you need to do the following: