Key definitions and key references in LwDITA

["Robert D Anderson" <robander@us.ibm.com>]

As currently defined, the <keydef> element can reference a URI with @href, but doesn't have the @format and @scope attributes that generally go with @href. As we've discovered over time, these attributes should always travel in a group (if you have an element that can provide a URI there may be a need to specify the scope and / or format). I see these three are already defined in a group that gets used on <topicref>; the same group should be used on <keydef>.

At least - that is the case as long as <keydef> is intended for use as both text reuse and as link targets. I assume that's the case. It is certainly the case for <topicref> with keys, and if <keydef> cannot be used for link targets, then we're back to not having a way to reference something that is not part of the TOC / part of the content.

After noting that I started looking at the other elements that allow @href. We have the same situation on both <image> and <data>, which allow you to specify @href but do not allow you to designate that URI as external / do not allow you to provide a format.

The lack of @scope/@format regularly (if infrequently) came up for my users with images in DITA 1.0 and 1.1 -- there is occasionally a desire to refer to an external image out on the web and have it appear inline. Based on those concerns, we added @scope and @format to images in DITA 1.2. As of DITA 1.3, they are universal for referencing elements - if you have @href, you also have @scope and @format.

I'm guessing this is also likely to come up with LwDITA - it's probably not that strange for simple marketing material to refer to campaign images or company logos out on the web, rather than to copies stored locally?

Based on the DITA 1.0 and 1.1 learning curve I'd suggest taking the same approach here, and ensure that any element which allows @href can also allow @scope + @format. As with my earlier note about complexity - it ends up being less of a cognitive burden if all referencing elements work the same way than if some referencing elements can refer to external material / alternative formats and other referencing elements cannot.

Regards, Robert D. Anderson DITA-OT lead and Co-editor DITA 1.3 specification, Digital Services Group
E-mail: robander@us.ibm.com Digital Services Group
11501 BURNET RD,, TX, 78758-3400, AUSTIN, USA