Re: [dita] otherprops syntax - should we specify?

["W. Eliot Kimber" <ekimber@innodata-isogen.com>]

Michael Priestley wrote:

> A specific note about NOT values:
> - a NOT value cannot be easily used for anything except filtering (eg hard 
> to flag).
> - a NOT value can be rendered invalid when new platforms/products are 
> added (does the paragraph still apply to every platform except Linux once 
> you add other flavours of Unix?)
> - if a NOT value absolutely must be used, it can be handled without 
> explicit boolean support by creating a new unitary value; eg instead of 
> "NOT Linux" use "NOTLinux". 

Based on my practical experience with conditionality (what I normally 
call "applicability" because it defines to which conditions an element 
applies to), I agree with Michael's overall analysis, particularly that 
a complete boolean expression language is too much overhead for most 
applications.

I also agree generally with the statement that in a map-based re-use 
environment you *can* reduce some of the conditionality complexity by 
having different maps. However, in discussing these issues with one of 
my clients, who has both complex re-use requirements and complex 
conditionality requirements and many different authoring groups, it 
became clear that some groups would accept having different maps for 
different sets of conditions and some would not. Some of this stems from 
existing practice and work habits, some of it stems from limitations 
imposed by different tools, some of it stems from practicalities of 
various business processes, such as localization workflows. So even 
though Michael is correct, you are not likely to get universal 
acceptance of the approach.

For the latest application I've built for a client, we were able to 
satisfy the applicability requirements by using lists of single tokens 
that represented either positive statements, e.g., 
presentation_target="html print" or negative statements, e.g., 
presentation_target="not-help". A list of tokens is an implied logical 
OR if all the statements are positive. That is, an element is applicable 
if *any* of the conditions apply. An element is not applicable if and 
only if none of the conditions apply. Negative conditions can be 
interpreted as implying a list of positive conditions reflecting the 
inverse of the negative statement.

The biggest challenge was in the implementation, where we found we had 
to use procedural logic to correctly interpret some combinations of 
positive and negative values, but it was never a problem for authors 
(that is, we couldn't implement it in XSLT with just simple value 
matches--I found it easier to put this logic in Java).

The biggest issue I've run into is in using distinct attributes for 
different axes of conditionality. The problem of course is that as new 
axes are discovered you must update the DTDs to add attributes for the 
axes. If you are defining the attributes as enumerated values you have 
to update the DTDs whenever the list of values changes. If you know that 
the axes are dynamic or likely to change in the future you start to 
think that it might be better to have a single "applicability" attribute 
and use condition names to distinguish the axes. As the axes tend to 
reflect local business processes, business objects, and practice, it is 
almost a certainty that they will change over time.

I think this is the case in DITA as an interchange standard since it's 
impossible for DITA to anticipate all the possible axes of its users, so 
either you need a way to declare new axis attributes (pre my earlier 
email) or you use one attribute and put the axes in the condition names).

If we say that condition names are namespace-qualified names, then you 
have the opportunity to formally bind an axis to a namespace, providing 
some hope of binding the axis to a formal definition of the semantics of 
that axis. It also reflects that a given axis is in fact a space of 
names, that is, names of conditions. For example, I might do something like:

<mytopic 
xmlns:rend_targ="http://www.example.com/ns/condition_axes/rendition_target";
xmlns:market_region="http://www.example.com/ns/condition_axes/marketing_region";>
   ...
   <mytopicbody>
     <p applicability="rend_targ:print rend_targ:html 
market_region:amea">For AMEA only</p>
     <p applicability="rend_targ:print rend_targ:html 
market_region:northamerica">For North America only</p>
    ...
   </mytopicbody>
</mytopic>

In use cases where the conditionality requirements demand full boolean 
logic, the approach I tend to take is to add indirection by creating 
"condition definitions" where each condition definition has a unique 
name within some scope (either within its axis or across all conditions, 
whatever is most appropriate). This provides users with a simple list of 
applicability keywords and centralizes the complexity to a separate 
location where it can be managed by specialists.

This also gives you a place to define "effectivity messages". 
Effectivity is orthoganal to applicability in that you only need an 
effectivity statement if a given rendition includes information for two 
different conditions within the same axis. For example, if I have the 
axis "engineering change" and I can publish versions of the document 
that reflect a single engineering change being appliable or that reflect 
multiple engineer changes, in the first case I don't need effectivity 
statements because there's no ambiguity, in the second case I do. Thus 
whether or not you put out an effectivity statement is a function of the 
rendition conditions, not the core information.

The source might look like this:

<procedure>
   ...
   <step_alts>
     <step applicability="ec_10-c">Attach nut p/n 23456 to bolt p/n 
56437. Tighten to 32nm.</step>
     <step applicability="ec_12-d">Attach nut p/n 76543 to bolt p/n 
56437. Tighten to 26nm.</step>
   </step_alts>
   ...
</procedure>

That is, in the first case, my rendition might look like this:

     Step 2. Attach nut p/n 23456 to bolt p/n 56437. Tighten to 32nm.

In the second case, my rendition might look like this:

   For E/C 10-c:

     Step 2. Attach nut p/n 23456 to bolt p/n 56437. Tighten to 32nm.

   For E/C 12-d:

     Step 2. Attach nut p/n 76543 to bolt p/n 56437. Tighten to 26nm.


The DITA standard, as far as I can tell, makes no explicit provision for 
effectivity. I don't know that it needs to because effectivity issues 
can be pushed out to the "condition specification". For example, to 
satisfy the above example, I might have condition definitions like this:

<condition_defs>
   <condition name="ec_10-c">
     <true_when>EC_10-c</true_when>
     <effectivity_statement>For E/C 10-c</effectivity_statement>
   </condition>
   <condition name="ec_12-d">
     <true_when>EC_12-d</true_when>
     <effectivity_statement>For E/C 12-d</effectivity_statement>
   </condition>
</condition_defs>

This condition definition mechanism can be completely outside the DITA 
parts of the application since it is only applied during authoring or 
rendition and doesn't affect the base document syntax at all.

I've seen this requirement most in aircraft maintenance information 
where the conditions might be "if AA AND EC 123 applied AND operating 
environment is "desert" AND operation hours > 1000". This type of 
condition usually reflects some business object or condition that really 
needs to be defined as a distinct thing. Thus, even though it could, in 
theory have been expressed as a sequence of simple conditions, it better 
fits the business process to objectify it in this way. In addition, the 
processing of the conditions can then be as simple or sophisticated as 
required without changing the authoring interface or the core document 
markup.

Note that this indirect approach can always be retrofitted to the simple 
keyword approach, so it could be applied to a DITA document unilaterally 
if needed. That is, there's no need for DITA to step up to this level of 
complexity unless we decided it was a common requirement, which it 
probably isn't.

Cheers,

Eliot
-- 
W. Eliot Kimber
Professional Services
Innodata Isogen
9390 Research Blvd, #410
Austin, TX 78759
(512) 372-8122

ekimber@innodata-isogen.com
www.innodata-isogen.com