DocBook Tips: Profiling (Conditional Content)


docbook, profiling

Diane Fleming works heavily on the OpenStack API documentation - in this post she covers profiling for Docbook.

What is profiling?

DocBook uses the term profiling to describe conditional text. DocBook provides a set of profiling attributes that you can include on DocBook tags to mark some elements as conditional.

Let’s say you want to create two versions of a document from one set of XML source files: One version of the document is for beginning programmers and the other is for advanced programmers.

The following basic steps and example show you how to use profiling to accomplish this.

Basic steps

The simplest implementation of profiling requires three easy steps: Choose a profiling attribute, create profiles in your pom.xml file, and mark elements as conditional by using the selected profiling attribute.

  1. Choose the profiling attribute that makes sense for your document. Because you want to create document versions based on the audience, this example uses the audience profiling attribute.

    Then, create a string to represent each audience. For example, you might use beginner for beginning programmers and advanced for advanced programmers.

  2. Add the following profiles to the appropriate configurations in your pom.xml file:

    <configuration>
        <includes>os-devguide.xml</includes>
        <profileAudience>beginner</profileAudience>
    </configuration>
    <configuration>
        <includes>os-devguide.xml</includes>
        <profileAudience>advanced</profileAudience>
    </configuration>
  3. In the XML source files, tag the content that you want to appear in the beginner version of the document as follows:

    <section audience="beginner">
      <title>Programming Concepts</title>
      ...
    </section>

    Tag the content that you want to appear in the advanced version of the document as follows:

    <section audience="advanced">
      <title>Advanced Concepts</title>
      ...
    </section>

    For content that is common to both versions of the book, tag that content as you normally would: No need for conditions.

Example

The following example shows these profiling attributes in context.

Two books are generated from the same pom.xml file. One execution defines a beginner guide, and the other defines an advanced guide.

<?xml version="1.0" encoding="UTF-8"?>
<executions>
    <execution>
        <id>os-devguide-beginner</id>
        <goals>
        <goal>generate-webhelp</goal>
        </goals>
        <phase>generate-sources</phase>
        <configuration>
            <includes>os-devguide.xml</includes>
            <profileAudience>beginner</profileAudience>
        </configuration>
    </execution>
    <execution>
        <id>os-devguide-advanced</id>
        <goals>
        <goal>generate-webhelp</goal>
        </goals>
        <phase>generate-sources</phase>
        <configuration>
            <includes>os-devguide.xml</includes>
            <profileAudience>advanced</profileAudience>
        </configuration>
    </execution>
</executions>

In the XML source file, you might include three sections that are tagged as follows:

<section audience="beginner">
  <title>Programming Concepts</title>
  ...
</section>
<section>
  <title>Concepts for Everyone</title>
  ...
</section>
<section audience="advanced">
  <title>Advanced Concepts</title>
  ...
</section>

The beginner guide shows the first and second sections. The advanced guide shows the second and third sections. If you have a configuration in your pom.xml file without a profile, that book shows only the second section.

You can use the profiling attribute on most tags. For example, you might tag a paragraph like this:

<para>If you are a <phrase audience="beginner">beginner</phrase>
<phrase audience="advanced">advanced programmer</phrase>,
read <phrase audience="beginner">Programming Concepts</phrase>
<phrase audience="advanced">Advanced Concepts</phrase> section.</para>

In the beginner guide, the following text appears: If you are a beginner, read Programming Concepts.

In the advanced guide, this text appears: If you are an advanced programmer, read Advanced Concepts.

Gotcha

When you use profiling, make sure to place conditional tags on the correct elements.

For example, the following mark-up can produce an error:

<procedure>
<title>My procedure</title>
    <step><para audience="beginner">A step for beginners.</para></step>
    <step><para audience="advanced">A step for advanced programmers.</para></step>
    <step><para>A step for everyone.</para></step>
</procedure>

Why? If your pom.xml file does not specify any profiles, the <step> tags have no content because the interior <para> tags are ignored. Empty steps cause a build error.

To correct the error, use the following mark-up:

<procedure>
<title>My procedure</title>
    <step audience="beginner"><para>A step for beginners.</para></step>
    <step audience="advanced><para">A step for advanced programmers.</para></step>
    <step><para>A step for everyone.</para></step>
</procedure>

This example works even if the pom.xml file does not provide profiles for these audiences: The conditionalized steps are ignored. However, because the procedure contains one step that is not conditionalized, the procedure successfully displays with one step.

©2014 Rackspace, US Inc. About Rackspace | Fanatical Support® | Hosting Solutions | Investors | Careers | Privacy Statement | Website Terms | Trademarks | Sitemap