OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.


Help: OASIS Mailing Lists Help | MarkMail Help

dita message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]

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

This is basically the same as our approach, which is reassuring. Thanks.

One question it raises, though, is whether it's more appropriate to use a topicref specialization or a metadata domain. I think I prefer the metadata approach. To simplify processing, it would be nice to be able to assume that ditaval rules for a given scope appear early in that scope, and metadata necessarily comes before other child topicrefs. For example, this would require two map passes:

  <topicref href="A.dita"/>
  <topicref href="B.dita"/>
  <ditavalref href="expert.ditaval"/>

While this only takes one:

    <ditavalref href="expert.ditaval"/>
  <topicref href="A.dita"/>
  <topicref href="B.dita"/>

Also, I'm pretty touchy about overburdening topicref. I devoutly wish keydef was its own thing, for instance. I'm convinced that a lot of the complexity complaints about DITA stem from the fact that predicting how a given topicref will (or, in the case of we poor application developers, should) affect output can take a lot of work, especially for newcomers. But I think that ship has sailed, and as such I don't feel that strongly one way or the other in this case.

As for conditional processing issues Eliot raises, I'm not sure I understand the problem. Since a ditaval reference only applies to its container, you could pick up and drop rules during normal map processing. You'd have to apply conditional processing before picking up new DITAVAL rules, but that shouldn't be too difficult. So say you had this:

   <ditavalref href="expertFlagging.ditaval" product="NewFancyEngine"/>

If you specified a DITAVAL file at the command-line, those would be the global, "baseline" rules. If those rules excluded product="NewFancyEngine", then the step that picked up new DITAVAL rules as it went along would never see the ditavalre. Maybe I'm not understanding the concern, but I think it's manageable.


-----Original Message-----
From: Robert D Anderson [mailto:robander@us.ibm.com] 
Sent: Thursday, September 01, 2011 4:05 PM
To: Nitchie, Chris
Cc: dita
Subject: Re: [dita] Design discussion for associating DITAVAL rules with a map

The approach we've been experimenting with over the last month is sort of a
combination between Chris's options (1) and (4).

In particular, we've got a domain that defines a topicref specialization
called <ditavalref>. It defaults the attributes format="ditaval" and

The element itself is specified as a child of the branch that it's meant to
filter. The logic here is very similar to the subjectdef element we've got
in DITA 1.2. For example, when you assign a subject, you do something like
<topicref href="thing.dita">
  <subjectdef keyref="thing-subject"/>

So, similarly, when the ditavalref is specified as a child of <topicref>,
it's done like this:
<topicref href="productA.dita">
  <ditavalref href="filter-for-A.ditaval"/>
  ...other topics...

This allows for filter conditions that apply to that entire branch without
impacting other branches. It gets much more complicated when you have two
ditavalref elements as children; we have very strong use cases around this,
which actually helped push us towards this design, but I'm wary of going
into too much detail in this email and distracting from the core idea of
the <ditavalref> element on a branch.

It's worth noting that when using this element, it is distinct from a
DITAVAL file that's associated with the whole map as you would do so today
(in DITA-OT terms, that would be one passed in from the command line). So,
you can still apply a global set of filters, but then use this new
capability for finer grained control within a document.

Provided that general approach makes sense, I'll go in to more detail about
the more complicated aspects, such as how we're trying to handle multiple
ditavalref elements on a single branch.

Robert D Anderson
IBM Authoring Tools Development
Chief Architect, DITA Open Toolkit

From:	"Nitchie, Chris" <cnitchie@ptc.com>
To:	"dita" <dita@lists.oasis-open.org>
Date:	09/01/2011 14:56
Subject:	[dita] Design discussion for associating DITAVAL rules with a

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

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:

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

To repeat the same topic with different profiles:

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

You could also nest profiles:

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

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

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 Nitchie
Senior Software Engineer

T 734.352.2879   F 734.997.0201
E cnitchie@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:

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]