| Chapter 25. Profiling (conditional text) | ||
|---|---|---|
 | Part IV. Special DocBook features |  |
| Chapter 25. Profiling (conditional text) | ||
|---|---|---|
| | Part IV. Special DocBook features | |
Table of Contents
Profiling is the term used in DocBook to describe conditional text. Conditional text means you can create a single XML document with some elements marked as conditional. When you process such a document, you can specify which conditions apply for that version of output, and the stylesheet will include or exclude the marked text to satisfy the conditions. This feature is useful when you need to produce more than one version of a document, and the versions differ in minor ways. Then you don't have to maintain separate documents that are nearly but not quite the same, and thereby run the risk of the separate documents getting out of synchronization as you make changes. With conditional text, you keep all the variations in the same document and select the ones you want at production time.
This feature is typically used to create different versions of a document for different audiences. That's where the term profiling comes in. You can create a document profiled for a particular audience. For example, software that runs on different platforms might need different installation instructions for each platform, but might otherwise be the same. You can create one version profiled for Linux customers and another profiled for Windows customers.
To mark text for inclusion or exclusion, the DocBook DTD provides several appropriate attributes that are common to most elements. You need to select one or more attributes and assign key words based on the conditions you want to apply. For example, the os attribute is used to specify a software operating system. You can assign the keywords linux or win to mark an element as conditional for Linux or Windows, respectively. It is up to you to pick the key words, and you must be consistent in their usage.
The following table summarizes the common attributes that can be used to conditionalize elements.
Table 25.1. Profiling attributes
You can also designate any attribute name as a profiling attribute by setting a couple of stylesheet parameters. This is most useful when you have extended the DTD to add custom attributes. See the section “Custom profiling attribute” for more information.
The only profiling attribute that requires particular care is role, which might be used for other purposes besides marking conditional text. See the section “Using the role attribute for profiling” for more information. If the condition key words you want to use don't seem to fit any of the other profiling attribute descriptions, then use the general purpose condition attribute since it is made for that purpose.
The following is an example of how one of these attributes might be used.
<sect1 os="win"> <title>Installation on Windows</title> ... </sect1> <sect1 os="linux"> <title>Installation on Linux</title> ... </sect1>
This example has two parallel sect1 elements with different values for the os attribute, one for the Windows version and one for the Linux version. In general you only want one of these sections to appear in the output for a particular version.
A conditional attribute applies to the element and its children, so each entire section is conditionalized by adding the attribute to the sect1 start tag. You can use these common attributes on almost any element, from high level elements like chapter down to low-level elements like para or even inline elements within a paragraph.
| DocBook XSL: The Complete Guide - 3rd Edition | PDF version available | Copyright © 2002-2005 Sagehill Enterprises |
| |  | |
| Refentry to man |  | Marking small bits of text |