Re: [dita] Cross-Deliverable Linking: Requires a-priori knowledge of which maps are root maps

[Eliot Kimber <ekimber@rsicms.com>]

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

Cheers,

E. 

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"
>   href="topics/has-a-figure.dita"
> />
> 
> 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="../map-b/map-b.ditamap"/>
> 
> <keydef keys="figure-containing-topic"
>  keyref="map-b::some-map-b-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).
> 
> Cheers,
> 
> E.
> 
> 
> 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:
>> 
>> [{keyspace-name}::]{keyname}[/{elementId}]
>> 
>> 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:
>> 
>> 
>> <map>
>>  ...
>> <!-- Peer reference to another root map (key space): -->
>> 
>> <mapref scope="peer"
>>    keys="map-b"
>>    href="../map-b/map-b.ditamap"
>> />
>> 
>> <!-- Local key bound to key in Map B: -->
>> 
>> <keydef keys="local-key-01"
>>    keyref="map-b::topic-b-01"
>> />
>> ...
>> </map>
>> 
>> 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.
>> 
>> Cheers,
>> 
>> E.
>> 
>> 
>> 
> 
> --
> Eliot Kimber
> Senior Solutions Architect, RSI Content Solutions
> "Bringing Strategy, Content, and Technology Together"
> Main: 512.554.9368
> www.rsicms.com
> www.rsuitecms.com
> Book: DITA For Practitioners, from XML Press,
> http://xmlpress.net/publications/dita/practitioners-1/
> 

-- 
Eliot Kimber
Senior Solutions Architect, RSI Content Solutions
"Bringing Strategy, Content, and Technology Together"
Main: 512.554.9368
www.rsicms.com
www.rsuitecms.com
Book: DITA For Practitioners, from XML Press,
http://xmlpress.net/publications/dita/practitioners-1/