Re: [dita] conref.dita editorial review

[Eliot Kimber <ekimber@reallysi.com>]

On 11/24/09 11:12 PM, "Bruce Nevin (bnevin)" <bnevin@cisco.com> wrote:

> [Just got SVN working again. Thanks, Kris.]
> 
> I think the following revision resolves question 2. Please let me know
> if problems remain.
> 
>     A key is bound to the resource addressed by the <topicref>
>     or <keydef> in which it is defined. The resource to which
>     a key is bound may be a DITA map or topic, or it may be a
>     non-DITA resource such as a graphic or an object specified
>     by an external URI. If no address is provided, the key is
>     bound to the information provided by the <topicref>, such
>     as a title and metadata.
> 
>     When a key is bound to an element within the <topicmeta>
>     of the key-defining <keydef> or <topicref>, the content of
>     that element is rendered as the content of the referenced
>     element. By this means, the referenced element can be used
>     as a variable, and the content of the bound element in
>     the definition in the map provides a way to set the
>     variable's value wherever that key occurs within the
>     document aggregated by that map.
> 
> Eliot: can a key be bound both to an element in the local <topicmeta>
> and to the resource referenced by the @href attribute in <topicref> or
> <keydef>, at the same time? If so, could you provide an example? Such an
> example is needed in several places in the lang ref (e.g. keydef, Using
> keys and keyref) and maybe in the arch spec as well. And if so, then the
> above text needs further work.
> 

When using a key reference from element's that can have their effective
value provided by the key definition, both the bound resource and the key
definition's topicmeta content come into play.

Consider, for example, this <keyword> element:

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

Processed with this key definition as the effective definition of
"apple-gloss":

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

When processed to e.g., HTML, I would expect to get a navigable link to the
glossary entry apple-fruite-enUS.dita and have the effective text of the
link be "apple":

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

That is, the key definition acts as both an indirection for constructing the
navigation link and as a conref source for determining the effective value
of the <keyword> element.

Here's another example for <term>:

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

With this keydef:

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


Will use the text "Apple" for the link text and be a link to the Web site.

Cheers,

Eliot

-- 
Eliot Kimber
Senior Solutions Architect
"Bringing Strategy, Content, and Technology Together"
Main: 610.631.6770
www.reallysi.com
www.rsuitecms.com