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: Re: [dita] Cross-Deliverable Linking: Requires a-priori knowledge of which maps are root maps


As the scoped key proposal is currently designed, a key reference is resolved by finding the outermost scope containing a definition for that key, in the parentage of the scope containing the reference. So if a key is defined in both the root 'global' scope as well as the current scope, the 'global' definition takes precedence (thus allowing 'using' maps to override keys in 'used' maps). So I don't think this is a problem, though I'm still digesting - with some difficulty - the idea of qualified keyrefs. It puts the burden on topic authors to understand the logical structure of the publication(s) that use a topic containing such a keyref, and it requires all contexts for that topic to have - or fake - a similar logical structure.


On Mar 24, 2013, at 1:36 PM, Eliot Kimber <ekimber@rsicms.com> wrote:

I just realized that if we have key scopes and the ability to address scopes
by name, then if the implication of scopes is that unqualified keyrefs
within a scope refer to keys within that scope, then we will need a way to
refer to the root (global) scope, otherwise there would be no way to refer
to global-scope keys from inside a scope.

In the context of my proposed syntax this could be something like:

<xref keyref="!global::some-key-name"/>

Where "!" signals a keyword rather than key name bound to a key space (scope
or peer root map).



On 3/23/13 9:54 AM, "Eliot Kimber" <ekimber@rsicms.com> wrote:

I forgot to describe the addressing details for references to elements
within topics. My analysis is that cross-deliverable key references doesn't
really change the nature of the problem or the solution for key-based
references to elements within topics.

My analysis:

Consider the case of linking to a <fig> via key: you would declare a key for
the topic that contains the <fig> and then specify the <fig> ID as part of
the keyref, e.g.:

In the map:

<keydef keys="figure-containing-topic"

In the referencing topic:

<p>See <xref keyref="figure-containing-topic/fig-01"/> ...</p>

Where "fig-01" is the ID of the <fig> element.

A side effect of this syntax is that all topics bound to the key
"figure-containing-topic" need to have an element with the ID "fig-01".

The implication for cross-deliverable addressing is the same: if I want to
link to the <fig> in a peer deliverable, the peer topic must also provide an
element with the ID "fig-01", e.g.:

<mapref keys="map-b" href=""/>

<keydef keys="figure-containing-topic"

The keyref from the xref above is the same, only now it resolves to the
topic with the key "some-map-b-topic" as defined in Map B's keydefs.

This is, I think, a problem, but not one we need to address in 1.3 (although
I did submit a proposal for doing element ID indirection, but withdrew it in
the face of complexity concerns).

Because in 1.2 we require coordination of IDs across topics that might be
used in different maps but bound to the same key I don't think that, in
practice, having to coordinate across peer deliverables changes the problem
any in practice: in most cases the peers are still going to be managed more
or less together. Also, if it's the case, as for the DITA spec, that the
cross-deliverable linking is only one option, with the content also being
delivered as a single deliverable, then the problem becomes the same as in
1.2 and again no new solution is required (or rather, our assessment that we
can do without a solution in practice continues to hold).



On 3/23/13 7:39 AM, "Eliot Kimber" <ekimber@rsicms.com> wrote:

I agree with Chris that a solution for referencing keys within scopes needs
to be coordinated with any keyspace-to-keyspace solution.

A key scope is really just a key space that is explicitly related to another
key space, which means that it's fundamentally no different from a
root-map-defined key space, it just has a known relationship to other key
spaces (it's ancestor key spaces and descendant key spaces) whereas a
root-map-defined keyspace has no known relationship to any other key spaces
(other than any descendant key scopes it might have).

So I think we have a common requirement for a new key reference syntax that
lets you specify the key space and key together, whether that key space is a
peer key space or a "scope" defined in the same root map as the reference.

As to Robert's concern about the meaning of scope="peer" on a mapref--if we
have this two-level key reference syntax, then I think we can say clearly:

"maps referenced as peers provide keys that may be referenced by a two-part
key reference. The keys within peer maps *do not* contribute to the key
space of the referencing map."

That is, you cannot directly reference a key in a peer map--you must address
both the map (key space) and the key together. To have a local key reference
that gets to a peer resource you must have two levels of key definition: one
for the local key that then provides the keyspace-specific reference to the
peer key.

I think that is consistent with Robert's understanding of our intent for the
meaning of peer and with the way current processors do or should process
peer maps.

For argument's sake and for my DITA NA demo I'm going to propose the syntax:


As the syntax for key references, where "keyspace-name" is either a key
bound to a peer-scope mapref or the name of a defined key scope (however
that works out).

I've chosen to use "::" as the separator as being analogous to the axis/term
separator in XPath: the keyspace-name establishes the context ("axis") that
the specified key is resolved in. I can't think of any other separator that
wouldn't cause potential confusion (e.g., "/", ".", "#", "%", etc.) or that
isn't common to all keyboards (e.g, "^").

Thus, to refer to a key in another map, you would have something like this:

<!-- Peer reference to another root map (key space): -->

<mapref scope="peer"

<!-- Local key bound to key in Map B: -->

<keydef keys="local-key-01"

Here a reference to the key "local-key-01" gets resolved to the key
"topic-b-01" as defined in map map-b.ditamap.

Likewise, from an xref you could address the topic in map B directly if that
was appropriate:

<xref keyref="map-b::topic-b-01"/>

Which is the author's way of saying "I know Map B will (or should) always
exist and I mean for this reference to unalterably be to Map B and nothing
else. There are times when that's what you want.

For the purposes of my demo for DITA NA I will use this proposed syntax, but
I'm not suggesting it's either the best answer or my most considered
suggestion, it's just what I've thought of at the moment.



Eliot Kimber
Senior Solutions Architect, RSI Content Solutions
"Bringing Strategy, Content, and Technology Together"
Main: 512.554.9368
Book: DITA For Practitioners, from XML Press,

Eliot Kimber
Senior Solutions Architect, RSI Content Solutions
"Bringing Strategy, Content, and Technology Together"
Main: 512.554.9368
Book: DITA For Practitioners, from XML Press,

To unsubscribe from this mail list, you must leave the OASIS TC that
generates this mail.  Follow this link to all your TCs in OASIS at:

Chris Nitchie
Oberon Technologies, Inc.
2640 Wildwood Trail
Saline, MI 48176
Main: 734.666.0400
Direct: 734.330.2978

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