Search results

DITA: Conditional profiling

You can add attributes to elements and then filter your transforms to include any element that has attributes with certain values.

Available attributes

DITA offers a set of standard attributes that you can apply to most elements. The general attributes are as follows:

  • audience
  • platform
  • product
  • props
  • otherprops
  • rev

You set the values you want for each attribute. You can't change the names of the attributes (because they're part of the DITA schema), but you can edit their values. (The props and otherprops are meant to be generic to adapt to any situation.)

To set up your attributes and values in OxygenXML, enter the Author view and click the Profiling Attributes button Profiling Attributes button. Then select Profiling Settings.

Profiling settings

Alternatively, go to DITA > Profiling/Conditional Text > Edit Profiling Attributes.

In the Profiling Attributes section, edit the values for each of the attributes.

DITA Profiling attributes

Creating Profiling Condition Sets

While you're on the Profiling Attributes screen, move to the next section below: Profiling Condition Sets. Here you can define the combinations of the profiling attributes you want for your various transformation scenarios.

DITA Profiling condition sets

Now configure your transformation scenarios with the right condition sets:

  1. Click the Transform Scenarios button Transform Scenarios button.
  2. Select New.
  3. Select DITA OT Transformation.
  4. Select Webhelp and click OK.
  5. Name the transformation scenario.
  6. Click the Filters tab.
  7. Select the profiling condition set you configured. Then click OK. (You may need to toggle the radio button to another selection and then come back to select Use profiling condition set — not sure if that's a UI quirk.)
  8. Select the transform scenario you just created and click Apply Associated.

    For example, if you selected a condition set with platform="mac", only the topics with platform="mac" would be included. Any elements with platform="pc" or other attribute values would be excluded.

Without Oxygen, you would need create a DITAVAL file that explains what should be excluded. See DITA: Ditaval files (filtering attributes from your transforms) for more details.

In the DITAVAL file method, you identify the attribute and value and then apply an exclude action. (You don't apply an include, just exclude.) You can still use DITAVAL files with Oxygen if you want.

With Oxygen, however, the conditional profiling works more intuitively. In Oxygen, when you create a condition set that includes certain values, other values not selected from that same attribute are excluded. However, if you don't apply any attribute to content, everything is included.

Applying attributes to elements

Now you can start using these attributes almost any DITA element. Suppose you want to apply an attribute to your map so that you can use the same map for each product. You might apply the attributes like this:

  <topicrefhref="maintaining_brakes_71_fx.html"product="trek"platform="71_fx"/>
  <topicrefhref="maintaining_brakes_72_fx.html"product="trek"platform="72_fx"/>

Or to a p element:

   <p product="trek">You can adjust your brakes by loosening the bolt with a 5mm allen wrench and sliding the brake pads to the distance you want. Then tighten the bolt.</p>
  

Or to pretty much any other element. If you want to be even more granular, you can surround a word with ph tags (for phrase). The tags can be applied to any word or phrase, so if the element you want doesn't allow you to apply these general attributes (such as with the entry element in a table), you can just put ph tags inside the element.

  Your bike is equipped with Shimano <ph platform="71_fx">Ultegra components</ph><ph platform="72_fx 73_fx">105 components</a>.
   

When adding multiple values to an attribute, just separate the values with a space.

   <p platform="mac linux">You have a web server already available in your OS.</p>
  

Viewing conditions in the Author mode

When you're in the Author mode, you can switch to the condition set that you want to see. If you switch to Trek 7.3 FX, only the content that meets that condition set appears in the Author view.

You can also set it so that the content not included is semi-transparent. This mode makes it easy to edit content that has conditional profiling. Here's an example. The content with the attribute for gary_fisher is transparent because I've selected to only see the trek content.

DITA editor

About Tom Johnson

Tom Johnson

I'm an API technical writer based in the Seattle area. On this blog, I write about topics related to technical writing and communication — such as software documentation, API documentation, AI, information architecture, content strategy, writing processes, plain language, tech comm careers, and more. Check out my API documentation course if you're looking for more info about documenting APIs. Or see my posts on AI and AI course section for more on the latest in AI and tech comm.

If you're a technical writer and want to keep on top of the latest trends in the tech comm, be sure to subscribe to email updates below. You can also learn more about me or contact me. Finally, note that the opinions I express on my blog are my own points of view, not that of my employer.