RE: [dita] conref.dita editorial review

["Bruce Nevin (bnevin)" <bnevin@cisco.com>]

Eliot,

I propose that we should add your examples to several topics.

In the language reference: 
"keydef" -- keydef.dita 

In the architecture specification: 
"Keyref (indirect addressing)" -- keyref.dita 
"Use by reference" -- conref.dita 
"DITA map elements" -- dita_spec_23_mapstruct.dita 

Maybe also
"DITA map elements" -- dita_spec_23_mapstruct.dita
Possibly put one part of it under 
"Example of a simple map that defines keys".

Does that seem excessive, that is, are cross references adequate to put the examples in one lang ref and one arch spec topic and for readers to be led there from the others? How does this fit with your reorg of linking and addressing?

Here's a revision of the two examples:

ø¤º°`°º¤ø,¸¸,ø¤º°`°º¤ø,¸¸,ø¤º°`°º¤ø,¸

The following example illustrates use of a key reference in an empty <keyword> element to render link text and a link to a glossary definition. Assume the following DITA content:

<p>To make an <keyword keyref="apple-gloss"/> pie ...</p>

Assume that the following is the effective definition of the key name "apple-gloss" in that content:

<keydef keys="apple-gloss"
  href="glossary/apple-fruit-enUS.dita"
  <topicmeta>
   <keywords>
   <keyword>apple</keyword>
   </keywords>
  </topicmeta>
</keydef>

In an HTML rendition the expected output is a navigable link 
to the glossary entry apple-fruit-enUS.dita with link text "apple", as follows:

<p>To make an <a href="glossary/apple-fruit-enUS.html">apple</a> pie ...</p>


The following example illustrates use of a key reference in a <term> element to render link text and a link to a corporate website. Assume the following DITA content:

<p>For <term keyref="stock-APPL"/> products ...</p>

Assume that the following is the effective definition of the key name "stock-APPL" in that content:

<keydef keys="stock-APPL"
  href="http://www.apple.com";
  format="html"
  scope="external"
  <linktext><term>Apple</term></linktext>
</keydef>

In an HTML rendition the expected output is a navigable link 
to the Apple corporate website with link text "Apple", as follows:

<p>For <a
href="http://www.apple.com";>Apple</a> products ...</p>

In both examples, if the referring element is not empty, its content is rendered as the link text. If the aim is to override such content when the key reference can be resolved and for it to provide fallback link text otherwise, use the conkeyref attribute.