Re: [dita] RE: Scoped keys

[Eliot Kimber <ekimber@rsicms.com>]

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/