OASIS Darwin Information Typing Architecture (DITA) TC

Jim,   (CC’ing the TC at large to get this discussion on the record.)   Yes, your two use cases are precisely what I had in mind when I initially drew up the proposal. And your first example, with @keyscope on the mapref, works according to the proposal.   I don’t understand your second example, with @scoped=’true’ on a key defining element. Scoped to what? The current map? The parent topicref? The ambiguity of that strikes me as confusing. However, it can be reformulated using the markup described in the existing proposal:   <topicgroup keyscope=”TractorX”>   <keydef keys=”ProductName”>     <topicmeta><linktext>Tractor X</linktext></topicmeta>   </keydef>   <keydef keys=”logo” href= format=”png”/>   <topicref href= > </topicgroup> <topicgroup keyscope=”TractorY”>   <keydef keys=”ProductName”>     <topicmeta><linktext>Tractor Y</linktext></topicmeta>   </keydef>   <keydef keys=”logo” href= format=”png”/>   <topicref href= > </topicgroup>   There is a third use case which you don’t list (and which also wasn’t accounted for in my initial draft of this proposal, leading to much sturm und drang ). Namely, there are cases where you need to be able to address a key defined in a scope from a different scope. For example, you might have an omnibus help system made up of numerous individual maps. These maps are self-contained for the most part, but some of their key names overlap. So when you create the master top-level map for the help system, you cordon off each individual sub-map into its own scope. However, there are cases where a topic from one sub-map needs to link to a topic in another sub-map. If key scopes were air-tight - as they were in my initial proposal - then there would be no way to do this short of creating a new key at the root level of the map.  It would probably be extremely cumbersome to identify and author the keys that need a root-level copy. So this new version of the proposal essentially automates the creation of those root-level keys.   Chris   From: Jim Tivy [mailto:jimt@bluestream.com] Sent: Tuesday, April 09, 2013 1:43 PM To: 'Chris Nitchie' Subject: Scoped keys   Hi Chris   I thought to contact you directly, since you are likely thinking about this subject alot.   Thanks for the description of the proposal today.   My first objective is to simplify the understanding for the DITA user.  Then we can discuss implementation.   The two use cases:   ·          Omnibus publications that combine multiple standalone maps, each with their own set of key definitions. ·          Cases where a topic is reused at multiple locations in a map structure, but the behavior of links and/or text replacement for each use context must be different. ------------------------ For Omnibus requirement I think a keyspace idea is a good approach.   <mapref href= keyspace="course-1"/>   All keys from this map are now referenced with a qualified name such as: course-1.fookey   ---------------   For supporting different “use concepts” I think that scoping the definition of keys is a good approach. A simple approach is to specify that the keydef is a scoped definition.  Scoped definitions do not get put into the global current space but instead are defined according to their scope in the “map tree”.   <keydef keys="ProductName" scoped=”true”>    <topicmeta>       <linktext>Tractor X</linktext>    </topicmeta> </keydef>   With regards to implementation, I think changing the references – along the lines of what you mentioned - is a good idea.  Without named scopes, the processor could simply come up with unique names for the purposes of scoping.  But don’t want to get into implementation – yet.                    

Hi Chris   Again, my aim here is to reduce the features and concepts to the minimum required to accomplish the use cases with the simplest description and model for DITA users.   Comments below:   From: Chris Nitchie [mailto:chris.nitchie@oberontech.com] Sent: April-09-13 1:31 PM To: 'Jim Tivy' Cc: dita@lists.oasis-open.org Subject: RE: Scoped keys   Jim,   (CC’ing the TC at large to get this discussion on the record.)   Yes, your two use cases are precisely what I had in mind when I initially drew up the proposal. And your first example, with @keyscope on the mapref, works according to the proposal. [Jim Tivy] <mapref href= keyspace="course-1"/>   [Jim Tivy] Note, in my example I changed keyscope to “keyspace” attribute.  The meaning is to import all the definitions into a global keyspace of the given name “course-1” above.  This allows future referencing using the keyspace name – similar I believe to Eliot’s proposal.   I don’t understand your second example, with @scoped=’true’ on a key defining element. Scoped to what? The current map? The parent topicref? The ambiguity of that strikes me as confusing. [Jim Tivy] <keydef keys="ProductName" scoped=”true”>    <topicmeta>       <linktext>Tractor X</linktext>    </topicmeta> </keydef>   [Jim Tivy] The word scoped in this case means that this keydef is not the standard global kind of key definition we are used to in V1.2.  What scoped=”true” means is that this keydef is scoped to all the elements on and below this element according to the concept of hierarchal scope. These keydefs are not introduced to the keyspace at the global level, as other keydefs are, but rather these definitions can only be referred to if you are within this scope and these keydefs are out of scope if you have no parent in the hierarchy where this key is defined. Key definitions defined in this manner are called scoped key definitions – thus the scoped = “true”     However, it can be reformulated using the markup described in the existing proposal:   <topicgroup keyscope=”TractorX”>   <keydef keys=”ProductName”>     <topicmeta><linktext>Tractor X</linktext></topicmeta>   </keydef>   <keydef keys=”logo” href= format=”png”/>   <topicref href= > </topicgroup> <topicgroup keyscope=”TractorY”>   <keydef keys=”ProductName”>     <topicmeta><linktext>Tractor Y</linktext></topicmeta>   </keydef>   <keydef keys=”logo” href= format=”png”/>   <topicref href= > </topicgroup>   There is a third use case which you don’t list (and which also wasn’t accounted for in my initial draft of this proposal, leading to much sturm und drang ). Namely, there are cases where you need to be able to address a key defined in a scope from a different scope. For example, you might have an omnibus help system made up of numerous individual maps. These maps are self-contained for the most part, but some of their key names overlap. So when you create the master top-level map for the help system, you cordon off each individual sub-map into its own scope. However, there are cases where a topic from one sub-map needs to link to a topic in another sub-map. If key scopes were air-tight - as they were in my initial proposal - then there would be no way to do this short of creating a new key at the root level of the map.  It would probably be extremely cumbersome to identify and author the keys that need a root-level copy. So this new version of the proposal essentially automates the creation of those root-level keys.   Chris   From: Jim Tivy [ mailto:jimt@bluestream.com ] Sent: Tuesday, April 09, 2013 1:43 PM To: 'Chris Nitchie' Subject: Scoped keys   Hi Chris   I thought to contact you directly, since you are likely thinking about this subject alot.   Thanks for the description of the proposal today.   My first objective is to simplify the understanding for the DITA user.  Then we can discuss implementation.   The two use cases:   ·      Omnibus publications that combine multiple standalone maps, each with their own set of key definitions. ·      Cases where a topic is reused at multiple locations in a map structure, but the behavior of links and/or text replacement for each use context must be different. ------------------------ For Omnibus requirement I think a keyspace idea is a good approach.   <mapref href= keyspace="course-1"/>   All keys from this map are now referenced with a qualified name such as: course-1.fookey   ---------------   For supporting different “use concepts” I think that scoping the definition of keys is a good approach. A simple approach is to specify that the keydef is a scoped definition.  Scoped definitions do not get put into the global current space but instead are defined according to their scope in the “map tree”.   <keydef keys="ProductName" scoped=”true”>    <topicmeta>       <linktext>Tractor X</linktext>    </topicmeta> </keydef>   With regards to implementation, I think changing the references – along the lines of what you mentioned - is a good idea.  Without named scopes, the processor could simply come up with unique names for the purposes of scoping.  But don’t want to get into implementation – yet.                    

