Processing profiled versions

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:

Which method you use depends on these factors:

Single-pass processing

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 filehtml/docbook.xslhtml/profile-docbook.xsl
Multiple chunked HTML fileshtml/chunk.xslhtml/profile-chunk.xsl
XSL-FO filefo/docbook.xslfo/profile-docbook.xsl

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 profile.os to linux. Here are some command examples.

Using xsltproc:
xsltproc  --output  myfile.linux.html  \
     --stringparam  profile.os  "linux" \
    html/profile-docbook.xsl  \

Using Saxon:
java  -cp  "../saxon653/saxon.jar" \
    com.icl.saxon.StyleSheet \
    myfile.xml \
    html/profile-chunk.xsl \
    profile.os="linux" \

Using Xalan:
java  org.apache.xalan.xslt.Process \
    -out  myfile.linux.html \
    -in  myfile.xml \
    -param  profile.os  linux \
    -xsl  html/profile-docbook.xsl 

When the 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 have an os attribute whose value does not match linux are ignored. And of course any elements that do not have an 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, and so on.

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 i386, i486, or i586, then specify the profile.arch parameter as i386;i486;i586.

Two-pass processing

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 xref or link which cannot be resolved with the single-pass processing, or if you are using an XSLT processor that does not support the EXSLT node-set() function.

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  \

Generate output:
     --output myfile.linux.html  \
     html/docbook.xsl  \

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.