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


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.
 

 

 

 

 

 

 

 

 

 



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