Re: [dita] Branch filtering: key names vs key scopes

[Eliot Kimber <ekimber@contrext.com>]

I can certainly buy the argument. I think key renaming was there for
completeness over the set of named things that would need to potentially
be disambiguated as a result of branch duplication.

However, I agree that adjusting key scopes would be much more useful and
less problematic than adjusting key names.

I could agree to remove the key renaming as long as there is a statement
in spec that explains the reasoning for not having it since otherwise its
absence would be conspicuous.

Cheers,

E.
—————
Eliot Kimber, Owner
Contrext, LLC
http://contrext.com




On 3/17/14, 11:37 AM, "Chris Nitchie" <chris.nitchie@oberontech.com> wrote:

>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></ditav
>a
>lref>
>  <ditavalref 
>href="expert.ditaval"><dvr-keyscopePrefix>expert</dvr-keyscopePrefix></dit
>a
>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></ditav
>a
>lref>
>  <ditavalref 
>href="expert.ditaval"><dvr-keyscopePrefix>expert</dvr-keyscopePrefix></dit
>a
>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/)
>
>
>---------------------------------------------------------------------
>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
>
>