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

[Eliot Kimber <ekimber@rsicms.com>]

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/