Re: [dita] Question about keyref with format="ditamap"

[Eliot Kimber <ekimber@contrext.com>]

The intent of that rule was to give you same thing you get if you xref to
a topicref by ID, that is, a reference to the topicref, not to the
resource the topicref references.

In an HTML environment where there is a table of contents that is the
literal reflection of the map as a navigation structure, it could make
sense to literally link to the HTML element in the ToC's HTML page and I
think that was the use case that was intended for direct-URL references to
topicrefs by ID.


More generally, it allows for a use/mention distinction for references to
topicrefs by keys: the normal keyref (@format="{format of target
resource}") gets you the resource ultimately addressed while a
format="ditamap" keyref gets you the topicref itself.

I had only considered the xref case, that is, making the key-based
equivalent of <xref href="somemap.ditamap#topicrefid" format="ditamap">.

This is obviously an edge case but I think it's necessary for completeness
of the addressing mechanism (that is, keyref and ID refs need to be
exactly equivalent such that any IDREF can be replaced by the equivalent
keyref and visa versa).

DITA doesn't (and can't) impose any particular semantics on the results of
addresses, it can only say what it is that you are addressing, in terms of
the DITA source as authored or the effective document as determined by the
DITA-defined rules for creating effective documents (conref, filtering).
How you use that thing for some purpose is up to you.

To respond to Robert's analysis: there is a fundamental problem with this
as the target of reference:

<topicref keys="mybranch"
href="whatever.ditamap#indirectReferenceToBranch" format="ditamap"/>


The referenced resource, whatever.ditamap, is referenced outside of any
use context: it is part of this map? Where is it bound to this map's
navigation structure? Etc. If I author a keyref-based xref to the key
"mybranch", what am I addressing?

If the purpose of the key reference is to refer to a specific topicref as
an object, then the above fails because there is no well-defined context,
in the current map, as to what is intended.

By contrast, a reference to a key is unambiguous: it can only mean the
topicref with that key in the context of the key space (key scope) that
defines the map.

That is, a direct URI xref to a topicref is wrong for exactly the same
reason that all other direct-URI xrefs to DITA resources are wrong: they
do not have any well-defined use context and thus are inherently ambiguous.

Cheers,

E.

—————
Eliot Kimber, Owner
Contrext, LLC
http://contrext.com




On 4/13/15, 4:17 PM, "Robert D Anderson" <robander@us.ibm.com> wrote:

>Hi,
>
>I have a question about some language that is in 1.2 and the 1.3 draft.
>Specifically, the wording is:
>
>
>     A key reference to a topicref element where the linking element
>specifies a format value of "ditamap" addresses the topicref element
>itself as though the topicref element had been addressed by ID. In
>particular, a topicref with a key reference to another topicref and a
>format value of "ditamap" is a use of the map branch rooted at the
>referenced topicref. [
>     1 
><http://docs.oasis-open.org/dita/v1.2/os/spec/archSpec/using_keys_to_addre
>ss_dita_elements.html>
>     ]
>
>
>In 1.2 and draft 1.3, it's hidden below an example, which is probably why
>I hadn't really thought much about it (it looks like part of the simple
>example). I'm guessing that's true of most other readers. However, it's
>actually setting out a normative rule that isn't mentioned anywhere else.
>
>I think the rule means that I can have the following map, and have the
>first two key references resolve differently:
><topicref keyref="mybranch"/>
><topicref keyref="mybranch" format="ditamap"/>
><topicref keys="mybranch" href="someParent.dita">
>  <topicref href="someChild.dita"/>
></topicref>
>
>The first topicref with keyref="mybranch" resolves as a reference to
>someParent.dita -- this is normal resolution for a key.
>
>As I understand the spec, the second topicref works differently because
>of the format="ditamap" attribute. It is "a use of the map branch rooted
>at the referenced topicref" -- almost the same as a conref of that branch
>(not quite the same, because metadata merging between the two is not
>straightforward).
>
>I don't like this for a few reasons. First - I had to read the language
>many times to work out what it is saying. Second - I don't find the use
>intuitive. It seems wrong to have @format on the reference trigger an
>entirely different resolution. Third - I think that if you want an
>indirect reference to an entire map branch, the following markup is more
>in line with other keys:
><topicref keyref="mybranch"/>
><topicref keys="mybranch"
>href="whatever.ditamap#indirectReferenceToBranch" format="ditamap"/>
>
> In that case, your key would resolve using normal key processing rules
>-- pulling in both @href and @format -- after which you end up with a
>reference to whatever map or whatever branch you need:
><topicref href="whatever.ditamap#indirectReferenceToBranch"
>format="ditamap"/>
>
>Once I worked out the meaning of the current rule, I checked with a
>couple other people, and it surprised them as well. We're not aware of
>any key processor that would support the resolution described here. So my
>questions are:
>1. Is my interpretation of the rule correct?
>2. If so, has anybody ever implemented it, or could anybody see
>implementing it?
>3. If no implementations, can we remove this language, since alternate
>markup can get the same result?
>
>Thanks -
>
>[1] 
>http://docs.oasis-open.org/dita/v1.2/os/spec/archSpec/using_keys_to_addres
>s_dita_elements.html
>
>Robert D Anderson
>IBM Authoring Tools Development
>Chief Architect, DITA Open Toolkit (http://www.dita-ot.org/)