RE: [dita] ITEM: Cross-references to Topicheads and Implicit Title-only Topics

["Grosso, Paul" <pgrosso@ptc.com>]

After review, Jeff and I are generally okay with this,
but if we're planning to approve something at next week's
telcon, we need to be sure we know what we're approving.
In most cases, Eliot's email does do that, but not in all.

[Note, despite the subject--which suffers from legacy--this
proposal is just about cross-references to topicheads.  It
does not mention/address implicit title-only topics.]

More detailed "editorial" comments below (nothing technical). 

> -----Original Message-----
> From: Eliot Kimber [mailto:ekimber@reallysi.com] 
> Sent: Monday, 2009 May 04 18:02
> To: dita
> Subject: [dita] ITEM: Cross-references to Topicheads and 
> Implicit Title-only Topics 
> 
> 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.

We're okay with #1.

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

We're okay with #2.

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

We're okay with #3.

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

Since no specific change has been suggested, I'm assuming this
is just a comment in passing.  Unless in the future some specific
change is suggested, this is a no-op, and I'll assume any vote
next week will not include anything on this.

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

Another no-op comment.

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

We're okay with #6.

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

Another no-op comment.

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

We're okay with #8.

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

We're okay with #9.

I'm assuming there is no significance to #10 being missing.

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

We're okay with #11.

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

We're okay with the first #12.

I'm assuming there is no significance to having two #12's.

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

We're okay with the second #12.

paul