2. Working with conditional processing profiles without the facilities added by the "Easy Profiling" add-on

Conditional processing, also called profiling or conditional text, means that 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 the output, and the XSLT stylesheet or the DITA processor will include or exclude the marked text to satisfy the conditions.

Let's suppose you are writing a manual for a software product which is available in 3 editions: Lite, Professional and Ultimate. You want to author a single manual (as the vast majority of its contents is common to the 3 editions), but you want to generate 3 different PDF deliverables, one for each edition (otherwise your customers would find your manual mixing info about the 3 editions confusing to read).

DITA example: the conditional processing attribute used in the example below is product. It's a standard DITA profiling attribute.

<p>First make sure that your work has been saved to disk.</p>

<p product="Lite">You need to install a third-party application such as
<xref format="html" href="http://www.pdfforge.org/pdfcreator"
scope="external">PDFCreator</xref>. Once this is done, select menu item
<menucascade> <uicontrol>File</uicontrol><uicontrol>Print</uicontrol>
</menucascade> and choose to print to the “PDF printer” added by this
third-party application.</p>

<p product="Professional Ultimate">Then simply select menu item
<menucascade><uicontrol>File</uicontrol><uicontrol>Export as PDF</uicontrol>
</menucascade>.</p>

<p product="Professional">Note that dialog box displayed by this menu item
has no "<uicontrol>PDF/A Format</uicontrol>" checkbox. This format is
available only in the Ultimate Edition.</p>

<p product="Ultimate">The dialog box displayed by this menu item has a
"<uicontrol>PDF/A Format</uicontrol>" checkbox. Check "<uicontrol>PDF/A
Format</uicontrol>" if you want to create a PDF file well-suited to
long-term archiving.</p>

First paragraph having no product attribute applies to all editions and thus, will be included in all deliverables. Second paragraph applies only to the Lite edition. Third paragraph applies to both Professional and Ultimate editions. Fourth paragraph applies only to the Professional edition. Fifth paragraph applies only to the Ultimate edition.

For a DITA document, a conditional processing profile, that is, a specification of which marked text should be included, excluded or flagged, is expressed using a DITAVAL file[1].

The following ".ditaval" file may be used to generate the deliverable for the Lite edition:

<val>
  <prop action="exclude" att="product" />
  <prop action="include" att="product" val="Lite" />
</val>

You must pass the location of this ".ditaval" file as a parameter to the DITA processor in order to generate the deliverable for the Lite edition. This deliverable will contain only the first and second paragraphs.

Working with conditional processing profiles without any assistance poses the following problems:

  1. Setting conditional processing attributes on some elements is tedious and error prone. For example, it's common to make a typo in the value of the attribute ("light" instead of "Lite").

  2. There is no way to visualize on screen which are the marked elements other than switching to the source view of the document.

  3. The ".ditaval" files must be created by hand. In the case of the above DITA example, you'll have to create 3 ".ditaval" files, one for each profile, which is tedious and error prone.

  4. You must explicitly pass the location of the ".ditaval" file as a parameter to the DITA processor when you generate a deliverable. This too can quickly become tedious and error prone.



[1] For a DocBook document, which marked text should be included or excluded is expressed using special XSLT stylesheet parameters. More information in DocBook XSL: The Complete Guide.