Keyref rendering FAQ item

["Su-Laine Yeo" <su-laine.yeo@justsystems.com>]

Title: Keyref rendering FAQ item

Hi everyone,

Here's a first draft of my FAQ item on key resolution for complex content. Please send substantive feedback to the list, and stylistic feedback to me directly.

One thing that jumps out at me is that if a keyref-bearing element has its own content, processors should give it lowest priority if the element type cannot take a @href, and highest priority if the element type can take a @href. Is this what is intended?

Best,

Su-Laine

Su-Laine Yeo
Solutions Consultant

JustSystems Canada, Inc.
Office: 1 (778) 327-6356
syeo@justsystems.com

**************************

Question: What should rendering tools display in the place of elements which have a keyref attribute?

Answer: This part of the DITA 1.2 specification was under-specified, and the details below will be included in an erratum to the DITA 1.2 specification. There are three sets of rules, for different element types:

- elements which cannot take a @href, except <abbreviated-form>

- elements which can take a href

- <abbreviated-form> element

A processor must use the first rule which allows it to render a string, image, or other content in the place of the keyref-bearing element. For example, if a rule says to use the contents of the <linktext> element in <topicmeta> in the key-defining element, skip the rule if <linktext> does not exist, if it is excluded through conditional filtering, or if it is completely empty.

For keyref-bearing elements which cannot take a @href (such as cite, dt, keyword, term, ph, indexterm, index-base, and indextermref, and their specializations):

- First choice: Use the contents of the first <keyword> or <term> within <keywords> within <topicmeta> in the key-defining element.

- Second choice: Use the contents of the <linktext> element within <topicmeta> in the key-defining element.

- Third choice:  Use the contents of the <navtitle> element within <topicmeta> in the key-defining element.

- Fourth choice: Use the contents of the keyref-bearing element.

For keyref-bearing elements which can take a @href (such as author, data, data-about, image, link, lq, navref, publisher, source, topicref, xref, and their specializations):

- First choice: Resolve the indirect reference as if it were a direct one. For example, if a topic has  <xref keyref = "foo">bar</xref> where the key is resolved using <keydef keys = "foo" href = ""foo.dita"/>," it should be rendered as if it were <xref href = ""foo.dita">bar</xref>.

- Second choice: Use the contents of the <linktext> element in <topicmeta> in the key-defining element.

In addition to the above rules: If the keyref-bearing element can also contain a <desc> subelement, and the key-defining element includes a <shortdesc> within <topicmeta>, copy the <shortdesc> contents into the <desc> element.

<abbreviated-form> element:

Processors should follow special rules for this element, detailed in http://docs.oasis-open.org/dita/v1.2/os/spec/langref/abbreviated-form.html#abbreviated-form.  If the specific rules for <abbreviated-form> do not produce any content that can be rendered, processors may follow general processing rules for keyref-bearing elements which cannot take a @href.

Notes:

When displaying content from <topicmeta> in the place of a keyref-bearing element, markup that is valid in the context of the keyref-bearing element should be kept. If <topicmeta> contains markup that is not valid in the new context, the invalid markup may be removed. The content within invalid markup may also be removed.

Note that processors are not required to display any elements from <topicmeta> other than <keyword>, <term>, <linktext>. and <navtitle>. The sentence in the DITA 1.2 specification which says, "matching content includes all elements from within the key definition element that are in valid context within the key reference." (http://docs.oasis-open.org/dita/v1.2/os/spec/archSpec/processing_key_references.html) is an error and should be ignored.