Topics

Conditional Processing in DITA

Don R. Day <dond@...>
 

One of the subjects on the older, developerWorks "dita" newsgroup
concerned conditional processing. Recently the question came up in a
conversation, so here is a copy of the post that was particularly
complete in explaining "the DITA way" for conditional processing (or
profiling, or effectivity control--whatever you know it as).
--
Don

-------- Original Message --------
Subject: Conditional processing in DITA
Date: Fri, 24 Jan 2003 14:29:48 -0500
From: Michael Priestley <mpriestl@...>
Organization: IBM Canada
Newsgroups: ibm.software.developerworks.xml.dita


There have been some questions in the past about how DITA can support
conditional processing. This is an example of how it could be done,
and a starting point for discussion.

Here are the basics:

Conditonal processing means filtering or flagging information based on
processing-time criteria (could be runtime or buildtime, same process
applies. DITA tries to implement conditional processing in a
semantically meaningful way: rather than bunches of arbitrary values
accumulating in a document over time, with meaning only to the
original author, we encourage the authoring of metadata using
attributes on content, which can then be leveraged by filtering,
flagging, search, or indexing processes, rather than being suitable
for filtering only.

There are four attributes intended for conditional processing,
available on most elements. they are:
product: the product that is the subject of the discussion.
platform: the platform on which the product is deployed.
audience: the intended audience of the text
rev: the revision or draft number of the current document
otherprops: anything else

Each attribute takes zero or more space-delimited string values. For
example, you can use the product attribute to identify that an element
applies to two particular products.

Example source:

<p audience="administrator">Set the configuration options:
<ul>
<li product="extendedprod">Set foo to bar</li>
<li product="basicprod extendedprod">Set your blink rate</li>
<li>Do some other stuff</li>
<li platform="Windows">Do a special thing for Windows</li>
</ul>
</p>

At processing time, you specify the values you want to exclude and the
values you want to flag. For example, let's say I want to flag info
that applies to administrators,and exclude stuff that applies to the
extended product, since I am building the docs for a mixed audience
who are using the basic product.

Example process conditions:

<prop att="audience" val="administrator" action="flag" use="ADMIN"/>
<prop att="product" val="extendedprod" action="exclude"/>

At output time, you'd want the paragraph flagged, and the first list
item excluded (since it applies to extendedprod), but the second list
item still included (even though it does apply to extendedprod, it
also applies to bsaicprod, which we didn't say to exclude).

Result should be something like:

ADMIN Set the configuration options:
- Set your blink rate
- Do some other stuff
- Do a special thing for Windows

Exclusion logic

- when deciding whether to exclude a particular element, evaluate each
attribute, and then evaluate the set of attributes:
- if all the values in an attribute have been set to "exclude", the
attribute evaluates to "exclude"
- if any of the attributes evaluate to exclude, the element is excluded.

This should make sense if you think it through. If a paragraph applies
to three products and you've excluded all of them, you should exclude
the paragraph; even if the paragraph applies to an audience or
platform that you aren't excluding.

Flagging logic

Flagging works the same way, except that if everything evaluates to
the condition we output an extra flagging element (a text string or an
image), instead of just removing the element.

Probably the simplest way to flag would be to output the flagging text
in an <em> tag in HTML, with a class setting "flag" that you can use
CSS to style as white, in small caps with a purple background (use
whatever you prefer, I'm just picking a style that I think would stand
out).

Example output in HTML (assuming everything was set to flag):
<p><em class="flag">ADMIN</em> Set the configuration options:
<ul>
<li><em class="flag">BP </em>Set foo to bar</li>
<li><em class="flag">BP </em><em class="flag">EP </em>Set your blink
rate</li>
<li>Do some other stuff</li>
<li><em class="flag">WINDOWS </em>Do a special thing for Windows</li>
</ul>
</p>

The "use" attribute could also take an image element, as long as you
know the image will be available at runtime.

Some thoughts on authoring

This model is intentionally simple, and people with experience
authoring with full boolean support may find it restrictive. However,
this comes out of our own experiences with writing reusable content:
when you have multiple authors working on the same set of documents, a
complex processing model quickly becomes more trouble than its worth.

Some last thoughts on processing

- this model is scalable from simple file systems all the way to
full-scale content management; this keeps your content insulated from
processing infrastructure
- probably the simplest way to incorporate exclusion processing is via
a preprocess step, eg with an XSLT transform. The exclusion logic
could be combined with content-referencing resolution, so that conrefs
are only resolved when they need to be.
- for flagging processing, we'd need to extend the final-stage output
transform, adding a call in each template to a "flageval" template
that would generate a flag if needed.


Anyway, I hope this can foster some discussion on conditional
processing. Does the scheme make sense? Does it meet your needs?
Hoping to hear from folks,

Michael Priestley
DITA Specialization Architect
mpriestl@...