ITEM: Cross-references to Topicheads and Implicit Title-only Topics

[Eliot Kimber <ekimber@reallysi.com>]

[NOTE: this was my first attempt to articulate the issues around xrefs to
topicheads. I am posting it for background and history. The subsequent
discussion has superseded much of this analysis but I think my summary of
the original issue and discussion in the TC conn calls might be useful--WEK]

This is my attempt to summarize the issue and, hopefully, allow us to come
to closure.

The original issue stemmed from the fact that DITA allows cross references
from topics to topicrefs within maps. However, through DITA 1.1 there is no
explicit language about what that means from a processing standpoint and
there are several possible cases which may have or should have or could have
different processing implications.

For cross references from topics to topicrefs I've identified the following
possible cases. In this discussion, by "topicref" I mean a topicref element
that points directly or indirectly to a topic. By "topichead" I mean a
topicref element that has only a navigation title. By "textref" I mean a
topicref element that contains only a <linktext> element.

1. xref via keyref to topicref. This is effectively a link to the resource
ultimately addressed per the semantics of the keyref mechanism and is
clearly defined by current 1.2 spec.

2. xref via keyref or href to textref. Textref's linktext value is used as
the effective linktext of the xref.

3. keyref from non-xref element (e.g., <term>) to textref. Textref's
linktext is used as the effective value of the referencing element.

4. keyref from non-xref element to topicref : linktext, if present, is used
as effective value of referencing element. Referencing element is also
rendered as a navigable link to the ultimate target topic.

5. xref via href or keyref to topichead. Expected behavior undefined in
current specs.

6. xref via href to topicref. Expected behavior undefined in current specs.

Cases 1 throught 4 are well defined in the current spec/proposals (the arch
spec and reference topics are not 100% complete in their descriptions but
the intent is well defined by the TC).

That leaves cases 5, and 6 to be clarified.

Case 5 is the one that I was focusing on initially. However, case 6 is also
interesting and may have the same general solution.

In addition, there is the general question of what, if anything, topicheads
should imply in renditions where there needs to be, or is expected to be, a
one-to-one correlation between navigation components (TOC entries) and
"body" components (titled divisions). In particular, in PDF (paged) output,
there is the expectation that every topichead that is not print="no" would
result in a corresponding division title in the resulting pages, not just
the TOC. This is not the case today with the PDF2 process. This behavior is
surprising to almost all users and leads to the practical need to create
title-only topics for what would otherwise only need to be topicheads.

While these seem like two separate issues (xrefs to topicheads and
topicheads in paged output) they are in fact two facets of the same problem
because in both cases there is at least a desire, if not a practical
requirement, for topicheads to imply the existence of topics for some uses
cases or output types.

One essential question is: when an author creates a cross reference to a
topicref or topichead, is their intent to create navigation to the rendered
navigation artifact (the TOC entry) or to the pointed to or implied by the
topicref?

While it would be meaningful in most, if not all, renditions to link to the
TOC entry produced from a topicref or topcihead, it's hard to imagine a case
in which you would want that instead of linking to the topic itself--there
is no common online delivery system or Web-delivered information set that
does that that I know of (not that I can claim authoritative knowledge on
the subject).

Therefore, it seems reasonable that the expected behavior would always be
for xrefs to topicrefs and topicheads to be to topics, not navigation
artifacts.

Given that, it appears to follow that an xref to a topichead *must* result
in a rendered topic that reflects the topichead's navigation title.

Note that this is not the same as saying "the topichead *generates* a
topic", only that the resulting rendition should behave as though the
topichead had been a reference to the equivalent topic. Whether or not this
is implemented by literally generating a DITA topic as an intermediate step
is an implementation detail.

At this point in the argument there should be general agreement that xrefs
to topicheads imply (virtual) topics.

Michael P. then pointed out that there are some practical problems that this
generation of virtual topics presents, in particular, the issue of
persistent addresses for generated topics. The problem holds for all
possible renditions that allow navigation to individual topics but Michael
raised it in the context of HTML output, where the problem is most obvious
and most likely to occur in practice.

The issue is simply this: having generated a topic as an HTML page and
published the result, someone may create a link from outside the published
data set to that generated topic. If, on republishing the data set, that
generated topic does not have the same address, the link will fail. This
would not (presumably) occur if the topic had been a literal topic in the
data as authored. [NOTE: DITA provides features that allow the rendered
result of processing a given map to have deterministic addresses for topics
as rendered. This is very important, for without such features, it would be
difficult or impossible to republish a map without sometimes or always
breaking links to the published artifacts made from outside the data itself.
Note that for the DITA-managed data itself, such persistence is not
necessary because links in the data as authored *must* be to the data as
authored, not as rendered.]

Two DITA features: chunk and copyto provide a mechanism by which map authors
can completely control the address details of the rendered result:

- chunk controls how a given topicref will be reflected in the rendered
result as a storage object ("document" in the language of the April 2007
architecture spec), when relevant to the output type (e.g., HTML but not
PDF).

- copyto defines the storage object identifier ("filename") of the rendered
result.

As currently written, these features apply only to topicrefs, not
topicheads.

Michael's suggestion was that these features could be used to handle the
topichead implicit topic case as well.

I agree.

I propose the following additions to the currently defined behavior of chunk
and copyto when used on topicheads (case 5 as outlined above):

A. The chunk value "to-content" requires that a title-only topic be
generated. The rendition address of the generated topic is determined as
defined for copyto. If copyto attribute is not specified and the topichead
has no id= attribute, the address of the generated topic is not required to
be predictable or consistent across rendition instances.

B. For topicheads that are the targets of xrefs, if the chunk= value is
"to-navigation" the resulting link is to the navigation artifact in the
rendition (e.g., TOC entry). If the chunk= value is "to-content" then the
xref is to the generated topic as defined in item (A). If a topichead is the
target of an xref and does not specify chunk=, it is processed as though the
chunk value "to-content" had been specified.

The meaning of "select-*" values is as specified for topicref and generated
topics should produce a result indistinguishable from replacing the
topichead with a topicref to a title-only topic.

For case 6, xref to topicref, I propose the following:

C. As for (B) above, if the chunk= value is "to-navigation", the xref is to
the navigation artifact in the rendition. If the value is "to-content" the
xref is to the target topic (i.e., same behavior as using a keyref to point
to the same topicref). If chunk= is unspecified, behavior should be as for
"to-content".


----
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>