Question about keyref and replacement text

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

Hi,

As mentioned last week, I've finally completed the initial rewrite of the DITA spec topics on processing keys. Some of the changes are just clarifications of existing language, and some comes from TC meetings a year or two ago when I came back after my first attempt to do the rewrite.

It's clear to anybody who has looked at the topic that we have some complicated rules for pulling in text when using @keyref. If you're a keyword with @keyref, you can get it from one place. If you're a term, from another. Of course, ph and xref could come from a third. This means that if you are very careful, and your processor rigorously supports all of these rules, you could define one key that pulls in one set of text for most (maybe not all) keywords, one set for term, one set for most other elements, etc. While it's possible people make use of this, I'm guessing few if any do so intentionally or reliably. We don't give any examples of this very complicated scenario.

The 1.2 spec also states that when you don't have this complicated setup, any key reference that pulls text will eventually fall back to looking in <linktext>. This is actually what we use in our examples of resolving text for <keyword>. I read this and think - if I want all my references to a given key to get the same text, the best practice is to store that text inside the <linktext> element.

We can't get rid of the more complex rules (yet) in DITA 1.3, because we have to stay backwards compatible. However - how would the TC feel about highlighting the linktext approach as either a best practice for key text, or at least as a way ensure that all of your link text is the same across all uses of a single key?

Thanks -

Robert D Anderson
IBM Authoring Tools Development
Chief Architect, DITA Open Toolkit (http://dita-ot.sourceforge.net/)