Jim,   I’d like to stick with @keyscope because it’s not a new, self-contained, standalone keyspace; it inherits keys from the parent. So ‘key scope’ still feels appropriate.   You can’t put regular topicrefs within key definitions, because key definitions are not included in the output structure of the publication; the’re just there as processing instructions (@processing-role=”resource-only”). Well, you could , but you’d have to explicitly set processing-role=”normal” on those children, and I imagine that would be just as confusing, if not moreso, to users than wrapping both the scoped key definition and the normal topicref within a topicgroup declaring a scope.   Chris   From: Jim Tivy [mailto:jimt@bluestream.com] Sent: Tuesday, April 09, 2013 5:14 PM To: 'Chris Nitchie' Cc: dita@lists.oasis-open.org Subject: [dita] RE: Scoped keys   Hi Chris   Again, my aim here is to reduce the features and concepts to the minimum required to accomplish the use cases with the simplest description and model for DITA users.   Comments below:   From: Chris Nitchie [ mailto:chris.nitchie@oberontech.com ] Sent: April-09-13 1:31 PM To: 'Jim Tivy' Cc: dita@lists.oasis-open.org Subject: RE: Scoped keys   Jim,   (CC’ing the TC at large to get this discussion on the record.)   Yes, your two use cases are precisely what I had in mind when I initially drew up the proposal. And your first example, with @keyscope on the mapref, works according to the proposal. [Jim Tivy] <mapref href= keyspace="course-1"/>   [Jim Tivy] Note, in my example I changed keyscope to “keyspace” attribute.  The meaning is to import all the definitions into a global keyspace of the given name “course-1” above.  This allows future referencing using the keyspace name – similar I believe to Eliot’s proposal.   I don’t understand your second example, with @scoped=’true’ on a key defining element. Scoped to what? The current map? The parent topicref? The ambiguity of that strikes me as confusing. [Jim Tivy] <keydef keys="ProductName" scoped=”true”>    <topicmeta>       <linktext>Tractor X</linktext>    </topicmeta> </keydef>   [Jim Tivy] The word scoped in this case means that this keydef is not the standard global kind of key definition we are used to in V1.2.  What scoped=”true” means is that this keydef is scoped to all the elements on and below this element according to the concept of hierarchal scope. These keydefs are not introduced to the keyspace at the global level, as other keydefs are, but rather these definitions can only be referred to if you are within this scope and these keydefs are out of scope if you have no parent in the hierarchy where this key is defined. Key definitions defined in this manner are called scoped key definitions – thus the scoped = “true”     However, it can be reformulated using the markup described in the existing proposal:   <topicgroup keyscope=”TractorX”>   <keydef keys=”ProductName”>     <topicmeta><linktext>Tractor X</linktext></topicmeta>   </keydef>   <keydef keys=”logo” href= format=”png”/>   <topicref href= > </topicgroup> <topicgroup keyscope=”TractorY”>   <keydef keys=”ProductName”>     <topicmeta><linktext>Tractor Y</linktext></topicmeta>   </keydef>   <keydef keys=”logo” href= format=”png”/>   <topicref href= > </topicgroup>   There is a third use case which you don’t list (and which also wasn’t accounted for in my initial draft of this proposal, leading to much sturm und drang ). Namely, there are cases where you need to be able to address a key defined in a scope from a different scope. For example, you might have an omnibus help system made up of numerous individual maps. These maps are self-contained for the most part, but some of their key names overlap. So when you create the master top-level map for the help system, you cordon off each individual sub-map into its own scope. However, there are cases where a topic from one sub-map needs to link to a topic in another sub-map. If key scopes were air-tight - as they were in my initial proposal - then there would be no way to do this short of creating a new key at the root level of the map.  It would probably be extremely cumbersome to identify and author the keys that need a root-level copy. So this new version of the proposal essentially automates the creation of those root-level keys.   Chris   From: Jim Tivy [ mailto:jimt@bluestream.com ] Sent: Tuesday, April 09, 2013 1:43 PM To: 'Chris Nitchie' Subject: Scoped keys   Hi Chris   I thought to contact you directly, since you are likely thinking about this subject alot.   Thanks for the description of the proposal today.   My first objective is to simplify the understanding for the DITA user.  Then we can discuss implementation.   The two use cases:   ·       Omnibus publications that combine multiple standalone maps, each with their own set of key definitions. ·       Cases where a topic is reused at multiple locations in a map structure, but the behavior of links and/or text replacement for each use context must be different. ------------------------ For Omnibus requirement I think a keyspace idea is a good approach.   <mapref href= keyspace="course-1"/>   All keys from this map are now referenced with a qualified name such as: course-1.fookey   ---------------   For supporting different “use concepts” I think that scoping the definition of keys is a good approach. A simple approach is to specify that the keydef is a scoped definition.  Scoped definitions do not get put into the global current space but instead are defined according to their scope in the “map tree”.   <keydef keys="ProductName" scoped=”true”>    <topicmeta>       <linktext>Tractor X</linktext>    </topicmeta> </keydef>   With regards to implementation, I think changing the references – along the lines of what you mentioned - is a good idea.  Without named scopes, the processor could simply come up with unique names for the purposes of scoping.  But don’t want to get into implementation – yet.                    

Chris   Comments below:   From: Chris Nitchie [mailto:chris.nitchie@oberontech.com] Sent: April-09-13 2:26 PM To: 'Jim Tivy' Cc: dita@lists.oasis-open.org Subject: RE: [dita] RE: Scoped keys   Jim,   I’d like to stick with @keyscope because it’s not a new, self-contained, standalone keyspace; it inherits keys from the parent. So ‘key scope’ still feels appropriate. [Jim Tivy] I had thought the Omnibus example would want a new keyspace where you can construct links to other publications. So pub1 imports the key definitions from pub2 so that pub1 can somewhere use those key definitions in pub2. <mapref href= keyspace="pub2"/> I think the omnibus example needs to be defined further so I am sure I know your use case. In the past for a customers we published two PDFs at once with links from one PDF to the other.  Is that the omnibus idea?   If you are thinking of the PDF case, I would imagine you want a separate keyspace and then processing to convert pub1 keyrefs in that keyspace (eg:pub2.foo) to refer to the output document pub2.pdf.  Cross HTML would be similar.   You can’t put regular topicrefs within key definitions, because key definitions are not included in the output structure of the publication; the’re just there as processing instructions (@processing-role=”resource-only”). Well, you could , but you’d have to explicitly set processing-role=”normal” on those children, and I imagine that would be just as confusing, if not moreso, to users than wrapping both the scoped key definition and the normal topicref within a topicgroup declaring a scope. [Jim Tivy] Yes, excellent point.  So, for my proposal I think it better to use the attribute parentScoped=”true” instead of my earlier scoped=”true”.   <keydef parentScoped=”true”...  This key is scoped from this element’s parent on down.   Your modified example would be:   <topicgroup>   <keydef parentScoped=”true” keys=”ProductName” >     <topicmeta><linktext>Tractor X</linktext></topicmeta>   </keydef>   <keydef parentScoped=”true” keys=”logo” href= format=”png”/>   <topicref href= > </topicgroup> <topicgroup>   <keydef parentScoped=”true” keys=”ProductName”>     <topicmeta><linktext>Tractor Y</linktext></topicmeta>   </keydef>   <keydef parentScoped=”true” keys=”logo” href= format=”png”/>   <topicref href= > </topicgroup>   cheers Jim   Chris   From: Jim Tivy [ mailto:jimt@bluestream.com ] Sent: Tuesday, April 09, 2013 5:14 PM To: 'Chris Nitchie' Cc: dita@lists.oasis-open.org Subject: [dita] RE: Scoped keys   Hi Chris   Again, my aim here is to reduce the features and concepts to the minimum required to accomplish the use cases with the simplest description and model for DITA users.   Comments below:   From: Chris Nitchie [ mailto:chris.nitchie@oberontech.com ] Sent: April-09-13 1:31 PM To: 'Jim Tivy' Cc: dita@lists.oasis-open.org Subject: RE: Scoped keys   Jim,   (CC’ing the TC at large to get this discussion on the record.)   Yes, your two use cases are precisely what I had in mind when I initially drew up the proposal. And your first example, with @keyscope on the mapref, works according to the proposal. [Jim Tivy] <mapref href= keyspace="course-1"/>   [Jim Tivy] Note, in my example I changed keyscope to “keyspace” attribute.  The meaning is to import all the definitions into a global keyspace of the given name “course-1” above.  This allows future referencing using the keyspace name – similar I believe to Eliot’s proposal.   I don’t understand your second example, with @scoped=’true’ on a key defining element. Scoped to what? The current map? The parent topicref? The ambiguity of that strikes me as confusing. [Jim Tivy] <keydef keys="ProductName" scoped=”true”>    <topicmeta>       <linktext>Tractor X</linktext>    </topicmeta> </keydef>   [Jim Tivy] The word scoped in this case means that this keydef is not the standard global kind of key definition we are used to in V1.2.  What scoped=”true” means is that this keydef is scoped to all the elements on and below this element according to the concept of hierarchal scope. These keydefs are not introduced to the keyspace at the global level, as other keydefs are, but rather these definitions can only be referred to if you are within this scope and these keydefs are out of scope if you have no parent in the hierarchy where this key is defined. Key definitions defined in this manner are called scoped key definitions – thus the scoped = “true”     However, it can be reformulated using the markup described in the existing proposal:   <topicgroup keyscope=”TractorX”>   <keydef keys=”ProductName”>     <topicmeta><linktext>Tractor X</linktext></topicmeta>   </keydef>   <keydef keys=”logo” href= format=”png”/>   <topicref href= > </topicgroup> <topicgroup keyscope=”TractorY”>   <keydef keys=”ProductName”>     <topicmeta><linktext>Tractor Y</linktext></topicmeta>   </keydef>   <keydef keys=”logo” href= format=”png”/>   <topicref href= > </topicgroup>   There is a third use case which you don’t list (and which also wasn’t accounted for in my initial draft of this proposal, leading to much sturm und drang ). Namely, there are cases where you need to be able to address a key defined in a scope from a different scope. For example, you might have an omnibus help system made up of numerous individual maps. These maps are self-contained for the most part, but some of their key names overlap. So when you create the master top-level map for the help system, you cordon off each individual sub-map into its own scope. However, there are cases where a topic from one sub-map needs to link to a topic in another sub-map. If key scopes were air-tight - as they were in my initial proposal - then there would be no way to do this short of creating a new key at the root level of the map.  It would probably be extremely cumbersome to identify and author the keys that need a root-level copy. So this new version of the proposal essentially automates the creation of those root-level keys.   Chris   From: Jim Tivy [ mailto:jimt@bluestream.com ] Sent: Tuesday, April 09, 2013 1:43 PM To: 'Chris Nitchie' Subject: Scoped keys   Hi Chris   I thought to contact you directly, since you are likely thinking about this subject alot.   Thanks for the description of the proposal today.   My first objective is to simplify the understanding for the DITA user.  Then we can discuss implementation.   The two use cases:   ·   Omnibus publications that combine multiple standalone maps, each with their own set of key definitions. ·   Cases where a topic is reused at multiple locations in a map structure, but the behavior of links and/or text replacement for each use context must be different. ------------------------ For Omnibus requirement I think a keyspace idea is a good approach.   <mapref href= keyspace="course-1"/>   All keys from this map are now referenced with a qualified name such as: course-1.fookey   ---------------   For supporting different “use concepts” I think that scoping the definition of keys is a good approach. A simple approach is to specify that the keydef is a scoped definition.  Scoped definitions do not get put into the global current space but instead are defined according to their scope in the “map tree”.   <keydef keys="ProductName" scoped=”true”>    <topicmeta>       <linktext>Tractor X</linktext>    </topicmeta> </keydef>   With regards to implementation, I think changing the references – along the lines of what you mentioned - is a good idea.  Without named scopes, the processor could simply come up with unique names for the purposes of scoping.  But don’t want to get into implementation – yet.                    

