[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: key reference error vs. warning
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) |
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]