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

 

 

 

 

 

 

 

 

 



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