DITA Proposed Feature # 40

Keyref architecture

Longer description

The keyref attribute is intended to provide a key-based referencing scheme, with a level of indirection to allow for remapping of targets when content is reused in contexts where the target is unavailable, or a new target needs to be substituted, or several targets need to be collapsed into one.

Scope

Major

Use Case

First information architect creates set of content with DITA map. In the DITA map, the information architect identifies a key value associated with each topicref. EG: <topicref href="xyz.dita#mytopic" keys="topicone"/>
Authors create references in the content set (eg conref, keyref, href) using the key to identify the topic, instead of the path plus topicid. EG: <p conref="topicone/mypara"/>, <xref keyref="topicone/mytable"/>, <link keyref="topicone"/>
Second information architect reuses some content from the first content set, but not xyz.dita#mytopic. They remap the key to an equivalent topic (potentially one they create for the purpose). EG: <topicref href="abc.dita#anothertopic" keys="mynewtopic topicone"/>
When the target topic has no equivalent in the information set, the reusing information architect explicitly maps the key to a topicref with no href, eg: <topicref keys="topicone"/>

Would also be nice to allow keyref to topics without an associated key, using their topicid as a default; ie if no key exists for a keyref, look for topicids that match instead; saves a step for the first information architect.

Does require the target topic to have the same internal IDs (eg on <p> or <ph>-level tags), if they are targets; this proposal only supports remapping of the parent topic id, for the sake of simplicity, and for the sake of keeping the map focus on topics rather than elements below the topic level.

Technical Requirements

Add keys attribute to topicref in map

Document keyref syntax: key (or topicid) optionally followed by / and element id; for example,

keyref="mytopicid"
keyref="key124valuethatmapstomytopic"
keyref="mytopicid/myelementid
keyref="key124valuethatmapstomytopic/myelementid"

Dcument keys syntax: any number of blank-delimited values, which cannot contain the "/" character

Document expected behavior in language and architectural specs, as follows::

match on topicref with @href, or on topic id: Element with @keyref is turned into link to target identified; if element is empty, text of element is pulled from topicref's title, or topicref's target's title
match on topicref with title but no @href: Element with @keyref is not turned into link. If element is empty, text of element is pulled from topicref's title.
match on topicref with neither title nor @href: Element with @keyref is not turned into link. If element is empty, element is left empty.
no match: Element with @keyref is not turned into link. If element is empty, element is left empty. Warning should be emitted by keyref processor.

Match will be made with the first matching occurrence of a key, based on the sequence of maps processed; if no matches in maps, can then check on topic id matches.

Costs

Toolkit will need to include preprocessing pass to turn key references into file/topic references for HTML or other output. Usability requirements on editors to support key-based references, for example so that conrefs can continue being resolved in the editor, even though the conref attribute on its own is no longer enough to locate the content (the conref must be interpreted in the context of a map file that associates the target key with a particular topic). This puts a further premium on supporting map-based authoring, ie authoring a topic in the context of a map, rather than as isolated chunks.

Benefits

Major increase in reusability of content. Removes need for file-system-centric workarounds such as conref substitution. Opprtunity for improved compatibility between different content management systems, and between CMSs and other systems such as file systems, dynamic web publishing systems, databases, etc. - each of which could use their own key scheme and just externalize it as a map file for the keyed content, as well as remapping keys to the preferred linking or retrieval mechanism at runtime.

Time Required

2 1 hour meetings to agree on requirements and solution (hoping)

1 day to document

Issues

We currently have keyref, href, and conref; do we need to create conkeyref for parallelism between inclusion and referencing mechanisms? Or deprecate href? Or make href available wherever keyref is available, and deprecate keyref? My recommendation would be to deprecate keyref wherever href is already available, since a keyref value could be stored in an href without issue; however, maintain the distinction between keyref and href on other elements, since href allows both direct and indirect referencing, whereas keyref requires indirect referencing.
Do we want to use a keys attribute, or a specialization of the resourceid element? (or the resourceid element itself, as it currently stands?) Since the key is the flipside of the existing keyref attribute, I think it makes sense to have it be a) a core part of the DITA architecture rather than a domain; and b) an attribute, so key and keyref are more immediately apparent as matching; and c) remove the need for a set of contained elements when the basic capability is quite simple.
Do we support keyref to topicid as a default? IE, if no matching key found, check for matching topic ids?
Is it okay not to support direct remapping below the element level? If the limitation is acceptable, it buys us a lot in terms of compartmentalizing the problem and maintaining architectural consistency (maps only reference topics, stuff below the topic level is handled within topics not by maps).