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 File→New 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).

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").
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").
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 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.
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 BookMap→Conditional Processing→Select Profile.

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

Associate a profile to the DITA map and not to the individual topics referenced by this map, then make sure to have checked Tools→Use 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 Tools→Use 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 Bookmap→Conditional Processing→Set 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).

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 BookMap→Conditional Processing→Select Profile, suffice to use one of the items of menu BookMap→Convert Document to generate the corresponding variant of the deliverable. For example, use BookMap→Convert Document→Convert to PDF to generate "user_guide_lite.pdf" then select profile "ultimate" and use BookMap→Convert Document→Convert to PDF again to generate "user_guide_ultimate.pdf".

Watch the screencast