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] key names


Just to be clear for myself, it sounds to me that these names should be opaque strings in terms of processing. I have not implemented this sort of processing yet, but that is how I would use them under the covers in my approach. In processing, when do these values cross the line from being look-up keys within the processing system (which I would think should be unique ids or opaque strings in which encoding is not needed) to RIs that are meaningfully addressable in world space (the only place where URL encoding normally takes place)?
--
Don

On 3/22/2016 1:40 PM, Jim Tivy wrote:

If I understand this right.

 

I would not give people using a non DITA key scoping an upgrade path in that manner at the expense of new users.

 

I do not see in the spec where keyscope name is specified to have the same character rules as a key.

 

If keyscope name is unspecified we should specify it and shut the door on more dots in keyscope name.

 

However, if its a done deal then so be it.

 

Just sayin...

 

Jim

 

 

 

From: Chris Nitchie [mailto:chris.nitchie@oberontech.com]
Sent: March-22-16 10:19 AM
To: Jim Tivy; 'Eliot Kimber'; dita@lists.oasis-open.org
Subject: Re: [dita] key names

 

A key scope name has the same rules as a key name.

 

Periods are allowed in key scope and key names to allow maximum flexibility to map designers reusing topics with keyrefs initially authored in a scoped environment. We want to make it as easy as possible for map authors to reuse topics containing (possibly) (sometimes) scoped key references.

 

For example, if a topic contained

 

<xref keyref="products.productA.introduction"/>

 

That topic might be reused in

  • A large publication containing product and marketing information - e.g. containing keyscope="products", keyscope="productA" and keys="introduction"
  • A product-specific map with multiple products, e.g. one containing keyscope="products.productA" and keys="introduction"
  • A flat map specific to Product A, containing keys="products.productA.introduction"

 

Chris

 

From: <dita@lists.oasis-open.org> on behalf of Jim Tivy <jimt@bluestream.com>
Date: Tuesday, March 22, 2016 at 1:10 PM
To: 'Eliot Kimber' <ekimber@contrext.com>, "dita@lists.oasis-open.org" <dita@lists.oasis-open.org>
Subject: RE: [dita] key names

 

Yes, agreed.

On URIs the only thing DITA can do is make them IRIs in the future – if the escaping is upwardly compatible.

How about disallowing “.” in keyscope names?  Where is the definition of what makes a keyscope name?

 

From: Eliot Kimber [mailto:ekimber@contrext.com]
Sent: March-22-16 10:07 AM
To: Jim Tivy; dita@lists.oasis-open.org
Subject: Re: [dita] key names

 

@Href values are URIs and therefore must conform to URI rules, including escaping. There's nothing DITA can or should do on that account.

 

"." must be allowed in key names because it was allowed before 1.3 and there are use cases for overriding scope-qualified names in a higher-level scope by declaring a name that matches the scope-qualified version (this is why it must always be allowed to define keys that are the same as the scope-qualified version).

 

Cheers,

 

E.

----

Eliot Kimber, Owner

Contrext, LLC

 

From: dita <dita@lists.oasis-open.org> on behalf of Jim Tivy <jimt@bluestream.com>
Date: Tuesday, March 22, 2016 at 11:54 AM
To: dita <dita@lists.oasis-open.org>
Subject: [dita] key names

 

Couple of points came up in todays call – so thought to weigh in.

 

In most Unicode and XML encoding aware XML editing environments characters from the Unicode character set can be inserted as attribute or element values.

Editing environments do this because in general unescaped characters strings are more useful to humans than escaped character strings

In this context, a simple approach would be to put no restrictions on the characters used in any attributes whether they be called href or key names or keyref.

However, restrictions on key names can be useful and on hrefs critical.  For example, for an href to support the notion of identifiers that can use relative addresses “../mydir1/mydir2/myfile.xml” it is critical to refer to a specification like the URI spec or in the future perhaps the IRI spec.  This is means a “sub-syntax” is at play within the DITA XML document.  When we say the String form is according to the URI spec it means escaping is necessary in the XML context.   However in a DITA aware XML editor you could decide to let people put in unescaped values and save it to XML under the covers as escaped – that is a UX matter – not a spec matter.

For key names, however, we should go with what we consider a good naming discipline – which NMToken is.

This avoids punctuation and other characters in names making names more usable.

 

As well, allowing dots in keynames and keyscope names is bad practice because we have defined “.” as a keyscope qualifier character.  Whether bad practice becomes illegal is a point of discussion.  There can be no simple rule for parsing – unlike file extension which is the last set of characters after the last dot.  So you are putting a burden on implementors.

{Does anyone know in the spec where it specifies the characters allowed in the KeyScope name?} 

 

It seems some “sub-syntax” is necessary for hrefs and likely key names.  Enforcement of this sub-syntax is transferred to the processor and we should make it as easy as we can for the processor if it does not cost in usability.

 

cheers

Jim




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