[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
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
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]