Chris   One thing about my proposal below is I refrain from having a named keyscope, rather the scope of a key occurs naturally according to hierarchal scope. I think this simplifies the scoped keys proposal.  I think it is an added order of complexity to be naming nested scopes and peeking into the stack of scopes through complex names. On the other hand, naming keyspaces, is a separate concern from keyscopes and is concerned with implementing the omnibus use case.   cheers Jim   From: Jim Tivy [mailto:jimt@bluestream.com] Sent: April-09-13 3:10 PM To: 'Chris Nitchie' Cc: dita@lists.oasis-open.org Subject: RE: [dita] RE: Scoped keys   Chris   Comments below:   From: Chris Nitchie [ mailto:chris.nitchie@oberontech.com ] Sent: April-09-13 2:26 PM To: 'Jim Tivy' Cc: dita@lists.oasis-open.org Subject: RE: [dita] RE: Scoped keys   Jim,   I’d like to stick with @keyscope because it’s not a new, self-contained, standalone keyspace; it inherits keys from the parent. So ‘key scope’ still feels appropriate. [Jim Tivy] I had thought the Omnibus example would want a new keyspace where you can construct links to other publications. So pub1 imports the key definitions from pub2 so that pub1 can somewhere use those key definitions in pub2. <mapref href= keyspace="pub2"/> I think the omnibus example needs to be defined further so I am sure I know your use case. In the past for a customers we published two PDFs at once with links from one PDF to the other.  Is that the omnibus idea?   If you are thinking of the PDF case, I would imagine you want a separate keyspace and then processing to convert pub1 keyrefs in that keyspace (eg:pub2.foo) to refer to the output document pub2.pdf.  Cross HTML would be similar.   You can’t put regular topicrefs within key definitions, because key definitions are not included in the output structure of the publication; the’re just there as processing instructions (@processing-role=”resource-only”). Well, you could , but you’d have to explicitly set processing-role=”normal” on those children, and I imagine that would be just as confusing, if not moreso, to users than wrapping both the scoped key definition and the normal topicref within a topicgroup declaring a scope. [Jim Tivy] Yes, excellent point.  So, for my proposal I think it better to use the attribute parentScoped=”true” instead of my earlier scoped=”true”.   <keydef parentScoped=”true”...  This key is scoped from this element’s parent on down.   Your modified example would be:   <topicgroup>   <keydef parentScoped=”true” keys=”ProductName” >     <topicmeta><linktext>Tractor X</linktext></topicmeta>   </keydef>   <keydef parentScoped=”true” keys=”logo” href= format=”png”/>   <topicref href= > </topicgroup> <topicgroup>   <keydef parentScoped=”true” keys=”ProductName”>     <topicmeta><linktext>Tractor Y</linktext></topicmeta>   </keydef>   <keydef parentScoped=”true” keys=”logo” href= format=”png”/>   <topicref href= > </topicgroup>   cheers Jim   Chris   From: Jim Tivy [ mailto:jimt@bluestream.com ] Sent: Tuesday, April 09, 2013 5:14 PM To: 'Chris Nitchie' Cc: dita@lists.oasis-open.org Subject: [dita] RE: Scoped keys   Hi Chris   Again, my aim here is to reduce the features and concepts to the minimum required to accomplish the use cases with the simplest description and model for DITA users.   Comments below:   From: Chris Nitchie [ mailto:chris.nitchie@oberontech.com ] Sent: April-09-13 1:31 PM To: 'Jim Tivy' Cc: dita@lists.oasis-open.org Subject: RE: Scoped keys   Jim,   (CC’ing the TC at large to get this discussion on the record.)   Yes, your two use cases are precisely what I had in mind when I initially drew up the proposal. And your first example, with @keyscope on the mapref, works according to the proposal. [Jim Tivy] <mapref href= keyspace="course-1"/>   [Jim Tivy] Note, in my example I changed keyscope to “keyspace” attribute.  The meaning is to import all the definitions into a global keyspace of the given name “course-1” above.  This allows future referencing using the keyspace name – similar I believe to Eliot’s proposal.   I don’t understand your second example, with @scoped=’true’ on a key defining element. Scoped to what? The current map? The parent topicref? The ambiguity of that strikes me as confusing. [Jim Tivy] <keydef keys="ProductName" scoped=”true”>    <topicmeta>       <linktext>Tractor X</linktext>    </topicmeta> </keydef>   [Jim Tivy] The word scoped in this case means that this keydef is not the standard global kind of key definition we are used to in V1.2.  What scoped=”true” means is that this keydef is scoped to all the elements on and below this element according to the concept of hierarchal scope. These keydefs are not introduced to the keyspace at the global level, as other keydefs are, but rather these definitions can only be referred to if you are within this scope and these keydefs are out of scope if you have no parent in the hierarchy where this key is defined. Key definitions defined in this manner are called scoped key definitions – thus the scoped = “true”     However, it can be reformulated using the markup described in the existing proposal:   <topicgroup keyscope=”TractorX”>   <keydef keys=”ProductName”>     <topicmeta><linktext>Tractor X</linktext></topicmeta>   </keydef>   <keydef keys=”logo” href= format=”png”/>   <topicref href= > </topicgroup> <topicgroup keyscope=”TractorY”>   <keydef keys=”ProductName”>     <topicmeta><linktext>Tractor Y</linktext></topicmeta>   </keydef>   <keydef keys=”logo” href= format=”png”/>   <topicref href= > </topicgroup>   There is a third use case which you don’t list (and which also wasn’t accounted for in my initial draft of this proposal, leading to much sturm und drang ). Namely, there are cases where you need to be able to address a key defined in a scope from a different scope. For example, you might have an omnibus help system made up of numerous individual maps. These maps are self-contained for the most part, but some of their key names overlap. So when you create the master top-level map for the help system, you cordon off each individual sub-map into its own scope. However, there are cases where a topic from one sub-map needs to link to a topic in another sub-map. If key scopes were air-tight - as they were in my initial proposal - then there would be no way to do this short of creating a new key at the root level of the map.  It would probably be extremely cumbersome to identify and author the keys that need a root-level copy. So this new version of the proposal essentially automates the creation of those root-level keys.   Chris   From: Jim Tivy [ mailto:jimt@bluestream.com ] Sent: Tuesday, April 09, 2013 1:43 PM To: 'Chris Nitchie' Subject: Scoped keys   Hi Chris   I thought to contact you directly, since you are likely thinking about this subject alot.   Thanks for the description of the proposal today.   My first objective is to simplify the understanding for the DITA user.  Then we can discuss implementation.   The two use cases:   ·         Omnibus publications that combine multiple standalone maps, each with their own set of key definitions. ·         Cases where a topic is reused at multiple locations in a map structure, but the behavior of links and/or text replacement for each use context must be different. ------------------------ For Omnibus requirement I think a keyspace idea is a good approach.   <mapref href= keyspace="course-1"/>   All keys from this map are now referenced with a qualified name such as: course-1.fookey   ---------------   For supporting different “use concepts” I think that scoping the definition of keys is a good approach. A simple approach is to specify that the keydef is a scoped definition.  Scoped definitions do not get put into the global current space but instead are defined according to their scope in the “map tree”.   <keydef keys="ProductName" scoped=”true”>    <topicmeta>       <linktext>Tractor X</linktext>    </topicmeta> </keydef>   With regards to implementation, I think changing the references – along the lines of what you mentioned - is a good idea.  Without named scopes, the processor could simply come up with unique names for the purposes of scoping.  But don’t want to get into implementation – yet.                    

