RE: [dita] Link text and key references

["Grosso, Paul" <pgrosso@ptc.com>]

We need to get to closure on DITA 1.2, so let's move
this issue along.

Who is the author of the section that discusses this,
and can that person see what the spec currently says and
suggest possible rewording to make it clearer if necessary?

paul

> -----Original Message-----
> From: Eliot Kimber [mailto:ekimber@reallysi.com]
> Sent: Friday, 2010 April 02 14:45
> To: Nitchie, Chris; Robert D Anderson
> Cc: dita
> Subject: Re: [dita] Link text and key references
> 
> 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
> 
> 
> ---------------------------------------------------------------------
> 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