[dita] Design discussion for associating DITAVAL rules with a map

["Nitchie, Chris" <cnitchie@ptc.com>]

There are a number of proposals on the DITA 1.3 list - 13036 and 13059 in particular - related to associating DITAVAL rules with all or part of a map. At PTC, we're in the progress of designing out features for our next release, which will ship early next year (i.e. well before DITA 1.3 is baked). One of our requirements, though, is this capability - associating conditional processing rules with a map. With that in mind, we've been doing some thinking around potential designs. We'll almost certainly need to implement something well before DITA 1.3 is finalized, and we really don't want to do something that is completely out of line (or worse, contradictory to) what finally winds up in the standard. So I wanted to run our current thinking by the group and get some feedback.

There are a couple of ways we could do this via specialization/custom processing without having to modify DITA 1.2.

1.	As a rule, <topicref format="ditaval" href="..."/> specifies the rules to apply to the whole map. TBD what happens when there are more than one.
2.	A new @base attribute specialization that would be ignored on everything but the root map element, specifying the DITAVAL file to use for the whole map, e.g. <map profileref="expert.ditaval">
3.	Similar to #2, but use @props instead of @base, and allow it to be applied on any map or topicref element, thus allowing the rules to be scoped, e.g. <topicgroup profileref="expert.ditaval">. 
4.	Similar to #3, but implemented as a metadata domain specialization, e.g. <topicgroup><topicmeta><profileref href="expert.ditaval">.

My current thinking is that Option 4 provides the greatest flexibility while breaking the fewest rules. Option 1 isn't flexible enough and could produce confusing results if a sub-map unexpectedly references a ditaval file. Option 2 is easy to implement and use, but isn't very flexible. Option 3 is simpler for authors to see and understand, but it's a violation of the way @props specializations are supposed to work (it should be a space-delimited set of values to use in conditional processing). So I think a new metadata element is what's called for.

So to associate a DITAVAL file with a whole map:

<map>
  <title>Expert Book</title>
  <topicmeta>
    <profileref href="expert.ditaval"/>
  </topicmeta>
 ...
</map>

To repeat the same topic with different profiles:

<topicref href="chapter1.dita">
  <topicmeta>
    <profileref href="student.ditaval"/>
  </topicmeta>
</topicref>
<topicref href="chapter1.dita">
  <topicmeta>
    <profileref href="teacher.ditaval"/>
  </topicmeta>
</topicref>

You could also nest profiles:

<topicref href="expertsGuide.dita">
  <topicmeta>
    <profileref href="expert.ditaval"/>
  </topicmeta>
  <topicref href="changingTheOil.dita">
    <topicmeta>
      <profileref href="productX.ditaval"/>
    </topicmeta>
  </topicref>
</topicref>

In this case, the effective rules for "changingTheOil.dita" would be the combination of the rules in "expert.ditaval" and "productX.ditaval".

There's an open question of what to do in this case if the nested DITAVALS specify conflicting rules. For example, if "expert.ditaval" contained this for some reason:

<prop action="include" att="product" val="ProductY"/>

And productX.ditaval contained this:

<prop action="exclude" att="product" val="ProductY"/>

What would be the effective action for product="ProductY"? There are a couple of potential solutions - outermost wins, innermost wins, explicit "include" trumps, or it might interact with some of the other new DITAVAL proposals for cascading behavior in 1.3 - but we haven't settled on an answer yet.

I think in the majority of cases, you'll just have one DITAVAL file associated with the whole map, but I think there are use cases we'll want to support with different profiling rules at different locations in the same map. Does this proposal, rough though it is, sound like reasonable start?

At this point, we're still in the design phase, and no implementation has happened yet, so we're not married to one approach over another. I'd just like to know whether we should drastically rethink the above in light of the intentions of those folks designing other DITAVAL changes for 1.3.

Chris


Chris Nitchie
Senior Software Engineer

T 734.352.2879   F 734.997.0201
E cnitchie@ptc.com

PTC.com