RE: [dita] conref.dita editorial review

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

In the first example, what about

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

Does the content specifed by the keyref replace the content of
<keyword>, and if href="glossary/apple-fruit-enUS.dita" fails does the
content of <keyword> provide a fall-back?

Likewise, could we rewrite the second example as

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

Does the content of <term> provide a fallback in case the keydef isn't
in the glossary or catalog of terms as follows?

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

If this is the expected behavior, wouldn't that be recommended practice?
If it's not the expected behavior, should it be?

	/Bruce

> -----Original Message-----
> From: Eliot Kimber [mailto:ekimber@reallysi.com] 
> Sent: Wednesday, November 25, 2009 9:58 AM
> To: Bruce Nevin (bnevin); Michael Priestley
> Cc: dita
> Subject: Re: [dita] conref.dita editorial review
> 
> 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
> 
>