Re: [dita] Design discussion for associating DITAVAL rules with amap

[Eliot Kimber <ekimber@reallysi.com>]

I started write that I preferred option (1) because that way the topicref
declares the dependency in a generic way. However, as <data> can use @keyref
rather than @href, option (4) allows you to get the benefits of both if you
use a key for the DITAVAL file, e.g.:

<map>
<topicmeta>
 <profileref keyref="ditaval-expert"/>
</topicmeta>
<keydef keys="ditaval-expert"
  href="../ditavals/ditaval-expert.ditaval"
  format="ditaval"
/>
...
</map>

I think option (3) is not acceptable, for the reasons you say: it's a misuse
of @props.

Option (2) would be OK but I would definitely prefer (1) or (4).

Thinking about this just now, it seems like there's a bit of a potential
bootstrapping issue, in that if a DITAVAL reference were itself conditional
there'd be no way to apply the conditionality unless a separate DITAVAL file
is specified at run time. Which means at least two phases of filtering, a
first phase to determine if any DITAVAL references are applicable and then
processing using the effects of those DITAVAL references. There's also a
potential interaction with key resolution as well, since some references to
DITAVAL files might involve keys and the key definitions might be directly
or indirectly conditional.

For example, I might have different DITAVAL flagging configurations that I
want to be used or not used based on other conditions. The flagging
configurations are probably largely invariant for a given publication, but
the filtering conditions are not--I want to be able to specify at runtime a
set of filtering conditions that will have the effect of selecting the
correct flagging configuration.

Even if you disallowed making DITAVAL references conditional, you couldn't
disallow making the containers of the references or pointers to the
containers of references conditional, so you have to address the problem.

If the purpose of the reference is really just documentation, e.g., when you
run this map, apply this DITAVAL file, then it's fine, because the
consumption of the DITAVAL reference is out of band of the regular DITA
processing. 

I don't object to the general idea of referencing DITAVAL files from maps,
but I think it would require us to say more about how filtering processing
should or must be implemented to account for the case of both run-time and
map-referenced DITAVAL files.

Cheers,

Eliot

On 9/1/11 1:50 PM, "Nitchie, Chris" <cnitchie@ptc.com> wrote:

> 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
> 
> 
> 
> ---------------------------------------------------------------------
> To unsubscribe from this mail list, you must leave the OASIS TC that
> generates this mail.  Follow this link to all your TCs in OASIS at:
> https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php
> 

-- 
Eliot Kimber
Senior Solutions Architect
"Bringing Strategy, Content, and Technology Together"
Main: 512.554.9368
www.reallysi.com
www.rsuitecms.com