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


Renaming keys is actually demonstrably worse than adding/renaming key
scopes, to the point where I would call key renaming harmful. Renaming
keys has the potential of breaking references to those keys within the
branch; key scoping does not. To take Robert¹s example:

<topicref href="branchRoot.dita">
  <ditavalref 
href="novice.ditaval"><dvr-keynamePrefix>novice</dvr-keynamePrefix></ditava
lref>
  <ditavalref 
href="expert.ditaval"><dvr-keyscopePrefix>expert</dvr-keyscopePrefix></dita
valref>
  <topicref href="installingProduct.dita" keys="install"/>
  ...lots more topics, with keys...
</topicref>


Let¹s say that somewhere else within this branch there existed a topic
that contains:

<xref keyref="install"/>

If you¹re renaming keys, as in the 'novice' branch, then the key that this
link is trying to reference has been renamed to 'noviceinstall', so the
keyref fails to resolve. However, in the second branch, which doesn¹t
rename keys but wraps the branch in a key scope, keyref="install" works
perfectly well from within the branch, and key references outside the
branch can reference keyref="expert.install", basically the same way as if
the key name were prefixed. If both branches used scopes instead of
renaming, then keyrefs outside the cloned branches could select the
appropriate key by providing the appropriate scope name, and key
references within the branches automatically resolve to their local copy
of the same key.

So I feel pretty strongly that we need to get rid of keynamePrefix and
keynameSuffix.

Chris

Chris Nitchie
(734) 330-2978
chris.nitchie@oberontech.com
www.oberontech.com
 <http://www.oberontech.com/>
Follow us:
 <https://www.facebook.com/oberontech>
 <https://twitter.com/oberontech>
 <http://www.linkedin.com/company/oberon-technologies>
 
 






From:  Robert D Anderson <robander@us.ibm.com>
Date:  Monday, March 17, 2014 at 12:21 PM
To:  dita <dita@lists.oasis-open.org>
Subject:  [dita] Branch filtering: key names vs key scopes


Now for the promised bigger question. Assume the following branch in a map:
<topicref href="branchRoot.dita">
  <ditavalref href="novice.ditaval">...</ditavalref>
  <ditavalref href="expert.ditaval">...</ditavalref>
  <topicref href="installingProduct.dita" 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="branchRoot.dita">
  <ditavalref 
href="novice.ditaval"><dvr-keynamePrefix>novice</dvr-keynamePrefix></ditava
lref>
  <ditavalref 
href="expert.ditaval"><dvr-keyscopePrefix>expert</dvr-keyscopePrefix></dita
valref>
  <topicref href="installingProduct.dita" 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]