dita — archive

[Su-Laine Yeo <syeo@justsystems.com>]

Title: Keyref rendering FAQ item Hi everyone, Here's a first draft of my FAQ item on k ey 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 can not 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-63 56 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 p rocessor 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 i f <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 content s of the first <keyword> or <term> within <keywords> within <topicmeta> i n the key-defining element . - Second choice: Use the contents of the <linktext> element with in <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: R esolve 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 m arkup 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.