Chapter 26. Profiling (conditional text)

Table of Contents

Marking conditional text
Marking small bits of text
Multiple profiling conditions
Processing profiled versions
Single-pass processing
Two-pass processing
Customization and profiling
Validation and profiling
Custom profiling attribute
Adding new profiling attributes
Adding attributes to the DTD
Adding attributes to RelaxNG
Profiling with new attributes
Using the role attribute for profiling

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 do not 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.

Marking conditional text

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. The table also shows the profiling parameter used to select content marked with each attribute, as described in the section “Processing profiled versions”.

Table 26.1. Profiling attributes

Attribute NameDescriptionProfiling parameter
archComputer or chip architecture, such as i386.profile.arch
audienceIntended audience of the content, such as instructor. Added in DocBook version 5.0.profile.audience
conditionGeneral purpose conditional attribute, with no preassigned semantics.profile.condition
conformanceStandards conformance, such as lsb (Linux Standards Base).profile.conformance
langLanguage code, such as de_DE.profile.lang
osOperating system.profile.os
revisionEditorial revision, such as v2.1.profile.revision
revisionflagRevision status of the element, such as changed. This attribute has a fixed set of values to choose from.profile.revisionflag
roleGeneral purpose attribute, with no preassigned semantics. Use with caution for profiling.profile.role
securitySecurity level, such as high.profile.security
statusEditorial or publication status, such as InDevelopment or draft.profile.status
userlevelLevel of user experience, such as beginner.profile.userlevel
vendorProduct vendor, such as apache.profile.vendor
wordsizeWord size (width in bits) of the computer architecture, such as 64bit. Added in DocBook version 4.4.profile.wordsize

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.

Caution

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 do not 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.