OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.

 


Help: OASIS Mailing Lists Help | MarkMail Help

dita message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]


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
>



[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]