[dita] Link text and key references

["Nitchie, Chris" <cnitchie@ptc.com>]

Hi all,

I'm still new here, so I apologize in advance if I'm either questioning
closed issues or missing something in the spec.

I'm trying to determine if it's possible to override the visible text
within various key referencing tags, specifically xref, using a key
defining topicref, and I'm having trouble figuring it out based on the
spec.  The section "Key-based (indirect) addressing"
(archSpec/keyref.dita) says the following:

====
When a key definition has a <topicmeta> subelement, elements that refer
to that key and
that are empty may get their effective content from the first matching
subelement of the
<topicmeta> subelement of the key-defining topicref.

When a key definition has no @href value, references to that key will
not result in a link,
even if they do contain an @href attribute of their own. If the key
definition also does not
contain a <topicmeta> subelement, empty elements that refer to the key
(such as <link
keyref="a"/> or <xref keyref="a" href="fallback.dita"/>) are removed.
Matching element content for key references contained in @keyref or
@conkeyref attributes
falls into one of two categories:

1. For elements on which no @href attribute is available (cite, dt,
keyword, term, ph,
indexterm, index-base, and indextermref, and their specializations),
matching content is
taken from the <keyword> or <term> elements within <keywords> within
<topicmeta>. If
more than one <keyword> or <term> is present, the matching content is
taken from the
first of them.

2. For elements that in addition to @keyref or @conkeyref do specify an
@href attribute
(author, data, data-about, image, link, lq, navref, publisher, source,
topicref, xref, and their
specializations), matching content includes all elements from within the
key definition
element that are in valid context within the key reference. Elements
that are invalid within
the key reference element directly or after generalization are not
included or are filtered out.

For key reference elements that become navigation links, if there is no
matching element in
the key definition, normal link text determination rules apply as for
<xref>.
====

Does this include elements directly within the key-defining topicref, or
should the entire subtree be scanned for legal tags?  For example, if I
had the following:

<keydef keys="a" href="a.dita" scope="local">
  <topicmeta>
    <linktext>Link Text</linktext>
    <shortdesc>Link Description</shortdesc>
  </topicmeta>
</keydef>

And I had some keyrefs:

<xref keyref="a" href="a.dita" scope="local">foo</xref>
<xref keyref="a"/>
<link keyref="a" href="a.dita"
scope="local"><linktext>foo</linktext><desc>bar</desc></link>
<keyword keyref="a">Some Keyword</keyword>

1. What, if anything, happens to the text in the first xref? Since no
tags within the key definition match legal tags within xref, I presume
from the spec that it remains as-is, but I think it's reasonable to
expect that the contents of the <linktext> tag would be used.

2. If the linktext in the keydef contained <term>, would that <term> tag
be 'copied' to the xrefs when they're published?

3. Should the second xref derive its contents from the referenced a.dita
file, or should it use the link text from the keydef? The spec suggests
the former, intuition suggests the latter.

4. I'm pretty sure the link would have its <linktext> replaced by the
keydef, but I'm not at all sure what would happen to the <desc> tag.
Stay as is?  Be removed?  I think it's again reasonable to expect the
desc to be replaced by the shortdesc in the keydef, but that's not what
the spec says. Since there's no way to get <desc> inside <topicref>, is
it even possible to override this via key?

5. The spec is pretty clear on the keyref case - it becomes a hyperlink
to a.dita, and since there are no <keyword> or <term> tags in the
keydef, the content is unchanged. I just want to make sure <linktext>
shouldn't be used in this case.

In the above quote from the spec, if we replace 'within' with 'within
the subtree of', I think this solves a lot of the confusion. In
addition, an example of replacing the text of an xref would be helpful.
Also, If processors should not use <linktext> in some of these
situations, then perhaps the spec should say that explicitly; even
though the spec as currently written doesn't allow it, I find it
confusing.

Many thanks,

Chris