Jim,   I really don’t see the benefit of parentScoped=”true” on individual key definitions over the establishment of a map subtree in which all key definitions are scoped. I think allowing one-off key definitions to be scoped, and not others, is going to lead to more complicated key spaces in actual usage. It will become * extremely * difficult to figure out, as an author, which definition for a given key is viable at a given location. I think it’s much easier - not easy, but easier - to understand the key spaces in a map structure if you put a virtual fence around a section of the map and say, ‘keydefs in here stay in here’.   The omnibus case is not the same thing as the cross-deliverable linking case, which is Eliot’s proposal 13041. Currently that proposal adds new syntax to the value of the keyref attribute for addressing the keys in the other scope. My hope is that he’ll be able to leverage the key scoping mechanism here in 13004 to serve that purpose, thus avoiding some of the complexity that would be involved in a new keyspace addressing scheme.   The omnibus case is where you combine a bunch of publications that could be published as standalone publications (say multiple PDFs), and combine them into a single publication (one PDF). To avoid pollution of the root key space in the omnibus map, you’d put each publication’s map into its own key scope. But the omnibus map could , if it so desired, override the key definitions in those child maps to point to a new location. For example, it might redefine the “aboutThisPublication” key to point to the ‘About’ topic for the omnibus publication instead of whatever ‘About’ sections are part of each individual publication.   In order for the omnibus case and the cross-deliverable linking case to play well together - e.g. to combine two sometimes-distinct, sometimes-combined publications that link to each other - it’s important that they key references used to achieve that linking will work both ways. That’s the main reason I’m leery of introducing a new, specific keyscope addressing mechanism in the keyref attribute. I’d much rather leave the keyref attribute syntax alone, and accomplish the appropriate behavior via key scope configuration in the map.   Chris   From: Jim Tivy [mailto:jimt@bluestream.com] Sent: Wednesday, April 10, 2013 5:16 PM To: 'Chris Nitchie' Cc: dita@lists.oasis-open.org Subject: RE: [dita] RE: Scoped keys   Chris   One thing about my proposal below is I refrain from having a named keyscope, rather the scope of a key occurs naturally according to hierarchal scope. I think this simplifies the scoped keys proposal.  I think it is an added order of complexity to be naming nested scopes and peeking into the stack of scopes through complex names. On the other hand, naming keyspaces, is a separate concern from keyscopes and is concerned with implementing the omnibus use case.   cheers Jim   From: Jim Tivy [ mailto:jimt@bluestream.com ] Sent: April-09-13 3:10 PM To: 'Chris Nitchie' Cc: dita@lists.oasis-open.org Subject: RE: [dita] RE: Scoped keys   Chris   Comments below:   From: Chris Nitchie [ mailto:chris.nitchie@oberontech.com ] Sent: April-09-13 2:26 PM To: 'Jim Tivy' Cc: dita@lists.oasis-open.org Subject: RE: [dita] RE: Scoped keys   Jim,   I’d like to stick with @keyscope because it’s not a new, self-contained, standalone keyspace; it inherits keys from the parent. So ‘key scope’ still feels appropriate. [Jim Tivy] I had thought the Omnibus example would want a new keyspace where you can construct links to other publications. So pub1 imports the key definitions from pub2 so that pub1 can somewhere use those key definitions in pub2. <mapref href= keyspace="pub2"/> I think the omnibus example needs to be defined further so I am sure I know your use case. In the past for a customers we published two PDFs at once with links from one PDF to the other.  Is that the omnibus idea?   If you are thinking of the PDF case, I would imagine you want a separate keyspace and then processing to convert pub1 keyrefs in that keyspace (eg:pub2.foo) to refer to the output document pub2.pdf.  Cross HTML would be similar.   You can’t put regular topicrefs within key definitions, because key definitions are not included in the output structure of the publication; the’re just there as processing instructions (@processing-role=”resource-only”). Well, you could , but you’d have to explicitly set processing-role=”normal” on those children, and I imagine that would be just as confusing, if not moreso, to users than wrapping both the scoped key definition and the normal topicref within a topicgroup declaring a scope. [Jim Tivy] Yes, excellent point.  So, for my proposal I think it better to use the attribute parentScoped=”true” instead of my earlier scoped=”true”.   <keydef parentScoped=”true”...  This key is scoped from this element’s parent on down.   Your modified example would be:   <topicgroup>   <keydef parentScoped=”true” keys=”ProductName” >     <topicmeta><linktext>Tractor X</linktext></topicmeta>   </keydef>   <keydef parentScoped=”true” keys=”logo” href= format=”png”/>   <topicref href= > </topicgroup> <topicgroup>   <keydef parentScoped=”true” keys=”ProductName”>     <topicmeta><linktext>Tractor Y</linktext></topicmeta>   </keydef>   <keydef parentScoped=”true” keys=”logo” href= format=”png”/>   <topicref href= > </topicgroup>   cheers Jim   Chris   From: Jim Tivy [ mailto:jimt@bluestream.com ] Sent: Tuesday, April 09, 2013 5:14 PM To: 'Chris Nitchie' Cc: dita@lists.oasis-open.org Subject: [dita] RE: Scoped keys   Hi Chris   Again, my aim here is to reduce the features and concepts to the minimum required to accomplish the use cases with the simplest description and model for DITA users.   Comments below:   From: Chris Nitchie [ mailto:chris.nitchie@oberontech.com ] Sent: April-09-13 1:31 PM To: 'Jim Tivy' Cc: dita@lists.oasis-open.org Subject: RE: Scoped keys   Jim,   (CC’ing the TC at large to get this discussion on the record.)   Yes, your two use cases are precisely what I had in mind when I initially drew up the proposal. And your first example, with @keyscope on the mapref, works according to the proposal. [Jim Tivy] <mapref href= keyspace="course-1"/>   [Jim Tivy] Note, in my example I changed keyscope to “keyspace” attribute.  The meaning is to import all the definitions into a global keyspace of the given name “course-1” above.  This allows future referencing using the keyspace name – similar I believe to Eliot’s proposal.   I don’t understand your second example, with @scoped=’true’ on a key defining element. Scoped to what? The current map? The parent topicref? The ambiguity of that strikes me as confusing. [Jim Tivy] <keydef keys="ProductName" scoped=”true”>    <topicmeta>       <linktext>Tractor X</linktext>    </topicmeta> </keydef>   [Jim Tivy] The word scoped in this case means that this keydef is not the standard global kind of key definition we are used to in V1.2.  What scoped=”true” means is that this keydef is scoped to all the elements on and below this element according to the concept of hierarchal scope. These keydefs are not introduced to the keyspace at the global level, as other keydefs are, but rather these definitions can only be referred to if you are within this scope and these keydefs are out of scope if you have no parent in the hierarchy where this key is defined. Key definitions defined in this manner are called scoped key definitions – thus the scoped = “true”     However, it can be reformulated using the markup described in the existing proposal:   <topicgroup keyscope=”TractorX”>   <keydef keys=”ProductName”>     <topicmeta><linktext>Tractor X</linktext></topicmeta>   </keydef>   <keydef keys=”logo” href= format=”png”/>   <topicref href= > </topicgroup> <topicgroup keyscope=”TractorY”>   <keydef keys=”ProductName”>     <topicmeta><linktext>Tractor Y</linktext></topicmeta>   </keydef>   <keydef keys=”logo” href= format=”png”/>   <topicref href= > </topicgroup>   There is a third use case which you don’t list (and which also wasn’t accounted for in my initial draft of this proposal, leading to much sturm und drang ). Namely, there are cases where you need to be able to address a key defined in a scope from a different scope. For example, you might have an omnibus help system made up of numerous individual maps. These maps are self-contained for the most part, but some of their key names overlap. So when you create the master top-level map for the help system, you cordon off each individual sub-map into its own scope. However, there are cases where a topic from one sub-map needs to link to a topic in another sub-map. If key scopes were air-tight - as they were in my initial proposal - then there would be no way to do this short of creating a new key at the root level of the map.  It would probably be extremely cumbersome to identify and author the keys that need a root-level copy. So this new version of the proposal essentially automates the creation of those root-level keys.   Chris   From: Jim Tivy [ mailto:jimt@bluestream.com ] Sent: Tuesday, April 09, 2013 1:43 PM To: 'Chris Nitchie' Subject: Scoped keys   Hi Chris   I thought to contact you directly, since you are likely thinking about this subject alot.   Thanks for the description of the proposal today.   My first objective is to simplify the understanding for the DITA user.  Then we can discuss implementation.   The two use cases:   ·          Omnibus publications that combine multiple standalone maps, each with their own set of key definitions. ·          Cases where a topic is reused at multiple locations in a map structure, but the behavior of links and/or text replacement for each use context must be different. ------------------------ For Omnibus requirement I think a keyspace idea is a good approach.   <mapref href= keyspace="course-1"/>   All keys from this map are now referenced with a qualified name such as: course-1.fookey   ---------------   For supporting different “use concepts” I think that scoping the definition of keys is a good approach. A simple approach is to specify that the keydef is a scoped definition.  Scoped definitions do not get put into the global current space but instead are defined according to their scope in the “map tree”.   <keydef keys="ProductName" scoped=”true”>    <topicmeta>       <linktext>Tractor X</linktext>    </topicmeta> </keydef>   With regards to implementation, I think changing the references – along the lines of what you mentioned - is a good idea.  Without named scopes, the processor could simply come up with unique names for the purposes of scoping.  But don’t want to get into implementation – yet.                    

