OASIS Darwin Information Typing Architecture (DITA) TC

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

@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 http://contrext.com 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

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 http://contrext.com   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

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


http://contrext.com




 


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

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 http://contrext.com   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

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 http://contrext.com   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

Key resolution is only ever within the context of DITA-specific processing. Keys never become resource IDs in a more global sense, at least in ways defined by the DITA specification. However, one could imagine a URI syntax that allows references to keys in some processor-specific way. For example, I am implementing a DITA link manager Web application that provides a REST API for accessing the link information about sets of DITA documents. In that context I may have a URI that includes key names as either part of the URI resource specification or as fragment ID or query parameters.  So it would be a problem if key names could include characters that cannot be used in URIs in any way  (that is, characters not allowed in URIs even with escaping). But it would NOT be a problem if characters in the key names required URI escaping, since normal URI processing will unescape the characters so that the application using the URIs as input will get the original key names as used inside the DITA documents. Cheers, Eliot ---- Eliot Kimber, Owner Contrext, LLC http://contrext.com From: dita < dita@lists.oasis-open.org > on behalf of Don Day < donday@donrday.com > Date: Tuesday, March 22, 2016 at 3:24 PM To: dita < dita@lists.oasis-open.org > 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 http://contrext.com   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