Re: [dita] Link text and key references

[Eliot Kimber <ekimber@reallysi.com>]

I think Chris' summary is the way it *should* work, in that there is
certainly a lot of value in having a "it just works" fallback for key-based
link text definition.

If that's not what the spec currently says I agree that it's what it should
say and I think it is consistent with the intent, if not the letter, of the
original proposal.

Cheers,

E.

On 4/2/10 2:38 PM, "Nitchie, Chris" <cnitchie@ptc.com> wrote:

> Robert,
> 
> Thanks much for getting back to me on this.  Sorry it's taken me so long
> to reply.  This all makes sense, and is great background.  My concern is
> that what you describe isn't exactly what the spec says; in particular,
> it seems like linktext is special, in that it can be used for content
> replacement of any key reference, even though it's not legal in all tags
> with a keyref attribute.  We should make sure the spec is as clear on
> this as we can make it.
> 
> Is this a succinct summary of the intended rules for content replacement
> via keyref?
> 
> - If the key defining element contains a matching tag for the key
> reference, that tag should be used.
> - If no matching tag is present, the contents of the <linktext> tag
> should be used, minus any nodes (text or elements) which do not match
> the content model of the key reference.
> - Special case: <desc> can be used to override <shortdesc> within
> <link>.
> - Else normal text determination rules apply.
> 
> Chris
> 
> -----Original Message-----
> From: Robert D Anderson [mailto:robander@us.ibm.com]
> Sent: Monday, March 22, 2010 2:40 PM
> To: Nitchie, Chris
> Cc: DITA TC
> Subject: Re: [dita] Link text and key references
> 
> Hi Chris,
> 
> I'll give my impression, and see if others agree. I haven't gone
> scanning
> the docs to verify these claims - it's just my expectation - but it
> comes
> from what I remember of the discussions.
> 
>> Does this include elements directly within the key-defining topicref,
> or
>> should the entire subtree be scanned for legal tags?  For example, if
> I
>> had the following:
>> 
>> <keydef keys="a" href="a.dita" scope="local">
>>   <topicmeta>
>>     <linktext>Link Text</linktext>
>>     <shortdesc>Link Description</shortdesc>
>>   </topicmeta>
>> </keydef>
>> 
>> And I had some keyrefs:
>> 
>> <xref keyref="a" href="a.dita" scope="local">foo</xref>
>> <xref keyref="a"/>
>> <link keyref="a" href="a.dita"
>> scope="local"><linktext>foo</linktext><desc>bar</desc></link>
>> <keyword keyref="a">Some Keyword</keyword>
>> 
>> 1. What, if anything, happens to the text in the first xref? Since no
>> tags within the key definition match legal tags within xref, I presume
>> from the spec that it remains as-is, but I think it's reasonable to
>> expect that the contents of the <linktext> tag would be used.
> 
> I think this is the one I'm least certain of.
> 
> My original expectation was that nothing happens to the text in the
> first
> xref, regardless of what is in the keydef. This is based on what I'm
> used
> to from 1.1 and earlier - if I have <xref>foo</xref>, then foo becomes
> the
> link text; if I want it to use the latest title from the target, I leave
> the xref empty. But, I think the text in the spec says otherwise - it
> says
> that link text determination rules apply *after* the keydef is
> evaluated:
>> For key reference elements that become navigation links, if there is
> no
>> matching element in
>> the key definition, normal link text determination rules apply as for
>> <xref>.
> 
> So - I agree that it's reasonable to expect that the contents of
> linktext
> would be used. The confusion here may arise from the fact that a text
> node
> is not a tag, and the talk is about matching elements. Certainly, when
> the
> xref is empty, the text node in linktext is considered matching content;
> so
> if keydef ever overrides the text in an xref, I think it does so here as
> well.
> 
>> 2. If the linktext in the keydef contained <term>, would that <term>
> tag
>> be 'copied' to the xrefs when they're published?
> 
> I expect that, if elements are part of the new link text (whether it is
> keyword, term, a specialized term, etc), then the elements are 'copied'
> along with the text.
> 
>> 3. Should the second xref derive its contents from the referenced
> a.dita
>> file, or should it use the link text from the keydef? The spec
> suggests
>> the former, intuition suggests the latter.
> 
> I'll rely on this part of the spec quoted in #1 -- "if there is no
> matching
> element..."
> 
> As mentioned in #1, I think that "matching element" means "valid content
> that becomes link text". So I would expect that, if the linktext inside
> the
> keydef is actually valid replacement text, that is used.
> 
>> 4. I'm pretty sure the link would have its <linktext> replaced by the
>> keydef, but I'm not at all sure what would happen to the <desc> tag.
>> Stay as is?  Be removed?  I think it's again reasonable to expect the
>> desc to be replaced by the shortdesc in the keydef, but that's not
> what
>> the spec says. Since there's no way to get <desc> inside <topicref>,
> is
>> it even possible to override this via key?
> 
> The <desc> in a link and <shortdesc> in topicmeta serve exactly the same
> purpose, so I think they should be treated the same. If linktext in the
> keydef overrides linktext in a link, then I'd expect shortdesc in the
> topicmeta to override desc in a link or xref.
> 
>> 5. The spec is pretty clear on the keyref case - it becomes a
> hyperlink
>> to a.dita, and since there are no <keyword> or <term> tags in the
>> keydef, the content is unchanged. I just want to make sure <linktext>
>> shouldn't be used in this case.
> 
> I think it's pretty clear on this as well - the keyword text remains
> unchanged.
> 
>> In the above quote from the spec, if we replace 'within' with 'within
>> the subtree of', I think this solves a lot of the confusion. In
>> addition, an example of replacing the text of an xref would be
> helpful.
>> Also, If processors should not use <linktext> in some of these
>> situations, then perhaps the spec should say that explicitly; even
>> though the spec as currently written doesn't allow it, I find it
>> confusing.
> 
> I think rather than saying "within the subtree of", we should be more
> explicit - say "within the linktext", "within the desc", "keyword or
> text
> element within <keywords>", or whatever is actually meant. The subtree
> of
> the <keydef> or <topicref> leaves room for a whole lot of cases.
> 
> I'm hoping to hear what Eliot says about this, as (I believe) the author
> of
> that topic...
> 
> Robert D Anderson
> IBM Authoring Tools Development
> Chief Architect, DITA Open Toolkit
> 
> "Nitchie, Chris" <cnitchie@ptc.com> wrote on 03/22/2010 01:50:42 PM:
> 
>> "Nitchie, Chris" <cnitchie@ptc.com>
>> 03/22/2010 01:50 PM
>> 
>> To
>> 
>> "DITA TC" <dita@lists.oasis-open.org>
>> 
>> cc
>> 
>> Subject
>> 
>> [dita] Link text and key references
>> 
>> Hi all,
>> 
>> I'm still new here, so I apologize in advance if I'm either
> questioning
>> closed issues or missing something in the spec.
>> 
>> I'm trying to determine if it's possible to override the visible text
>> within various key referencing tags, specifically xref, using a key
>> defining topicref, and I'm having trouble figuring it out based on the
>> spec.  The section "Key-based (indirect) addressing"
>> (archSpec/keyref.dita) says the following:
>> 
>> ====
>> When a key definition has a <topicmeta> subelement, elements that
> refer
>> to that key and
>> that are empty may get their effective content from the first matching
>> subelement of the
>> <topicmeta> subelement of the key-defining topicref.
>> 
>> When a key definition has no @href value, references to that key will
>> not result in a link,
>> even if they do contain an @href attribute of their own. If the key
>> definition also does not
>> contain a <topicmeta> subelement, empty elements that refer to the key
>> (such as <link
>> keyref="a"/> or <xref keyref="a" href="fallback.dita"/>) are removed.
>> Matching element content for key references contained in @keyref or
>> @conkeyref attributes
>> falls into one of two categories:
>> 
>> 1. For elements on which no @href attribute is available (cite, dt,
>> keyword, term, ph,
>> indexterm, index-base, and indextermref, and their specializations),
>> matching content is
>> taken from the <keyword> or <term> elements within <keywords> within
>> <topicmeta>. If
>> more than one <keyword> or <term> is present, the matching content is
>> taken from the
>> first of them.
>> 
>> 2. For elements that in addition to @keyref or @conkeyref do specify
> an
>> @href attribute
>> (author, data, data-about, image, link, lq, navref, publisher, source,
>> topicref, xref, and their
>> specializations), matching content includes all elements from within
> the
>> key definition
>> element that are in valid context within the key reference. Elements
>> that are invalid within
>> the key reference element directly or after generalization are not
>> included or are filtered out.
>> 
>> For key reference elements that become navigation links, if there is
> no
>> matching element in
>> the key definition, normal link text determination rules apply as for
>> <xref>.
>> ====
>> 
>> Does this include elements directly within the key-defining topicref,
> or
>> should the entire subtree be scanned for legal tags?  For example, if
> I
>> had the following:
>> 
>> <keydef keys="a" href="a.dita" scope="local">
>>   <topicmeta>
>>     <linktext>Link Text</linktext>
>>     <shortdesc>Link Description</shortdesc>
>>   </topicmeta>
>> </keydef>
>> 
>> And I had some keyrefs:
>> 
>> <xref keyref="a" href="a.dita" scope="local">foo</xref>
>> <xref keyref="a"/>
>> <link keyref="a" href="a.dita"
>> scope="local"><linktext>foo</linktext><desc>bar</desc></link>
>> <keyword keyref="a">Some Keyword</keyword>
>> 
>> 1. What, if anything, happens to the text in the first xref? Since no
>> tags within the key definition match legal tags within xref, I presume
>> from the spec that it remains as-is, but I think it's reasonable to
>> expect that the contents of the <linktext> tag would be used.
>> 
>> 2. If the linktext in the keydef contained <term>, would that <term>
> tag
>> be 'copied' to the xrefs when they're published?
>> 
>> 3. Should the second xref derive its contents from the referenced
> a.dita
>> file, or should it use the link text from the keydef? The spec
> suggests
>> the former, intuition suggests the latter.
>> 
>> 4. I'm pretty sure the link would have its <linktext> replaced by the
>> keydef, but I'm not at all sure what would happen to the <desc> tag.
>> Stay as is?  Be removed?  I think it's again reasonable to expect the
>> desc to be replaced by the shortdesc in the keydef, but that's not
> what
>> the spec says. Since there's no way to get <desc> inside <topicref>,
> is
>> it even possible to override this via key?
>> 
>> 5. The spec is pretty clear on the keyref case - it becomes a
> hyperlink
>> to a.dita, and since there are no <keyword> or <term> tags in the
>> keydef, the content is unchanged. I just want to make sure <linktext>
>> shouldn't be used in this case.
>> 
>> In the above quote from the spec, if we replace 'within' with 'within
>> the subtree of', I think this solves a lot of the confusion. In
>> addition, an example of replacing the text of an xref would be
> helpful.
>> Also, If processors should not use <linktext> in some of these
>> situations, then perhaps the spec should say that explicitly; even
>> though the spec as currently written doesn't allow it, I find it
>> confusing.
>> 
>> Many thanks,
>> 
>> Chris
>> 
>> ---------------------------------------------------------------------
>> To unsubscribe from this mail list, you must leave the OASIS TC that
>> generates this mail.  Follow this link to all your TCs in OASIS at:
>> https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php
>> 
> 
> 
> ---------------------------------------------------------------------
> To unsubscribe from this mail list, you must leave the OASIS TC that
> generates this mail.  Follow this link to all your TCs in OASIS at:
> https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php
> 

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