I agree with Chris' analysis and hope. I haven't had the time yet to fully work through the implications of Chris' design, but my initial analysis is that he is correct that cross-scope and cross-publication key references can use the addressing scheme Chris has proposed. A main thing is that any solution for scoped keys really needs to work for cross-publication links and visa-versa, since they are fundamentally two sides of the same coin. It absolutely needs to be the case that same key *reference* can be made to resolve to the appropriate resource in both the single-publication case and the multi-publication case. I think Chris makes a strong argument for his approach. Cheers, E. On 4/12/13 10:23 AM, "Chris Nitchie" <chris.nitchie@oberontech.com> wrote: > Jim, > > I really don¹t see the benefit of parentScoped=²true² on individual key > definitions over the establishment of a map subtree in which all key > definitions are scoped. I think allowing one-off key definitions to be scoped, > and not others, is going to lead to more complicated key spaces in actual > usage. It will become *extremely* difficult to figure out, as an author, which > definition for a given key is viable at a given location. I think it¹s much > easier - not easy, but easier - to understand the key spaces in a map > structure if you put a virtual fence around a section of the map and say, > Okeydefs in here stay in here¹. > > The omnibus case is not the same thing as the cross-deliverable linking case, > which is Eliot¹s proposal 13041. Currently that proposal adds new syntax to > the value of the keyref attribute for addressing the keys in the other scope. > My hope is that he¹ll be able to leverage the key scoping mechanism here in > 13004 to serve that purpose, thus avoiding some of the complexity that would > be involved in a new keyspace addressing scheme. > > The omnibus case is where you combine a bunch of publications that could be > published as standalone publications (say multiple PDFs), and combine them > into a single publication (one PDF). To avoid pollution of the root key space > in the omnibus map, you¹d put each publication¹s map into its own key scope. > But the omnibus map could, if it so desired, override the key definitions in > those child maps to point to a new location. For example, it might redefine > the ³aboutThisPublication² key to point to the OAbout¹ topic for the omnibus > publication instead of whatever OAbout¹ sections are part of each individual > publication. > > In order for the omnibus case and the cross-deliverable linking case to play > well together - e.g. to combine two sometimes-distinct, sometimes-combined > publications that link to each other - it¹s important that they key references > used to achieve that linking will work both ways. That¹s the main reason I¹m > leery of introducing a new, specific keyscope addressing mechanism in the > keyref attribute. I¹d much rather leave the keyref attribute syntax alone, and > accomplish the appropriate behavior via key scope configuration in the map. > > Chris > > > From: Jim Tivy [ mailto:jimt@bluestream.com ] > Sent: Wednesday, April 10, 2013 5:16 PM > To: 'Chris Nitchie' > Cc: dita@lists.oasis-open.org > Subject: RE: [dita] RE: Scoped keys > > Chris > > One thing about my proposal below is I refrain from having a named keyscope, > rather the scope of a key occurs naturally according to hierarchal scope. > I think this simplifies the scoped keys proposal. I think it is an added > order of complexity to be naming nested scopes and peeking into the stack of > scopes through complex names. > On the other hand, naming keyspaces, is a separate concern from keyscopes and > is concerned with implementing the omnibus use case. > > cheers > Jim > > > From: Jim Tivy [ mailto:jimt@bluestream.com ] > Sent: April-09-13 3:10 PM > To: 'Chris Nitchie' > Cc: dita@lists.oasis-open.org > Subject: RE: [dita] RE: Scoped keys > > Chris > > Comments below: > > > From: Chris Nitchie [ mailto:chris.nitchie@oberontech.com ] > Sent: April-09-13 2:26 PM > To: 'Jim Tivy' > Cc: dita@lists.oasis-open.org > Subject: RE: [dita] RE: Scoped keys > > Jim, > > I¹d like to stick with @keyscope because it¹s not a new, self-contained, > standalone keyspace; it inherits keys from the parent. So Okey scope¹ still > feels appropriate. > [Jim Tivy] I had thought the Omnibus example would want a new keyspace where > you can construct links to other publications. > So pub1 imports the key definitions from pub2 so that pub1 can somewhere use > those key definitions in pub2. > <mapref href="pub2defs.ditamap" keyspace="pub2"/> > I think the omnibus example needs to be defined further so I am sure I know > your use case. > In the past for a customers we published two PDFs at once with links from one > PDF to the other. Is that the omnibus idea? > > If you are thinking of the PDF case, I would imagine you want a separate > keyspace and then processing to convert pub1 keyrefs in that keyspace > (eg:pub2.foo) to refer to the output document pub2.pdf. Cross HTML would be > similar. > > You can¹t put regular topicrefs within key definitions, because key > definitions are not included in the output structure of the publication; > the¹re just there as processing instructions > (@processing-role=²resource-only²). Well, you could, but you¹d have to > explicitly set processing-role=²normal² on those children, and I imagine that > would be just as confusing, if not moreso, to users than wrapping both the > scoped key definition and the normal topicref within a topicgroup declaring a > scope. > [Jim Tivy] Yes, excellent point. So, for my proposal I think it better to use > the attribute parentScoped=²true² instead of my earlier scoped=²true². > > <keydef parentScoped=²true²... This key is scoped from this element¹s parent > on down. > > Your modified example would be: > > <topicgroup> > <keydef parentScoped=²true² keys=²ProductName²> > <topicmeta><linktext>Tractor X</linktext></topicmeta> > </keydef> > <keydef parentScoped=²true² keys=²logo² href=²TractorX.png² format=²png²/> > <topicref href=²genericTopic.dita²/> > </topicgroup> > <topicgroup> > <keydef parentScoped=²true² keys=²ProductName²> > <topicmeta><linktext>Tractor Y</linktext></topicmeta> > </keydef> > <keydef parentScoped=²true² keys=²logo² href=²TractorY.png² format=²png²/> > <topicref href=²genericTopic.dita²/> > </topicgroup> > > cheers > Jim > > Chris > > > From: Jim Tivy [ mailto:jimt@bluestream.com ] > Sent: Tuesday, April 09, 2013 5:14 PM > To: 'Chris Nitchie' > Cc: dita@lists.oasis-open.org > Subject: [dita] RE: Scoped keys > > Hi Chris > > Again, my aim here is to reduce the features and concepts to the minimum > required to accomplish the use cases with the simplest description and model > for DITA users. > > Comments below: > > > From: Chris Nitchie [ mailto:chris.nitchie@oberontech.com ] > Sent: April-09-13 1:31 PM > To: 'Jim Tivy' > Cc: dita@lists.oasis-open.org > Subject: RE: Scoped keys > > Jim, > > (CC¹ing the TC at large to get this discussion on the record.) > > Yes, your two use cases are precisely what I had in mind when I initially drew > up the proposal. And your first example, with @keyscope on the mapref, works > according to the proposal. > [Jim Tivy] <mapref href="course-1.ditamap" keyspace="course-1"/> > > [Jim Tivy] Note, in my example I changed keyscope to ³keyspace² attribute. > The meaning is to import all the definitions into a global keyspace of the > given name ³course-1² above. This allows future referencing using the > keyspace name ­ similar I believe to Eliot¹s proposal. > > I don¹t understand your second example, with @scoped=¹true¹ on a key defining > element. Scoped to what? The current map? The parent topicref? The ambiguity > of that strikes me as confusing. > [Jim Tivy] > <keydef keys="ProductName" scoped=²true²> > <topicmeta> > <linktext>Tractor X</linktext> > </topicmeta> > </keydef> > > [Jim Tivy] > The word scoped in this case means that this keydef is not the standard global > kind of key definition we are used to in V1.2. What scoped=²true² means is > that this keydef is scoped to all the elements on and below this element > according to the concept of hierarchal scope. These keydefs are not introduced > to the keyspace at the global level, as other keydefs are, but rather these > definitions can only be referred to if you are within this scope and these > keydefs are out of scope if you have no parent in the hierarchy where this key > is defined. > Key definitions defined in this manner are called scoped key definitions ­ > thus the scoped = ³true² > > > However, it can be reformulated using the markup described in the existing > proposal: > > <topicgroup keyscope=²TractorX²> > <keydef keys=²ProductName²> > <topicmeta><linktext>Tractor X</linktext></topicmeta> > </keydef> > <keydef keys=²logo² href=²TractorX.png² format=²png²/> > <topicref href=²genericTopic.dita²/> > </topicgroup> > <topicgroup keyscope=²TractorY²> > <keydef keys=²ProductName²> > <topicmeta><linktext>Tractor Y</linktext></topicmeta> > </keydef> > <keydef keys=²logo² href=²TractorY.png² format=²png²/> > <topicref href=²genericTopic.dita²/> > </topicgroup> > > There is a third use case which you don¹t list (and which also wasn¹t > accounted for in my initial draft of this proposal, leading to much sturm und > drang). Namely, there are cases where you need to be able to address a key > defined in a scope from a different scope. For example, you might have an > omnibus help system made up of numerous individual maps. These maps are > self-contained for the most part, but some of their key names overlap. So when > you create the master top-level map for the help system, you cordon off each > individual sub-map into its own scope. However, there are cases where a topic > from one sub-map needs to link to a topic in another sub-map. If key scopes > were air-tight - as they were in my initial proposal - then there would be no > way to do this short of creating a new key at the root level of the map. It > would probably be extremely cumbersome to identify and author the keys that > need a root-level copy. So this new version of the proposal essentially > automates the creation of those root-level keys. > > Chris > > > From: Jim Tivy [ mailto:jimt@bluestream.com ] > Sent: Tuesday, April 09, 2013 1:43 PM > To: 'Chris Nitchie' > Subject: Scoped keys > > Hi Chris > > I thought to contact you directly, since you are likely thinking about this > subject alot. > > Thanks for the description of the proposal today. > > My first objective is to simplify the understanding for the DITA user. Then > we can discuss implementation. > > The two use cases: > > · Omnibus publications that combine multiple standalone maps, each > with their own set of key definitions. > > · Cases where a topic is reused at multiple locations in a map > structure, but the behavior of links and/or text replacement for each use > context must be different. > > ------------------------ > > For Omnibus requirement I think a keyspace idea is a good approach. > > <mapref href="course-1.ditamap" keyspace="course-1"/> > > All keys from this map are now referenced with a qualified name such as: > course-1.fookey > > --------------- > > For supporting different ³use concepts² I think that scoping the definition of > keys is a good approach. A simple approach is to specify that the keydef is a > scoped definition. Scoped definitions do not get put into the global current > space but instead are defined according to their scope in the ³map tree². > > <keydef keys="ProductName" scoped=²true²> > <topicmeta> > <linktext>Tractor X</linktext> > </topicmeta> > </keydef> > > With regards to implementation, I think changing the references ­ along the > lines of what you mentioned - is a good idea. Without named scopes, the > processor could simply come up with unique names for the purposes of scoping. > But don¹t want to get into implementation ­ yet. > > > > > > > > > > -- Eliot Kimber Senior Solutions Architect, RSI Content Solutions "Bringing Strategy, Content, and Technology Together" Main: 512.554.9368 www.rsicms.com www.rsuitecms.com Book: DITA For Practitioners, from XML Press, http://xmlpress.net/publications/dita/practitioners-1/

