After you have marked your conditional content with profiling attributes, you select which content to include at runtime by setting certain profiling parameters. For example, if you set the stylesheet parameter
profile.userlevel to the value
advanced, then the stylesheet will include all elements with a
userlevel="advanced" attribute, and exclude all elements that have a
userlevel attribute with some other value. All the profiling parameters are listed in Table 26.1, “Profiling attributes”.
There are actually two methods for running the profiling process to select content:
Single-pass processing, in which the profiling stylesheet first selects the profiled content, stores it in an internal node-set, and then generates the output from that internal node-set. This is all done with a single XSLT process.
Two-pass processing, in which you use a separate stylesheet that generates a profiled version into a temporary file, and then you process that temporary file with the standard DocBook stylesheet or customization. This requires two separate XSLT processes run in sequence.
Which method you use depends on these factors:
If your document contains
link cross references, then you may need to use the two-pass method. That is because ID lookups are not standardized for internal node-sets, so not all processors can resolve them. Saxon and Xalan work, but xsltproc does not. Switching all cross references to use
olink would permit you to use single-pass processing.
If your XSLT processor does not support the EXSLT
node-set() function, then you must use the two-pass method. Saxon, Xalan, and xsltproc support it, but MSXSL does not, for example.
If you want to be able to examine the effects of profiling on your XML content, then use two-pass processing and examine the temporary profiled version.
In the current implementation, single-pass profiling is handled with customized versions of the DocBook stylesheets. This was done to avoid the overhead of profiling for those who do not use the feature. The profiling stylesheets perform the normal DocBook XSL processing after doing the profiling step to select the content to process. These stylesheets are included with the DocBook XSL distribution.
Table 26.2. Profiling stylesheets
|For generating this output:
|Instead of this standard stylesheet:
|Use this profiling stylesheet:
|Single HTML file
|Multiple chunked HTML files
These stylesheets can be used by any XSLT processor that supports the EXSLT
node-set() function. That includes Saxon, Xalan, and xsltproc. It does not include MSXSL, however. For that processor and others that do not support EXSLT
node-set(), you need to perform a separate profiling step as described in the section “Two-pass processing”.
By default, the profiling stylesheets will output all elements, whether they are marked with profiling attributes or not. That is probably not what you want. You set the conditions for selecting marked elements by passing stylesheet parameters to the XSLT processor. For example, if you want to select elements whose profiling attribute
os has the value
linux, you would set the stylesheet parameter
linux. Here are some command examples.
Using xsltproc: xsltproc --output myfile.linux.html \ --stringparam profile.os "linux" \ html/profile-docbook.xsl \ myfile.xml Using Saxon: java -cp "../saxon653/saxon.jar" \ com.icl.saxon.StyleSheet \ myfile.xml \ html/profile-chunk.xsl \ profile.os="linux" \ base.dir="html/" Using Xalan: java org.apache.xalan.xslt.Process \ -out myfile.linux.html \ -in myfile.xml \ -param profile.os linux \ -xsl html/profile-docbook.xsl
profile.os parameter is set to a non-blank value like
linux, then all instances of the
os attribute in the document are examined
and only those elements with the
linux value are included in the output. Any other elements that
os attribute whose value
does not match
linux are ignored. And of course any elements that do not have
os attribute at all are
included in the output as well.
Similar stylesheet parameters are available for the other profiling attributes. If you are profiling on the
condition attribute, then you would set the
profile.condition stylesheet parameter to the selected value,
If you are using more than one profiling attribute, you will need to set a parameter for each one. Any for which you do not will have all versions included in the output, which is probably not what you want.
If you need to specify two or more key words for one profiling attribute, you can put them in the parameter separated by semicolons (but no spaces). For example, if you want to select all elements whose
arch attribute value is
i586, then specify the
profile.arch parameter as
A separate stylesheet is available to perform just the profiling step, without also applying the DocBook style templates. The output is a filtered version of your original XML document, with the profiling conditions applied so that some elements are excluded. That profiling-only stylesheet is useful when your document contains
link which cannot be resolved with the single-pass processing, or if you are using an XSLT processor that does not support the EXSLT
The profiling-only stylesheet can be found at
profiling/profile.xsl, a separate directory in the DocBook XSL distribution. It accepts the same profiling parameters as the single-pass profiling stylesheets. The following is an example of how to use it.
Generate profiled XML file: xsltproc --output myfile.linux.xml \ --stringparam profile.os "linux" \ profiling/profile.xsl \ myfile.xml Generate output: xsltproc --output myfile.linux.html \ html/docbook.xsl \ myfile.linux.xml
The result of the first command is a file named
myfile.linux.xml, which is your original document but with the non-linux elements removed. It is then processed with the stock DocBook XSL stylesheet.
|DocBook XSL: The Complete Guide - 4th Edition
|PDF version available
Copyright © 2002-2007 Sagehill Enterprises