OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.

 


Help: OASIS Mailing Lists Help | MarkMail Help

dita message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]


Subject: Proposal 13001: Same Topic Reference and Conrefs and Scoped Keys


Proposal 13001 makes this statement:

"Note that there is a processing ambiguity for same topic references which
comes to light with this proposal that the previous DITA Specifications
did not address for same topic references (or a more general case when
more than one topic exists in one file). That is conrefs pointing to
content that has embedded references in them. These could be xrefs or
other conrefs in these that have same topic syntax in them.

 …

As mentioned in the Stage 2 proposal, this ambiguity is not brought on by
this proposal."


It may or may not be true that this proposal doesn’t introduce the
ambiguity but it definitely brings the issue into the light. However, the
proposal does not attempt to resolve the ambiguity.

I think we must decide what the correct behavior is, because not just the
“same topic” reference but also scoped keys present a potential challenge,
and as in all cases of addressing behavior, there must be exactly one
right answer to what a given address addresses.

When a conreffed component includes an xref within it, it raises the
question of what that xref addresses. I think there are four interesting
cases for a conref containing an xref:

1. An xref that uses a direct URI reference to its target where the URI
consists of more than just a fragment identifier, e.g.
“../../common/topic-01.dita#topic-01/p2". In this case the only possible
correct behavior is that the URI is resolved relative to the location of
the xref *as authored* and not in any referencing context it might be used
in. If the URI is absolute then of course there is only one thing it can
resolve to. If the URI is relative, it is only sensible to resolve it in
its original context, since that’s the only context that correct
resolution can be assured in the general case. I think that this would be
very authoring practice and should be avoided entirely. The existence of
keys, and especially scoped keys, should remove any need for this type of
linking.

2. An xref that uses a URI reference that is only a fragment identifier
with an explicit topic ID, e.g. “#topic-01/p2”.  As in case (1), the only
reliable resolution is within the context of the xref as authored, because
that’s the only context in which there is guaranteed to be a topic with
the id “topic-01” (assuming that the xref is resolvable as authored, which
is the only case we can usefully consider). Again, I would consider this
very bad practice.

3. An xref that uses a key reference. In this case, for global keys, there
is only one possible resolution target regardless of use context. For
scoped keys, there is potential ambiguity as different use contexts may be
in different key scopes. In the case scoped keys I think it makes sense,
and would be the expected behavior, to resolve the key relative to the
scope of the reference, not the scope as authored. Any other behavior
would seriously erode the value of scoped keys. This behavior is also
consistent with the general intent of scoped keys whereby the same topic
used in two different scopes may have its key-based links resolve to
different targets based on the scope details.

4. An xref that uses a URI reference consisting of only a fragment
identifier with the “same topic” topic ID, e.g. “#./p2”. In this case, as
for key references, I think it makes sense that the reference would be
resolved in the referencing context.

In both of cases (3) and (4), all xref resolution must be done after any
conref processing, so that you can, for example, have a reference in one
conreffed element resolve to an element contained within another conreffed
element by using the same-topic topic ID or key ref that happens to
resolve to something also brought in by conref. This does come at the cost
of potential resolution failure if the author fails to conref the targets
required by other conreffed elements, but I think that is unavoidable in
this kind of late-bound addressing feature.

With this approach, there is no ambiguity about what the results of any
address will be in the face of use via conref. The only real potential
ambiguity, in terms of possible user expectation, is case (2) and both
cases (1) and (2) are, I would submit, are pathological cases that no sane
DITA user should ever do.

Cases (3) and (4) are completely unambiguous and produce the results users
will I think expect, namely that keys and “same topic” will resolve in the
using context, not the original context.

For conrefs, the implications for cases (1) and (2) are the same: the
conref must be resolved in the context in which the referenced element is
authored, not its use context. Any other behavior is madness.

For cases (3) and (4) I think it makes sense to apply the same rules as
for xref, namely references are resolved relative to the referencing
context. This rule implies that con refs must be resolved from the initial
reference through any subsequent references because otherwise you don’t
have a map or topic context within which to resolve keys or same-topic
references. 

Cheers,

Eliot

-- 
Eliot Kimber
Senior Solutions Architect
"Bringing Strategy, Content, and Technology Together"
Main: 512.554.9368
www.reallysi.com
www.rsuitecms.com




[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]