There's a third aspect to that coin. The target of a given key reference might have any of three relationships to the referencing element, and it might vary from context to context. The target might be 1. In a different root map. 2. In a different scope in the same root map. 3. In the same key scope. By using standard keyref syntax and not imposing a new keyref syntax component that forces the assumption that the target is 'somewhere else,' we give map authors the flexibility they need to configure all three cases. Chris
Original Message----- From: Eliot Kimber [ mailto:ekimber@rsicms.com ] Sent: Friday, April 12, 2013 11:30 AM To: Chris Nitchie; Jim Tivy Cc: dita Subject: Re: [dita] RE: Scoped keys I agree with Chris' analysis and hope. I haven't had the time yet to fully work through the implications of Chris' design, but my initial analysis is that he is correct that cross-scope and cross-publication key references can use the addressing scheme Chris has proposed. A main thing is that any solution for scoped keys really needs to work for cross-publication links and visa-versa, since they are fundamentally two sides of the same coin. It absolutely needs to be the case that same key *reference* can be made to resolve to the appropriate resource in both the single-publication case and the multi-publication case. I think Chris makes a strong argument for his approach. Cheers, E. On 4/12/13 10:23 AM, "Chris Nitchie" <chris.nitchie@oberontech.com> wrote: > Jim, > > I really don¹t see the benefit of parentScoped=²true² on individual > key definitions over the establishment of a map subtree in which all > key definitions are scoped. I think allowing one-off key definitions > to be scoped, and not others, is going to lead to more complicated key > spaces in actual usage. It will become *extremely* difficult to figure > out, as an author, which definition for a given key is viable at a > given location. I think it¹s much easier - not easy, but easier - to > understand the key spaces in a map structure if you put a virtual > fence around a section of the map and say, Okeydefs in here stay in here¹. > > The omnibus case is not the same thing as the cross-deliverable > linking case, which is Eliot¹s proposal 13041. Currently that proposal > adds new syntax to the value of the keyref attribute for addressing the keys in the other scope. > My hope is that he¹ll be able to leverage the key scoping mechanism > here in > 13004 to serve that purpose, thus avoiding some of the complexity that > would be involved in a new keyspace addressing scheme. > > The omnibus case is where you combine a bunch of publications that > could be published as standalone publications (say multiple PDFs), and > combine them into a single publication (one PDF). To avoid pollution > of the root key space in the omnibus map, you¹d put each publication¹s map into its own key scope. > But the omnibus map could, if it so desired, override the key > definitions in those child maps to point to a new location. For > example, it might redefine the ³aboutThisPublication² key to point to > the OAbout¹ topic for the omnibus publication instead of whatever > OAbout¹ sections are part of each individual publication. > > In order for the omnibus case and the cross-deliverable linking case > to play well together - e.g. to combine two sometimes-distinct, > sometimes-combined publications that link to each other - it¹s > important that they key references used to achieve that linking will > work both ways. That¹s the main reason I¹m leery of introducing a new, > specific keyscope addressing mechanism in the keyref attribute. I¹d > much rather leave the keyref attribute syntax alone, and accomplish the appropriate behavior via key scope configuration in the map. > > Chris > > > From: Jim Tivy [ mailto:jimt@bluestream.com ] > Sent: Wednesday, April 10, 2013 5:16 PM > To: 'Chris Nitchie' > Cc: dita@lists.oasis-open.org > Subject: RE: [dita] RE: Scoped keys > > Chris > > One thing about my proposal below is I refrain from having a named > keyscope, rather the scope of a key occurs naturally according to hierarchal scope. > I think this simplifies the scoped keys proposal. I think it is an > added order of complexity to be naming nested scopes and peeking into > the stack of scopes through complex names. > On the other hand, naming keyspaces, is a separate concern from > keyscopes and is concerned with implementing the omnibus use case. > > cheers > Jim > > > From: Jim Tivy [ mailto:jimt@bluestream.com ] > Sent: April-09-13 3:10 PM > To: 'Chris Nitchie' > Cc: dita@lists.oasis-open.org > Subject: RE: [dita] RE: Scoped keys > > Chris > > Comments below: > > > From: Chris Nitchie [ mailto:chris.nitchie@oberontech.com ] > Sent: April-09-13 2:26 PM > To: 'Jim Tivy' > Cc: dita@lists.oasis-open.org > Subject: RE: [dita] RE: Scoped keys > > Jim, > > I¹d like to stick with @keyscope because it¹s not a new, > self-contained, standalone keyspace; it inherits keys from the parent. > So Okey scope¹ still feels appropriate. > [Jim Tivy] I had thought the Omnibus example would want a new keyspace > where you can construct links to other publications. > So pub1 imports the key definitions from pub2 so that pub1 can > somewhere use those key definitions in pub2. > <mapref href="pub2defs.ditamap" keyspace="pub2"/> I think the omnibus > example needs to be defined further so I am sure I know your use case. > In the past for a customers we published two PDFs at once with links > from one PDF to the other. Is that the omnibus idea? > > If you are thinking of the PDF case, I would imagine you want a > separate keyspace and then processing to convert pub1 keyrefs in that > keyspace > (eg:pub2.foo) to refer to the output document pub2.pdf. Cross HTML > would be similar. > > You can¹t put regular topicrefs within key definitions, because key > definitions are not included in the output structure of the > publication; the¹re just there as processing instructions > (@processing-role=²resource-only²). Well, you could, but you¹d have to > explicitly set processing-role=²normal² on those children, and I > imagine that would be just as confusing, if not moreso, to users than > wrapping both the scoped key definition and the normal topicref within > a topicgroup declaring a scope. > [Jim Tivy] Yes, excellent point. So, for my proposal I think it > better to use the attribute parentScoped=²true² instead of my earlier scoped=²true². > > <keydef parentScoped=²true²... This key is scoped from this element¹s > parent on down. > > Your modified example would be: > > <topicgroup> > <keydef parentScoped=²true² keys=²ProductName²> > <topicmeta><linktext>Tractor X</linktext></topicmeta> > </keydef> > <keydef parentScoped=²true² keys=²logo² href=²TractorX.png² format=²png²/> > <topicref href=²genericTopic.dita²/> </topicgroup> <topicgroup> > <keydef parentScoped=²true² keys=²ProductName²> > <topicmeta><linktext>Tractor Y</linktext></topicmeta> > </keydef> > <keydef parentScoped=²true² keys=²logo² href=²TractorY.png² format=²png²/> > <topicref href=²genericTopic.dita²/> </topicgroup> > > cheers > Jim > > Chris > > > From: Jim Tivy [ mailto:jimt@bluestream.com ] > Sent: Tuesday, April 09, 2013 5:14 PM > To: 'Chris Nitchie' > Cc: dita@lists.oasis-open.org > Subject: [dita] RE: Scoped keys > > Hi Chris > > Again, my aim here is to reduce the features and concepts to the > minimum required to accomplish the use cases with the simplest > description and model for DITA users. > > Comments below: > > > From: Chris Nitchie [ mailto:chris.nitchie@oberontech.com ] > Sent: April-09-13 1:31 PM > To: 'Jim Tivy' > Cc: dita@lists.oasis-open.org > Subject: RE: Scoped keys > > Jim, > > (CC¹ing the TC at large to get this discussion on the record.) > > Yes, your two use cases are precisely what I had in mind when I > initially drew up the proposal. And your first example, with @keyscope > on the mapref, works according to the proposal. > [Jim Tivy] <mapref href="course-1.ditamap" keyspace="course-1"/> > > [Jim Tivy] Note, in my example I changed keyscope to ³keyspace² attribute. > The meaning is to import all the definitions into a global keyspace of > the given name ³course-1² above. This allows future referencing using > the keyspace name ­ similar I believe to Eliot¹s proposal. > > I don¹t understand your second example, with @scoped=¹true¹ on a key > defining element. Scoped to what? The current map? The parent > topicref? The ambiguity of that strikes me as confusing. > [Jim Tivy] > <keydef keys="ProductName" scoped=²true²> > <topicmeta> > <linktext>Tractor X</linktext> > </topicmeta> > </keydef> > > [Jim Tivy] > The word scoped in this case means that this keydef is not the > standard global kind of key definition we are used to in V1.2. What > scoped=²true² means is that this keydef is scoped to all the elements > on and below this element according to the concept of hierarchal > scope. These keydefs are not introduced to the keyspace at the global > level, as other keydefs are, but rather these definitions can only be > referred to if you are within this scope and these keydefs are out of > scope if you have no parent in the hierarchy where this key is defined. > Key definitions defined in this manner are called scoped key > definitions ­ thus the scoped = ³true² > > > However, it can be reformulated using the markup described in the > existing > proposal: > > <topicgroup keyscope=²TractorX²> > <keydef keys=²ProductName²> > <topicmeta><linktext>Tractor X</linktext></topicmeta> > </keydef> > <keydef keys=²logo² href=²TractorX.png² format=²png²/> > <topicref href=²genericTopic.dita²/> </topicgroup> <topicgroup > keyscope=²TractorY²> > <keydef keys=²ProductName²> > <topicmeta><linktext>Tractor Y</linktext></topicmeta> > </keydef> > <keydef keys=²logo² href=²TractorY.png² format=²png²/> > <topicref href=²genericTopic.dita²/> </topicgroup> > > There is a third use case which you don¹t list (and which also wasn¹t > accounted for in my initial draft of this proposal, leading to much > sturm und drang). Namely, there are cases where you need to be able to > address a key defined in a scope from a different scope. For example, > you might have an omnibus help system made up of numerous individual > maps. These maps are self-contained for the most part, but some of > their key names overlap. So when you create the master top-level map > for the help system, you cordon off each individual sub-map into its > own scope. However, there are cases where a topic from one sub-map > needs to link to a topic in another sub-map. If key scopes were > air-tight - as they were in my initial proposal - then there would be > no way to do this short of creating a new key at the root level of the > map. It would probably be extremely cumbersome to identify and author > the keys that need a root-level copy. So this new version of the proposal essentially automates the creation of those root-level keys. > > Chris > > > From: Jim Tivy [ mailto:jimt@bluestream.com ] > Sent: Tuesday, April 09, 2013 1:43 PM > To: 'Chris Nitchie' > Subject: Scoped keys > > Hi Chris > > I thought to contact you directly, since you are likely thinking about > this subject alot. > > Thanks for the description of the proposal today. > > My first objective is to simplify the understanding for the DITA user. > Then we can discuss implementation. > > The two use cases: > > · Omnibus publications that combine multiple standalone maps, each > with their own set of key definitions. > > · Cases where a topic is reused at multiple locations in a map > structure, but the behavior of links and/or text replacement for each > use context must be different. > > ------------------------ > > For Omnibus requirement I think a keyspace idea is a good approach. > > <mapref href="course-1.ditamap" keyspace="course-1"/> > > All keys from this map are now referenced with a qualified name such as: > course-1.fookey > > --------------- > > For supporting different ³use concepts² I think that scoping the > definition of keys is a good approach. A simple approach is to specify > that the keydef is a scoped definition. Scoped definitions do not get > put into the global current space but instead are defined according to their scope in the ³map tree². > > <keydef keys="ProductName" scoped=²true²> > <topicmeta> > <linktext>Tractor X</linktext> > </topicmeta> > </keydef> > > With regards to implementation, I think changing the references ­ > along the lines of what you mentioned - is a good idea. Without named > scopes, the processor could simply come up with unique names for the purposes of scoping. > But don¹t want to get into implementation ­ yet. > > > > > > > > > > -- Eliot Kimber Senior Solutions Architect, RSI Content Solutions "Bringing Strategy, Content, and Technology Together" Main: 512.554.9368 www.rsicms.com www.rsuitecms.com Book: DITA For Practitioners, from XML Press, http://xmlpress.net/publications/dita/practitioners-1/ --------------------------------------------------------------------- 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

