Re: [dita-comment] DITA1.2: Query on <desc> element's content in akey referencing <link> element

[Eliot Kimber <ekimber@reallysi.com>]

We discussed this some more in the TC meeting and Robert realized that his
original analysis was not quite right.

The general intent of the design is that any text in the content of linking
elements is used in preference to either text provided by the ultimate link
target or any intermediate key definitions. However, processors do have
license to do something different. That is, the construction of link text,
especially for xrefs, is ultimately a matter of presentation style.

Here's what the spec currently says in topic 2.1.3.3 DITA Linking:

<lq>
Most navigation links have an associated "link text", which is the text used
to render the link so that it can be used. For all elements that allow or
require link text, the link text may be specified as part of the linking
element or, if unspecified, should be taken from the referenced resource.
The details for how the link text for a given element should or may be
generated are defined for that element type and may also be determined
entirely by a rendition processor.

In the specific case of cross references created using <xref> and related
links using <link>, the potential set of rules for constructing link text is
essentially unbounded. Processors may, for example, define conventions for
the value of @outputclass by which authors can indicate the details of how
the link text should be constructed, or they may provide appropriate
configuration options for controlling or customizing the construction of
link text in cross references.
</lq>

For elements that only take keyref (e.g., keyword and term), the spec is
explicit that they get their link text from key definitions only when they
have empty content.

Cheers,

Eliot



On 9/13/10 5:41 AM, "Nakshatra Bhardwaj" <nbhardwa@adobe.com> wrote:

> Hi Robert,
> 
> In your example:
> 
> <link keyref="a" href="topictarget">
>   <linktext>Topic linktext</linktext>
>   <desc>Topic desc</desc>
> </link>
>        
> Shouldn't <linktext> update itself from the key-defining element only when it
> is an *empty element*. I agree that during the insertion of <link> element the
> <linktext> from the topicmeta of the key defining element should be seen. But
> once the user has provided his/her own linktext we should not override it.
> Otherwise user will not have the flexibility to use alternate text for
> linktext element.
> 
> So link text for each link should be "Map linktext" and <desc> content for
> link should be "Map shortdesc" when your example should be like this-
> <link keyref="a" href="topictarget">
>   <linktext/>
>   <desc/>
> </link>
> 
> My question was whether to necessarily bring in <desc> content whenever a link
> is inserted or only bring it when an empty desc element is present.
> For Example:
> <link keyref="a" href="topictarget">
>   <linktext></linktext>
> </link>
> 
> Here, in my opinion, the linktext should bring in content from the key
> defining element. And in case when no <desc> element is present we should not
> bring in the <shortdesc> content in the example above.
> 
> Regards,
> Nakshatra
> 
> -----Original Message-----
> From: Robert D Anderson [mailto:robander@us.ibm.com]
> Sent: 09 September 2010 23:52
> To: Nakshatra Bhardwaj
> Cc: dita-comment@lists.oasis-open.org
> Subject: Re: [dita-comment] DITA1.2: Query on <desc> element's content in a
> key referencing <link> element
> 
> Hi Nakshatra,
> 
> First - sorry for the delay in this response.
> 
> My interpretation of this is that the shortdesc / desc content should work
> much the same as the linktext. That is to say, assume I have this key
> definition:
> <topicref keys="a" href="maptarget">
>   <topicmeta>
>     <linktext>Map linktext</linktext>
>     <shortdesc>Map shortdesc</shortdesc>
>   </topicmeta>
> </topicref>
> 
> Now say I have these two uses in a topic:
> <link keyref="a"/>
> <link keyref="a" href="topictarget">
>   <linktext>Topic linktext</linktext>
>   <desc>Topic desc</desc>
> </link>
> 
> In this case, the target for each link will be "maptarget" and the link
> text for each link will be "Map linktext". It is logical that the short
> description should work the same way as the link text, so the effective
> <desc> content for each link will be "Map shortdesc". I believe that the
> topic should be updated to clarify that shortdesc works the same way here
> as linktext.
> 
> Does that make sense?
> 
> Thanks -
> 
> Robert D Anderson
> IBM Authoring Tools Development
> Chief Architect, DITA Open Toolkit
> 
> 
> 
> From:   Nakshatra Bhardwaj <nbhardwa@adobe.com>
> To:     "dita-comment@lists.oasis-open.org"
>             <dita-comment@lists.oasis-open.org>
> Date:   07/21/2010 08:19 AM
> Subject:        [dita-comment] DITA1.2: Query on <desc> element's content in a
>             key referencing <link> element
> 
> 
> 
> Hi All,
> 
> I would like to have some additional input on section ³2.1.3.4.3.3
> Processing key references² in the Specs_Review#5.
> 
> The specs say that ³For <link> tags with a keyref attribute, the contents
> of the <shortdesc> tag in the key-defining element should provide the
> <desc> contents.²
> The question I have is how should DITA processors handle insertion of links
> in such a case. As per my understanding I have come to these conclusions
> for linktext and desc elements-
> On insertion of <link> element the <linktext> element would automatically
> get the effective content from topicmeta¹s <linktext> element. In case the
> element has been provided alternate text by the author, the processor
> should honour that and not bring in content from the topicmeta of the
> key-defining element.
> 
> Now coming to my question-
> What should the processor ideally do with the linktext¹s <desc> element if
> the topicmeta provides a <shortdesc> element.
> Should the <shortdesc> element be pulled in automatically *every time* the
> links are created?
> OR the <desc> element should be populated with content only when the user
> inserts the <desc> element and also in case where the topic has an empty
> <desc> element for that <link> element.
> 
> Regards,
> Nakshatra
> 

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