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] ITEM: Cross-references to Topicheads and Implicit Title-only Topics

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
> is to link to the map component/navigation artifact and not to the
> 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

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

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.


> -----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
> > 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
> >> 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
> use
> > xref to point to map components, but the resolution of those links
> > 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
> > left, content on the right. Let's say that the content is one big
> > 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
> > situations in which it might be desirable to link to locations
> 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
> so they do not act as indirectors is real. But using the form of
> 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
> The semantic of the link *cannot* be determined by the form of
> The problem is not that keyref *means* one thing and href= another,
> that there isn't an obvious way to indicate author intent for xrefs
> <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
> 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
> for anyone to author links directly for any embedded link) that there
> potential ambiguity and therefore potential confusion between
> (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
> useful. I'm only disagreeing with the mechanism by which that intent
> indicated in the DITA source markup.
> Our initial mistake as a TC (and mine for not realizing earlier that
> 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
> 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
> we
> were all focused on the use of keyref in the context of replacing
> *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
> the semantic (links to topicrefs for indirection) with the form of
> (keyref).
> Once you correct this conceptual error and make the distinction
> topicrefs as the indirector and the form of address used to point to
> 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
> 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
> 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
> be
> for conref, which allows no ambiguity about intent, or from elements
> 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
> need
> to update the description to clarify this issue and generalize the
> language, as it specifically mentions xrefs to topics or non-DITA
> 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
> is
> to link to the map component/navigation artifact and not to the topic
> topicref ultimately links to or implies.
> That again avoids the need to have a specific form of addressing imply
> 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
> 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

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