Processing instructions

Processing instructions
	Chapter 9. Customization methods

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. The following is an example of how the DocBook stylesheet gets the value of the above example:

Example 9.3. Custom processing instruction

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

	Put the selected value into a stylesheet variable named `bgcolor` for use later in the template.
	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.
	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.
	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:

Decide on the names and possible values for your pseudo attributes.
Decide where you might place your processing instructions in your document.
For the elements that will contains such PIs, you will want to customize that element's template to make use of the PI.
Add XSL code similar to the above example to the customized template, changing the select statement in the pis parameter, and changing the value of the attribute parameter to match your usage.


Adding new templates		Customizing DocBook 5 XSL