OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.

 


Help: OASIS Mailing Lists Help | MarkMail Help

dita message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]


Subject: RE: [dita] RE: Scoped keys


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 




[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]