Conditional processing made easy

What is conditional processing?

Conditional processing, also called profiling, allows you to use the same XML source document to create several variants of the deliverables (PDF, RTF, EPUB, etc). For example, your document is a manual for a product which has 3 editions: "Lite", "Professional", "Ultimate", and you want to create a different set of deliverables for each edition.

Implementing conditional processing requires you to set special attributes (called conditional processing attributes or profiling attributes) on the elements you want to include or exclude from the deliverable depending on the variant you want to generate.

For example, let's suppose your document contains 3 paragraphs: first paragraph has no profiling attributes, second paragraph has profiling attribute product="Lite" and third paragraph has product="Professional". If you generate a variant of the deliverable for the "Lite" edition, then this variant will contain the first and second paragraph, but not the third one.

Generating a variant of the deliverable for the "Lite" edition implies applying a profile where product="Lite" to your document. A profile may be seen a named combination of profiling attribute values. In our example, let's call this profile "lite". The "lite" profile comprises a single profiling attribute value product="Lite".

Conditional processing is available for DITA documents and for DocBook documents. See Darwin Information Typing Architecture (DITA) Version 1.2, Conditional processing (profiling). See DocBook XSL: The Complete Guide, Profiling (conditional text) by Bob Stayton.

Why install and use the "Easy Profiling" add-on?

In a nutshell, without the help of the "Easy Profiling" add-on, implementing conditional processing in your DITA or DocBook documents is tedious and error-prone.

Moreover, the "Easy Profiling" add-on allows to assign screen styles to elements having profiling attribute values and/or to elements which are to be included or excluded from the deliverable depending on the selected profile.

How to put the "Easy Profiling" add-on into use?

We'll use a simple DITA bookmap, user_guide.ditamap, referencing just two topics, export_pdf.dita and advanced_features.dita, to explain this process.

First step: specify which profiles you are going to use in your document

This is done using FileNew and then selecting the document template called "Conditional Processing Profiles" found in the category of the document you are authoring ("DITA" in the case of our example).

Edit ".profiles" file
  1. First specify which profiling attributes you are going to use in your document (example: attribute "product"). For each of these attributes, specify all the allowed values (example: attribute values "Lite", "Professional" and "Ultimate").
  2. Then specify one or more profiles, that is, give a name (examples: "lite", "pro", "ultimate") to a combination of profiling attribute values (example: profile "lite" comprises product="Lite").
  3. While at it, give a distinct screen style (CSS style properties) to the “unselected profiles”. That is, give a distinct style to the elements which will be excluded from the deliverable given the selected profile.

    This is done by clicking the "Set Style" button button which is next to the "Conditional processing profiles" document title and then choosing "Style of Unselected Profile" from the popup menu.

    In the dialog box below, excluded elements are given a pink hatched background.

    "Set Style" dialog box
  4. Finally save this special XML document to a file having a ".profiles" extension.

Second step: associate a profile to your document

This is done by using BookMapConditional ProcessingSelect Profile.

In the dialog box below, the "editions.profiles" file created above is associated to DITA bookmap user_guide.ditamap.

"Select Profile" dialog box

Associate a profile to the DITA map and not to the individual topics referenced by this map, then make sure to have checked ToolsUse as Master Document for this map. When this the case, the topics referenced by a map automatically “inherit” the profile of this map.

The same tip applies to DocBook. Associate a profile to the modular book and not to the individual chapters included in this book, then make sure to have checked ToolsUse as Master Document for this modular book.

Third step: set profiling attributes on some elements

The easiest way to set profiling attributes on some elements is to use BookmapConditional ProcessingSet Profiling Attributes.

In the dialog box below, topicref href="advanced_features.dita" found in DITA bookmap user_guide.ditamap is given profiling attribute value product="Professional Ultimate" (which means that this topicref applies to both the "Professional" and "Ultimate" editions or the product being documented).

"Set Profiling Attributes" dialog box

While less convenient, it's also certainly possible to use the Attributes tool to set profiling attributes on some elements. Note that when a ".profiles" file has been associated to the document being edited, undeclared profiling attribute values are reported as semantic errors by the Validity tool.

Semantic error reported by the Validity tool

Fourth step: generate the deliverable corresponding to selected profile

Once a profile has been selected using BookMapConditional ProcessingSelect Profile, suffice to use one of the items of menu BookMapConvert Document to generate the corresponding variant of the deliverable. For example, use BookMapConvert DocumentConvert to PDF to generate "user_guide_lite.pdf" then select profile "ultimate" and use BookMapConvert DocumentConvert to PDF again to generate "user_guide_ultimate.pdf".

Watch the screencast Watch the screencast

Related tutorials

related tutorial Working with master documents