key reference error vs. warning

["Ogden, Jeff" <jogden@ptc.com>]

Eliot, Robert, and I would like to request the TC’s approval for what is almost, but not quite, an editorial change to the DITA 1.2 specification.  This has to do with treating key references on topic references in maps that reference maps that contain key definitions as a situation where a warning message MAY be issued rather than as an error where an error message SHOULD be issued.

 

Among other things the Indirect Referencing proposal (#12007) that was approved by the TC says:

 

21)  Key references are not allowed on and will be treated as an error if used with href or conkeyref attributes on topicref elements that reference maps or portions of maps that define keys.

 

The draft version of the DITA 1.2 spec. currently says

 

It is an error for conkeyref attributes to be used on topicref elements or specializations that reference maps or portions of maps when the referenced maps define keys. In such cases the key definitions from the referenced maps are not used, an implementation SHOULD give an error message, and MAY (but need not) recover from the error condition by ignoring the key definitions.

 

The draft spec. statement is more explicit than what was said in proposal #12007 and as a result is better. This statement in the draft spec. only addresses the use of @conkeyref on topicrefs and doesn’t address the use of @keyref on topicrefs, but the same situation could arise for both attributes.

 

As Eliot was revising this section of the draft spec. he came to feel that treating this case as an error is too harsh. And after a good deal of e-mail discussion between Eliot, Robert, and myself, we’d like to recommend that this case not be treated as an error, but as a case where a warning MAY be issued. And while the three of us agree that MAY is acceptable here and that MUST is not, there is a feeling on my part that SHOULD would be better than MAY, while Eliot is more comfortable with MAY or even having the spec. be silent on the subject of a warning message.

 

If the TC agrees to this change, the DITA 1.2 spec. would be changed to include wording something like this (my suggestion):

 

keyref and conkeyref attributes on topicref elements or topicref specializations are ignored for the purpose of constructing the list of key names that will be used to resolve key references. Processors may (but are not required to) issue a warning if later processing determines that the ignored key references directly or indirectly reference maps that contain key definitions.

 

Or like this (Eliot’s suggestion):

 

Only directly-addressed maps contribute to the map tree used to determine key definition occurrence order (and thus to the determination of effective key definitions). For topicrefs that use @keyref or @conkeyref and that are determined, after the key space is constructed, to point to maps that contain, directly or indirectly, key definitions, processors may issue a warning that the reference did not contribute to the key space construction.

 

With the exact wording finalized by the writer(s).

 

   -Jeff (Eliot and Robert)