ITEM: Clarification of hrefs to topicrefs (Was: Cross-references toTopicheads and Implicit Title-only Topics)

[Eliot Kimber <ekimber@reallysi.com>]

Clarification of Hrefs to Topicrefs

The href attribute can be used from the following element types to
meaningfully refer to any element type (not exclusively topicrefs):

- <xref> (navigation link to an element, topic, topicref, or non-DITA
resource)
- <lq> (use is deprecated)
- <longquoteref> (source of the quotation (e.g., bibliographic record).
- <longdescref> (data that serves as the alternative text for a graphic or
object)
- <image> (the image data)
- <data> (effective metadata value)
- <data-about> (element to which metadata value applies)
- <author> (resource representing the author, e.g., a biographical entry)
- <publisher> (resource representing the publisher)
- <source> (original source of a topic)

Note that <link>, like <topicref>, can only point to whole topics,
topicrefs, or non-DITA resources, not elements within topics.

In the case where one of these elements points to a <topicref> element:

1. A reference 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.

Architectural Specification language to be determined through the ongoing
editorial activity.

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

[Editorial Note: makes it explicit that topicrefs are unconditional
indirections only when 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 the 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", add new third paragraph:

Use the href attribute to point to the effective value of the <data> element
(the object of the <data>). When the direct target of the href attribute is
a topicref element, processors may choose to treat either the topicref or
its ultimate target as the object of the <data> element.

5. data-about

[Editorial Comment: No text change required. 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.

[Editorial Comment: 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

[Editorial Comment: No text change required. I think the text under href,
proposed above, is sufficient since it's not a navigation relationship but
an annotation relationship. Also, use of href on lq is deprecated by
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.

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

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