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: Branch filtering: key names vs key scopes


Now for the promised bigger question. Assume the following branch in a map:
<topicref href="">
  <ditavalref href="">
  <ditavalref href="">
  <topicref href="" keys="install"/>
  ...lots more topics, with keys...
</topicref>

The two <ditavalref> elements result in two instances of the branch - one filtered for novice, one filtered for expert. If keys are not adjusted, then keys="install" will be defined in both instances of the branch; the second instance (installing topic, filtered for expert) can never be addressed, because the first declaration of keys="install" will always win.

The <ditavalref> element as currently defined allows two different mechanisms to deal with this: elements to add a prefix/suffix to keys in the branch, and elements to add a prefix/suffix to the branch's key scope. Chris Nitchie's comments in the review suggest that renaming the key scope should always be preferred, and use of direct key renaming should be discouraged, and at this point I have to agree. Assume the following example:

<topicref href="">
  <ditavalref href="">
  <ditavalref href="">
  <topicref href="" keys="install"/>
  ...lots more topics, with keys...
</topicref>

The first branch adds a prefix "novice" to the name of every key. The second branch adds a scope of "expert" to every key. As far as I can tell, the net effect of the two approaches is exactly the same - they add a token to the original keys so that you can explicitly reference the "expert" or "novice" branch. Conceptually, both approaches are adding a scope to the keys. In each case, topics outside of this branch must be aware of the token in order to reference the branch-specific key; in each case, topics inside these branches have equal access to the keys outside of the branch.

I can't think of a case where modifying the keys in a branch (without touching the scope) buys anything over adding/renaming a scope on the branch. Instead, it actually forces processors to think about the same operation in two ways. Processors must be able to read the branch to discover keys, while adding an arbitrary prefix/suffix to each key; processors must also be able to create/modify a scope for the original or renamed keys.

If I'm correct in that analysis - then Chris and I would both lean towards dropping the elements dvr-keynamePrefix and dvr-keynameSuffix in favor of the existing scope renaming elements. The biggest benefits are:
* Drop two new elements that we may not need
* We only offer one way to do the same operation
* Simplifies processing: we only need to consider one operation on keys in the branch, and it matches the processing for scope on any other branch

Chris pointed out that with key renaming, you can add a token to the end of a key, while scopes only impact the beginning of the key. I don't think that on its own is important enough to require the extra elements / processing, and I can't think of anything else you get from key renaming that you don't get from scopes. So, I'll propose dropping the two key renaming elements.

Any other thoughts? Eliot - am I missing some important case where adding a prefix to every key in a branch is required, versus adding a scope to those same keys?

Thanks,

Robert D Anderson
IBM Authoring Tools Development
Chief Architect, DITA Open Toolkit (http://dita-ot.sourceforge.net/)



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