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