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

[Eliot Kimber <ekimber@reallysi.com>]

Here is Michael and my proposed resolution of this issue.

The key technical decisions are:

1. An xref via @href to a topicref is always a pointer to the topicref,
whether or not it has a @keys attribute.

2. Processors may treat the reference as a direct reference to the topicref
(navigation artifact) or to the topic pointed to or implied (via chunking)
by the topicref.

Given this clarification of the implications for href=, the following items
in the language reference should be updated as follows:


1. Under "Using keys and keyref"

1.A. Change: 
"During processing key references in topics and maps are resolved using key
definitions from maps." to:

"During processing key references in topics and maps are resolved using key
definitions from maps when key-defining topicrefs are addressed by key.

1.B After the paragraph starting "During processing", add the note:

Note: A key-defining topicref that also has an @id attribute and that is
pointed to by that ID, rather than by its key, does not necessarily act as
an indirection. In that case, processors may choose to treat as the
effective target of the ID reference either the topicref itself or the
ultimate target of the topicref.

2. Under the reference for "xref":

2.A Delete the last sentence of the first para "The href attribute on the
<xref> element provides the location of the target."

2.B Insert new paragraphs after the first paragraph:

Cross reference targets are addressed using either the href attribute,
keyref attribute, or both. If both keyref and href are specified, the keyref
is used unless the key reference cannot be resolved, in which case the href
is used. 

When the href is effective and the direct target is a topicref element, the
nominal target of the cross reference is the topicref element itself. In
that case processors may choose to treat either the topicref or its ultimate
target as the effective target of the cross reference.

NOTE: For example, in one delivery environment it might make most sense to
have the link be to an entry in a navigation view (table of contents) and in
another the link should be to the ultimate target topic (for example, in an
embedded help system that has no separate navigation view).

3. Under "The href attribute":

3.A Replace 3rd paragraph with this new 3rd and 4th paragraph [note change
of "file" to "document" from original 3rd para]:

In the case of a reference to a DITA resource, an href value consisting of a
URI with no fragment identifier resolves to the document element in the
referenced document. For the purposes of rendering, such as when a topicref
reference to a DITA document is used to render the document as HTML, this
means that all topics (and topic specializations) in the target document are
included in the reference. For the purpose of linking to topics or elements
within topics, the reference resolves to the first (or only) topic (or topic
specialization) in the document. For the purpose of linking to maps, the
reference resolves to the direct-child topicref elements of document element
(which must always be a map element).

In the case of a reference to a topicref within a map, the reference is
nominally to the topicref itself, even when the topicref defines keys.
Processors may choose to treat either the topicref or its ultimate target as
the effective target of the href.

4. Under "data":

- href= is allowed but the current spec doesn't say what it means to specify
href= on data. Data-about mentions that href= on data specifies the object
of the data. So clearly we need to say something to that effect under data.

5. data-about

I think the text under href, proposed above, is sufficient since it's not a
navigation relationship but an annotation relationship.

6. Under "image"

Change sentence in first para starting "An href attribute is required..."
to:

The image must point to a graphic object using either a keyref attribute, an
href attribute, or both, which allows the processor to bring the image into
the text flow.

[NOTE: here I'm assuming that the intent for keyref= on image was to enable
indirect reference to the image, not to make the image a navigation link to
some target.]

7. lq

Same as data-about--let href text serve, since use of href= on lq is
effectively deprecated by the existence of longquoteref

8. longquoteref

Add new second paragraph:

When the href is effective and the direct target is a topicref element, the
nominal target of the long quote reference is the topicref element itself.
In that case processors may choose to treat either the topicref or its
ultimate target as the effective target of the long quote reference.


9. longdescref

When the href is effective and the direct target is a topicref element, the
nominal target of the long description reference is the topicref element
itself. In that case processors may choose to treat either the topicref or
its ultimate target as the effective target of the long description
reference.


11. author 

Add new second paragraph:

When author specifies either or both of the keyref or href attributes, the
author element functions as a link to another DITA or non-DITA resource that
further describes or represents the author in some way. When the href is
effective and the direct target is a topicref element, the nominal target of
the author element is the topicref element itself. In that case processors
may choose to treat either the topicref or its ultimate target as the
effective target of the link.

12. publisher

Add new second paragraph:

When publisher specifies either or both of the keyref or href attributes,
the publisher element functions as a link to another DITA or non-DITA
resource that further describes or represents the publisher in some way.
When the href is effective and the direct target is a topicref element, the
nominal target of the publisher element is the topicref element itself. In
that case processors may choose to treat either the topicref or its ultimate
target as the effective target of the link.

12. source

Delete "; the href reference can be a string or a URL that points to it."
from first paragraph.

Add new second paragraph:

When source specifies either or both of the keyref or href attributes, the
source element functions as a link to another DITA or non-DITA resource that
is the source resource. When the href is effective and the direct target is
a topicref element, the nominal target of the source element is the topicref
element itself. In that case processors may choose to treat either the
topicref or its ultimate target as the effective source resource.



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