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

[Eliot Kimber <ekimber@reallysi.com>]

On 3/28/09 1:37 PM, "Michael Priestley" <mpriestl@ca.ibm.com> wrote:

> Great write up, and thanks for doing the research. I for one would be
> interested in seeing the table you put together.

I will post it separately.

> One thing that makes me uncomfortable in this is the requirement to treat
> an xref to a topichead as being equivalent to an explicit request to chunk
> the topichead. That means for example that we get quite different output
> behavior depending on things that might be buried in content and under
> various sorts of conditions. In other words, we wouldn't know whether to
> chunk the topichead or not until we had parsed every piece of content, and
> doing something like conditionally processing an xref in or out (which is
> pretty common) would result in the topichead being chunked or not, which
> isn't an intuitive side-effect.

Good point. I think you're right: chunking should be determined entirely by
information in the map. Thus an xref to a non-chunking topichead would not
result in a chunk.

In light of this, I think that processors should *not* be allowed to do
chunking of topicheads by default, since that could lead to unexpected and
surprising behavior from two different output processors for the same input
data set. I think. Need to think about the practical implications of that
more, especially in the case where you want to share map components between
an HTML-specific map and a PDF-specific map and might naturally want
different chunking implications for topicheads. It would definitely be a
burden to have duplicate map structures that differed only in the chunk=
values on topicheads. But it may be that setting chunk= on the root map
element solves the problem--not sure I fully understand the defaulting
implications in that case.

>   And what happens with keyrefs, which might
> legitimately be pulling in just the text of the topichead and not want a
> link?

Removing the requirement for implicit chunking on xref should avoid this
ambiguity, yes?

> Speaking of keyrefs makes me wonder about the general practice of linking
> to a topicref as a way of linking to the resource the topicref points to.
> It's using the topicref as an indirection mechanism, which is fine when
> we're using keyref (because it's an explicit, designed redirection system
> - it always means "point to the thing this points to"), but this seems to
> be adding another level of indirection beyond keyref and I think it
> creates ambiguity (do I want to point to the thing - the nav point - or
> the thing it points to - the potentially generated header topic?).

> You've taken the chunk attribute to-content or to-nav values as way to
> disambiguate, but what if someone wants to do both? For example, someone
> is reusing a set of topics - so they organize the topics in a map, add
> their own headings to act as organizers for the new groupings, and
> generate both new navigation files and new header topics based on the new
> organization.
> 
> Keyref vs topicref-ref:
> 
> <keyword keyref="blat"/>
>         pointing to a topicref that points to a topic, becomes an xref to
> that topic
>         pointing to a topicref with no href, becomes just the text
>         pointing to a topichead that gets explicitly chunked out, becomes
> an xref to that topic
>         pointing a topichead that isn't explicitly chunked out - does it
> become the text, or a request to chunk?
> 
> Now how about:
> 
> <xref href="mymap.ditamap#blatid"/>
>         what is pointing to the topicref buying us that pointing by keyref
> wouldn't?
> 
> Net: could we simplify the problem by using keyref as our explicit
> redirector? 

Hmm--I'm not sure I fully understand your point about "doing both"--what
would it mean, practically, to have a link that points to both a navigation
artifact and a topic?

But in any case, I think you ask a good question: given the existence of
keyref does it make sense to allow an href= pointer to a topicref also do
indirection?

My initial answer is driven by a basic principle of hypertext systems: the
nature of the address should *never* affect the semantics of the link that
uses the address. This principle is explicit in the W3C's addressing and
linking standards (HTTP, URIs, etc.).

Or said another way: you should *always* be able to change one form of
address to another equivalent form and get the same processing result. This
is certainly the principle defined by the W3C for Web technologies (e.g., it
doesn't matter what form of URI you use to get to a resource, it's the same
resource and the processing result is always the same).

The indirection mechanism in DITA is not keyref but topicrefs. Pointing to a
topicref, by any means of address, is pointing to a topicref and the
semantics of that pointing are determined by the nature of the topicref and
the nature of the linking element, not the syntax chosen for addressing.

What keyref provides is a late-bound addressing mechanism that makes
pointers context dependent. That is a necessary feature of DITA (and
hyperdocument management systems in general) but it doesn't change the
semantics of the resulting relationships thereby created.

Note that DITA could have *always* allowed href= on elements that 1.2 is
allowing keyref= on (e.g., term) and the processing results would have been
the same as for keyref. DITA didn't because we realized that it was
impractical to have hard (early bound) links to things from topic content
(and implicitly or explicitly indicated that xrefs, while a practical
necessity, should be avoided for topic-to-topic links as much as possible in
the absence of late-bound addresses).

Keyref makes topic-to-topic links *practical* because of the late binding of
initial addresses to ultimate targets but it doesn't change the meaning of
the relationships established.

Thus, I would expect the processing result for xrefs to topicrefs to be the
same whether done via keyref or href=. Of course, having said that, I would
at the same time say "you should always use keyref" for the simple reason
that it's generally reliable and manageable whereas direct href= is not. But
we still have legacy content where href-based xrefs are made to topicheads
and topicrefs and therefore we have to define clearly what that means.

The following is my attempt to enumerate all the possible interesting
combinations of xref and topicref configuration. In this discussion
"topicref" means a topicref element that ultimately points to a topic,
"topichead" means a topicref element with only a navigation title, "textref"
means a topicref element with only a linktext element. Topicrefs that use
navtitle or linktext and topicheads that include linktext shouldn't change
the nature of the relationships established between xrefs and topics or
navigation artifacts.

1. xref to topicref: effective link is to the topic(s) ultimately addressed.

2. xref to topichead:
   - If chunk has no effective value, xref is to the navigation artifact
   - If chunk has the effective value "to-content", the xref is to the topic
implied by the topichead (per my proposal as modified below to require
explicit chunk= specification in this case)
   - If chunk has the value "to-navigation", the xref is to the navigation
artifact

3. xref to textref: This is effectively an error condition because there is
no explicit or implicit target for the xref, only text, and should be
treated the same as any other unresolvable pointer (e.g., an href= to a
missing resource or a keyref to an undefined key).

Given the above, I modify my proposal as follows:

Item (B) should now read:

B. For topicheads that are the targets of xrefs, if the chunk= value is
Unspecified or "to-navigation" the resulting link is to the navigation
artifact in the rendition, if any. If the chunk= value is "to-content" then
the xref is to the generated topic as defined in item (A).

My first item (C) is deleted (there should be no allowed processor-provided
default chunking of topicheads).

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>