OASIS Darwin Information Typing Architecture (DITA) TC

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/ )

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/ )

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 > >