conditional processing design

[Michael Priestley <mpriestl@ca.ibm.com>]

Copying this note from an old post to the DITA forum on developerworks,
since it is of interest for today's presentation:

-------------------------------------------------------------------------

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@ca.ibm.com

------------------------------------------------------------------------------------------

Michael Priestley
mpriestl@ca.ibm.com
Dept PRG IBM Canada  phone: 416-915-8262
Toronto Information Development