Keyref Proposal

["W. Eliot Kimber" <ekimber@innodata-isogen.com>]

With regards to the keyref proposal, I think I understand the 
requirement, which I think can be stated as:

"Enable reference to a topic (either for direct use of the topic or for 
then addressing elements within the topic) via reference to a property 
of the topic within the context of a specific map, rather than to its 
specific location."

That is, given that I know that there is or should be a topic with the 
associated "key" value "foo" within my governing map, allow me to 
address the topic by reference to the value "foo", rather than to the 
specific location-dependent URL of the topic.

I certainly agree with the requirement being both valid and compelling. 
However, I'm not that keen on the details of the keyref proposal.

In particular, I think we can achieve the same functional result 
reflected in the keyref proposal with a more general addressing scheme 
that is more consistent with established Web and XML practice.

My alternative proposal is as follows:

1. Retain the proposed keys= attribute on topicref and add it to topic, 
with the same meaning as in the current keyref= proposal.

2. Replace the attribute keyref= with the attribute target=, named to be 
consistent with the XInclude specification and having the semantic of 
containing either an XPointer or a standard URL query specification 
(that is, the stuff that follows a "?" in a URI). XPointers would be for 
future use but the query would be for immediate implementation. [Note 
that XPointers and normal URL queries are syntactically distinguishable 
so there would be no problem telling which you had for a given target= 
value.] The value would be interpreted as unescaped URL strings (that 
is, you wouldn't need to replace spaces with %20 and such like).

Alternatively, replace the keyref= attribute with the direct use on URIs 
of queries (as defined in item 3 below). I don't like this approach 
however, because I feel having two attributes, one for URIs with no 
fragement ID or query, and a second one for queries and fragment IDs is 
cleaner and clearer. However, this approach is syntactically simpler and 
would require no additional attributes to the current language.

3. For queries, allow reference to any DITA-defined properties of 
topics, including a new property, "key", that would be defined either on 
topicrefs (as in the current keyref proposal) or on topics directly (I 
don't see that in the current keyref proposal but I can't think of a 
reason not to have it, given that a given topic may have multiple keys 
associated with it per the current keymap proposal).

4. Allow as one of the query keys, the term "elemid", which takes the ID 
of an element within the direct scope of the target topic. (That is, 
this replaces the term following the "/" in the current element 
addressing fragement identifier syntax.)

5. For references, the href= value is always the URL of the *map* that 
establishes the context for resolving the target= value. If unspecified, 
the context is established by the top-level map established for the 
resolution session (i.e., the input map to a rendition process or the 
map context established within a CMS or information retrieval system).

6. For conref, define the keyword "urn:dita:conref:use-target" for use 
on the conref= attribute to indicate that the default map context is 
used and that the actual target is addressed via the target= attribute 
[NOTE: I think the current keyref proposal requires something like this 
as well, otherwise it would be ambiguous when you meant a reference to a 
topic ID and when you meant a reference to a key since they are 
syntactically indistinguishable and there's no reason otherwise to 
disallow keys and IDs from having the same value (but not necessarily 
for the same topic).]

This would allow the following sorts of references:

- Reference to a topic by key:

<relrow>
   <topicref target="key=somekeyvalue"/>
</relrow>

- Reference to a topic by search title string:

<relrow>
   <topicref target="searchtitle=ResolverFactoryImpl"/>
</relrow>

- Reference to a topic by id:

<relrow>
   <topicref target="id=topic-0923465"/>
</relrow>

- Reference to a topic by search title and topic type:

<relrow>
   <topicref 
target="searchtitle=ResolverFactoryImpl&amp;topictype=concept"/>
</relrow>

Reference to a target element for conref by topic key in the default map 
context:

<note conref="urn:dita:conref:use-target"
       target="key=allnotes&amp;elemid=note-023"/>

Reference to a target element for conref by topic key in the context of 
a specific map:

<note conref="../common/re-usable-elements.ditamap"
       target="key=allnotes&amp;elemid=note-023"/>

The advantages I see of this proposal over the current keyref proposal are:

- It is more consistent with the XInclude href/target pattern, which is, 
I think, the best pattern for address representation in general.

- It is more general, allowing greater flexibility in how topics are 
addressed by property.

- It prepares us for a future where we replace the current DITA-specific 
fragment identifier syntax with the appropriate standard syntax 
(presumably XPointer).

- It allows sub-maps to establish local query resolution contexts 
without ambiguity, such that if you know that you need to do your 
resolution within the context of a specific map, you can do that by 
reference to it using href=. However, if you want to just get whatever 
you get (which is probably the more common case), you just leave the map 
context unspecified.

Another question, inherent in any form of query-based address, is what 
do to when there are multiple topics with the same key?

One answer is that it's never an *authoring* error to have multiple 
topics with the same key but it may be a run-time error to resolve a 
reference to multiple targets depending on the nature of the reference.

For example, in the context of a relationship table, there's no semantic 
or processing problem with having a single query result in multiple 
matching topics--it would be equivalent to having multiple topicrefs 
within a single relcell.

However, for the purposes of xref or conref, there is an expectation of 
at most one target.

This suggests that it's up to the resolving processor to determine what 
the right response is to multiple results from a query. It's probably 
something we need to specify clearly in the DITA spec for each distinct 
type of reference semantic DITA defines.

Another question is whether or not this same mechanism should be 
extended to maps as well. While the current keyref proposal does provide 
a form of indirection for addressing topics and their contents, it does 
not provide indirection for addressing maps. Should it? I haven't 
thought it through deeply, but I'm pretty sure it should.

Cheers,

Eliot

-- 
W. Eliot Kimber
Professional Services
Innodata Isogen
8500 N. Mopac, Suite 402
Austin, TX 78759
(214) 954-5198

ekimber@innodata-isogen.com
www.innodata-isogen.com