Re: [dita] ITEM: Cross-references to Topicheads and ImplicitTitle-only Topics

[Eliot Kimber <ekimber@reallysi.com>]

On 4/4/09 12:01 PM, "Michael Priestley" <mpriestl@ca.ibm.com> wrote:

>> Remember too that DITA 1.2 is adding new feature, the ability to point
> from
>> non-xref elements to topicrefs (via keyref) but it always had the ability
> to
>> use xref to point to map components. So the addition of keyref doesn't
>> actually change anything about either the ability to create
>> topic-element-to-map-element relationships.
> 
> I'm just going to poke at this a bit. It has always had the ability to use
> xref to point to map components, but the resolution of those links has
> never been defined before. I think you have gone with the conclusion that
> they should be resolved as an indirection mechanism, and that's a logical
> conclusion, but it's not the only possible conclusion.

> For example, let's say I have a standard infocenter layout: nav on the
> left, content on the right. Let's say that the content is one big file,
> and the nav points to anchor points inside that file (the topics). If I
> click on a nav entry, it scrolls the content pane to the right topic. If I
> click on an xref in the content pane that points to a nav entry, wouldn't
> it be reasonable to scroll the nav pane to that entry?
> 
> The use of keyref is unambiguous - an xref with a keyref points to
> whatever the topicref with the key points to (which might be a topic, or
> might be another nav entry for that matter).
> 
> But the use of href to point to a topicref is ambiguous. It does not
> necessarily mean pointing to the topicref's target, because there are
> situations in which it might be desirable to link to locations within the
> navigation context.

Short version: 

This analysis is confusing linking with addressing.

The use/mention problem is real (am I linking to a topicref or to the
ultimate target of the topicref?) and the need to allow links to topicrefs
so they do not act as indirectors is real. But using the form of address to
indicate author intent is not the right way to satisfy the requirement
(because the form of address *should not* affect link semantics).

But there is an easy solution: use the existing format= attribute to
indicate author intent irrespective of form of address.

Long version:

Michael is confusing the semantic of the *link* with the form of address.
The semantic of the link *cannot* be determined by the form of address.

The problem is not that keyref *means* one thing and href= another, it's
that there isn't an obvious way to indicate author intent for xrefs (and
<link> links) to topicrefs.

In the case of conref and term, there is no ambiguity because, in the first
case, there is only one possible semantic (use by reference) and therefore
keyref and href are exactly equivalent (as they should be). In the case of
term href= was never allowed so again there is no ambiguity.

It is only in the case of xref (and <link>, but it would be rare, I think,
for anyone to author links directly for any embedded link) that there is
potential ambiguity and therefore potential confusion between semantics
(author-intended ultimate target of the link) and addressing (href- or
keyref-based addresses).

I do not disagree that links to navigation artifacts are meaningful and
useful. I'm only disagreeing with the mechanism by which that intent is
indicated in the DITA source markup.

Our initial mistake as a TC (and mine for not realizing earlier that we were
making this mistake) was to indicate that it is *keyref* that makes a
topicref an indirector rather than indicating that topicrefs are
*inherently* indirectors when pointed to from topic elements unless the
author says otherwise for those cases where an alternative meaning is
meaningful (xref and link).

I should have realized the problem we're now discussing much earlier but we
were all focused on the use of keyref in the context of replacing hrefs *to
topics* with indirect links to the same topic and were not considering using
it to replace existing hrefs to topicrefs. That allowed us all to confuse
the semantic (links to topicrefs for indirection) with the form of address
(keyref).

Once you correct this conceptual error and make the distinction between
topicrefs as the indirector and the form of address used to point to the
topicref, then you realize, as we have here, that you then have a
use/mention problem since it may be meaningful and useful to xref (or
<link>) to topicrefs rather than indirecting through them. [Note that having
a separate dedicated indirector would avoid this potential for confusion but
adds its own complexity--in this case I think the use of topicref for
indirection is the better design choice.]

So in the case of xrefs to topicrefs, via keyref or href, the author intent
could reasonably be to link to the ultimate topic pointed to (or implied) by
the topicref or to the navigation artifact implied by the topicref. I think
that all other links to topicrefs from within topic content would either be
for conref, which allows no ambiguity about intent, or from elements that
don't allow href at all (<term>) and for which the meaning of links to
topicrefs is made explicit in the 1.2 spec (indirection in all cases, either
to the ultimate topic or to the topicref's linktext).

Looking at the 3/24 version of the language ref for xref, it's clear we need
to update the description to clarify this issue and generalize the intro
language, as it specifically mentions xrefs to topics or non-DITA stuff but
does not mention xrefs to map components as being a meaningful option.

To solve this problem, it seems to me that the format= attribute is already
available to provide unambiguous author intent.

In particular, if the author says format="topicref" as opposed to the
default of "topic", I think that makes it clear that the author's intent is
to link to the map component/navigation artifact and not to the topic the
topicref ultimately links to or implies.

That again avoids the need to have a specific form of addressing imply a
link semantic.

So I think that, given a bit more explanatory language in the spec and
possibly defining a suggested meaning for the value "topicref" (or the
equivalent) that we can both avoid any need to have keyrefs mean something
different from hrefs for xref and <link> and allow full author control over
intent when linking to map components.

Cheers,

Eliot

----
Eliot Kimber | Senior Solutions Architect | Really Strategies, Inc.
email:  ekimber@reallysi.com <mailto:ekimber@reallysi.com>
office: 610.631.6770 | cell: 512.554.9368
2570 Boulevard of the Generals | Suite 213 | Audubon, PA 19403
www.reallysi.com <http://www.reallysi.com>  | http://blog.reallysi.com
<http://blog.reallysi.com> | www.rsuitecms.com <http://www.rsuitecms.com>