Hi Chris.   Thank you for explaining your proposal further. Tree scope exists by the very nature of the tree.  Scoped keys exist by designating them as scoped at some place in that tree.  I do not see why we need to designate a “keyscope” and name it since a scope exists by definition of tree scope.  And I do not see why naming keyscopes makes keyref resolution simpler or more clear. Using names to qualifying the keyref with a scope name defeats the redefinition feature we seek. Keyspaces are the thing that you will want to name if you want multiples – that is a related discussion.    My purpose here is to discuss this proposal and brainstorm in a friendly way in the spirit of making DITA a good as we can make it. Once we decide we will live with this for decades – as I am sure we are all aware.   My reasoning is as follows:   1. There exists something called a “filtered tree” which is a tree of maps and in turn submaps and in turn their topics – all after filtering.  I could elaborate but I think we all get the idea as this - it is not new. 2. There are two kinds of keydefs – “global” and “scoped” (tree scoped). Global keydefs are what we have in 1.2 and scoped keydefs is what we are discussing here. 3. Tree scoped keydefs are “in scope” for all topics and topic refs under the parent in the  filtered tree where they are defined. 4. Since  scoped keydefs are new we need a syntax to designate them.   Either of the two syntaxes below would suffice to designate a keydef as being of the “scoped” variety – but the need to name the scopes seems like added complexity.   <topicgroup scopeChildKeyDefs=”true ”>   <keydef keys=”ProductName” >     <topicmeta><linktext>Tractor X</linktext></topicmeta>   </keydef>   or   <topicgroup>   <keydef parentScoped=”true” keys=”ProductName” >     <topicmeta><linktext>Tractor X</linktext></topicmeta>   </keydef>     From: dita@lists.oasis-open.org [mailto:dita@lists.oasis-open.org] On Behalf Of Chris Nitchie Sent: April-12-13 8:23 AM To: 'Jim Tivy' Cc: dita@lists.oasis-open.org Subject: RE: [dita] RE: Scoped keys   Jim,   I really don’t see the benefit of parentScoped=”true” on individual key definitions over the establishment of a map subtree in which all key definitions are scoped. I think allowing one-off key definitions to be scoped, and not others, is going to lead to more complicated key spaces in actual usage. It will become * extremely * difficult to figure out, as an author, which definition for a given key is viable at a given location. I think it’s much easier - not easy, but easier - to understand the key spaces in a map structure if you put a virtual fence around a section of the map and say, ‘keydefs in here stay in here’.   The omnibus case is not the same thing as the cross-deliverable linking case, which is Eliot’s proposal 13041. Currently that proposal adds new syntax to the value of the keyref attribute for addressing the keys in the other scope. My hope is that he’ll be able to leverage the key scoping mechanism here in 13004 to serve that purpose, thus avoiding some of the complexity that would be involved in a new keyspace addressing scheme.   The omnibus case is where you combine a bunch of publications that could be published as standalone publications (say multiple PDFs), and combine them into a single publication (one PDF). To avoid pollution of the root key space in the omnibus map, you’d put each publication’s map into its own key scope. But the omnibus map could , if it so desired, override the key definitions in those child maps to point to a new location. For example, it might redefine the “aboutThisPublication” key to point to the ‘About’ topic for the omnibus publication instead of whatever ‘About’ sections are part of each individual publication.   In order for the omnibus case and the cross-deliverable linking case to play well together - e.g. to combine two sometimes-distinct, sometimes-combined publications that link to each other - it’s important that they key references used to achieve that linking will work both ways. That’s the main reason I’m leery of introducing a new, specific keyscope addressing mechanism in the keyref attribute. I’d much rather leave the keyref attribute syntax alone, and accomplish the appropriate behavior via key scope configuration in the map.   Chris   From: Jim Tivy [ mailto:jimt@bluestream.com ] Sent: Wednesday, April 10, 2013 5:16 PM To: 'Chris Nitchie' Cc: dita@lists.oasis-open.org Subject: RE: [dita] RE: Scoped keys   Chris   One thing about my proposal below is I refrain from having a named keyscope, rather the scope of a key occurs naturally according to hierarchal scope. I think this simplifies the scoped keys proposal.  I think it is an added order of complexity to be naming nested scopes and peeking into the stack of scopes through complex names. On the other hand, naming keyspaces, is a separate concern from keyscopes and is concerned with implementing the omnibus use case.   cheers Jim   From: Jim Tivy [ mailto:jimt@bluestream.com ] Sent: April-09-13 3:10 PM To: 'Chris Nitchie' Cc: dita@lists.oasis-open.org Subject: RE: [dita] RE: Scoped keys   Chris   Comments below:   From: Chris Nitchie [ mailto:chris.nitchie@oberontech.com ] Sent: April-09-13 2:26 PM To: 'Jim Tivy' Cc: dita@lists.oasis-open.org Subject: RE: [dita] RE: Scoped keys   Jim,   I’d like to stick with @keyscope because it’s not a new, self-contained, standalone keyspace; it inherits keys from the parent. So ‘key scope’ still feels appropriate. [Jim Tivy] I had thought the Omnibus example would want a new keyspace where you can construct links to other publications. So pub1 imports the key definitions from pub2 so that pub1 can somewhere use those key definitions in pub2. <mapref href= keyspace="pub2"/> I think the omnibus example needs to be defined further so I am sure I know your use case. In the past for a customers we published two PDFs at once with links from one PDF to the other.  Is that the omnibus idea?   If you are thinking of the PDF case, I would imagine you want a separate keyspace and then processing to convert pub1 keyrefs in that keyspace (eg:pub2.foo) to refer to the output document pub2.pdf.  Cross HTML would be similar.   You can’t put regular topicrefs within key definitions, because key definitions are not included in the output structure of the publication; the’re just there as processing instructions (@processing-role=”resource-only”). Well, you could , but you’d have to explicitly set processing-role=”normal” on those children, and I imagine that would be just as confusing, if not moreso, to users than wrapping both the scoped key definition and the normal topicref within a topicgroup declaring a scope. [Jim Tivy] Yes, excellent point.  So, for my proposal I think it better to use the attribute parentScoped=”true” instead of my earlier scoped=”true”.   <keydef parentScoped=”true”...  This key is scoped from this element’s parent on down.   Your modified example would be:   <topicgroup>   <keydef parentScoped=”true” keys=”ProductName” >     <topicmeta><linktext>Tractor X</linktext></topicmeta>   </keydef>   <keydef parentScoped=”true” keys=”logo” href= format=”png”/>   <topicref href= > </topicgroup> <topicgroup>   <keydef parentScoped=”true” keys=”ProductName”>     <topicmeta><linktext>Tractor Y</linktext></topicmeta>   </keydef>   <keydef parentScoped=”true” keys=”logo” href= format=”png”/>   <topicref href= > </topicgroup>   cheers Jim   Chris   From: Jim Tivy [ mailto:jimt@bluestream.com ] Sent: Tuesday, April 09, 2013 5:14 PM To: 'Chris Nitchie' Cc: dita@lists.oasis-open.org Subject: [dita] RE: Scoped keys   Hi Chris   Again, my aim here is to reduce the features and concepts to the minimum required to accomplish the use cases with the simplest description and model for DITA users.   Comments below:   From: Chris Nitchie [ mailto:chris.nitchie@oberontech.com ] Sent: April-09-13 1:31 PM To: 'Jim Tivy' Cc: dita@lists.oasis-open.org Subject: RE: Scoped keys   Jim,   (CC’ing the TC at large to get this discussion on the record.)   Yes, your two use cases are precisely what I had in mind when I initially drew up the proposal. And your first example, with @keyscope on the mapref, works according to the proposal. [Jim Tivy] <mapref href= keyspace="course-1"/>   [Jim Tivy] Note, in my example I changed keyscope to “keyspace” attribute.  The meaning is to import all the definitions into a global keyspace of the given name “course-1” above.  This allows future referencing using the keyspace name – similar I believe to Eliot’s proposal.   I don’t understand your second example, with @scoped=’true’ on a key defining element. Scoped to what? The current map? The parent topicref? The ambiguity of that strikes me as confusing. [Jim Tivy] <keydef keys="ProductName" scoped=”true”>    <topicmeta>       <linktext>Tractor X</linktext>    </topicmeta> </keydef>   [Jim Tivy] The word scoped in this case means that this keydef is not the standard global kind of key definition we are used to in V1.2.  What scoped=”true” means is that this keydef is scoped to all the elements on and below this element according to the concept of hierarchal scope. These keydefs are not introduced to the keyspace at the global level, as other keydefs are, but rather these definitions can only be referred to if you are within this scope and these keydefs are out of scope if you have no parent in the hierarchy where this key is defined. Key definitions defined in this manner are called scoped key definitions – thus the scoped = “true”     However, it can be reformulated using the markup described in the existing proposal:   <topicgroup keyscope=”TractorX”>   <keydef keys=”ProductName”>     <topicmeta><linktext>Tractor X</linktext></topicmeta>   </keydef>   <keydef keys=”logo” href= format=”png”/>   <topicref href= > </topicgroup> <topicgroup keyscope=”TractorY”>   <keydef keys=”ProductName”>     <topicmeta><linktext>Tractor Y</linktext></topicmeta>   </keydef>   <keydef keys=”logo” href= format=”png”/>   <topicref href= > </topicgroup>   There is a third use case which you don’t list (and which also wasn’t accounted for in my initial draft of this proposal, leading to much sturm und drang ). Namely, there are cases where you need to be able to address a key defined in a scope from a different scope. For example, you might have an omnibus help system made up of numerous individual maps. These maps are self-contained for the most part, but some of their key names overlap. So when you create the master top-level map for the help system, you cordon off each individual sub-map into its own scope. However, there are cases where a topic from one sub-map needs to link to a topic in another sub-map. If key scopes were air-tight - as they were in my initial proposal - then there would be no way to do this short of creating a new key at the root level of the map.  It would probably be extremely cumbersome to identify and author the keys that need a root-level copy. So this new version of the proposal essentially automates the creation of those root-level keys.   Chris   From: Jim Tivy [ mailto:jimt@bluestream.com ] Sent: Tuesday, April 09, 2013 1:43 PM To: 'Chris Nitchie' Subject: Scoped keys   Hi Chris   I thought to contact you directly, since you are likely thinking about this subject alot.   Thanks for the description of the proposal today.   My first objective is to simplify the understanding for the DITA user.  Then we can discuss implementation.   The two use cases:   ·         Omnibus publications that combine multiple standalone maps, each with their own set of key definitions. ·         Cases where a topic is reused at multiple locations in a map structure, but the behavior of links and/or text replacement for each use context must be different. ------------------------ For Omnibus requirement I think a keyspace idea is a good approach.   <mapref href= keyspace="course-1"/>   All keys from this map are now referenced with a qualified name such as: course-1.fookey   ---------------   For supporting different “use concepts” I think that scoping the definition of keys is a good approach. A simple approach is to specify that the keydef is a scoped definition.  Scoped definitions do not get put into the global current space but instead are defined according to their scope in the “map tree”.   <keydef keys="ProductName" scoped=”true”>    <topicmeta>       <linktext>Tractor X</linktext>    </topicmeta> </keydef>   With regards to implementation, I think changing the references – along the lines of what you mentioned - is a good idea.  Without named scopes, the processor could simply come up with unique names for the purposes of scoping.  But don’t want to get into implementation – yet.