RE: [dita] ITEM: Cross-references to Topicheads and Implicit Title-only Topics

["Ogden, Jeff" <jogden@ptc.com>]

Among other things Eliot wrote:
> 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.

Do you mean @type rather than @format?  @type defaults to "topic" unless
a value cascades from an ancestor.  @format defaults to "dita", but it
too can inherit a value that cascades from an ancestor or there are some
vague words about figuring out the format value based on the thing being
referenced.

A reference to a topicref would presumably be a reference to a map and
so the value for @format would be "ditamap" and not "topicref" or
"topic".

Eliot, the more I think and read about this the more I feel that this
just isn't something that should be decided at the last minute as the TC
tries to pull together the final pieces of DITA 1.2.  Doing this in a
rush at the last minute, we are likely to make mistakes.  It would be
better to leave this unspecified in DITA 1.2 as it was in DITA 1.1 and
then write a real proposal and run any changes through the regular
process for DITA 1.3 or DITA 2.0.

    -Jeff


> -----Original Message-----
> From: Eliot Kimber [mailto:ekimber@reallysi.com]
> Sent: Monday, April 06, 2009 4:57 PM
> To: Michael Priestley
> Cc: dita; Ogden, Jeff
> Subject: Re: [dita] ITEM: Cross-references to Topicheads and Implicit
> Title-only Topics
> 
> 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>