Proposals 13004 and 13041: Proposed Reconciliation

[Eliot Kimber <ekimber@rsicms.com>]

In preparation for the DITA North America conference I prepared a set of
sample maps using Chris' scoped keys proposal augmented with a specific
meaning for scope="peer" on maprefs in order to test how Chris' proposal
would work for cross-deliverable addressing. My result was that it works
quite well, avoiding the need for any new addressing syntax specific to
cross-deliverable addressing.

My proposed extension is to define a specific meaning for @scope="peer" on
map references that specify a key scope per proposal 13004, such that the
peer map is treated as a distinct root map and a distinct key space that is
*not* included in the referencing map's key space. Key references qualified
with the scope name bound to the peer map are resolved in the context of the
peer key space. 

Note that you *must* have a scope on the map reference in order to be able
to address keys defined in the peer map. This is fine since the alternative
would be some new syntax for addressing the map explicitly. By using the
same scoping mechanism you have the advantage that the key references don't
know or care whether the referenced key is a local key or peer key.

For example, consider this map:

<map keyscope="map-a">
  <title>Map A (13004 version)</title>
  <mapref href="keydefs/map-a-keydefs-local.ditamap"
    scope="local"
    processing-role="resource-only"/>
  <!-- Include Map B's map as a peer and assign a keyscope to it. -->
  <mapref href="../map-b/map-b.ditamap"
    scope="peer" 
    keyscope="map-b"/>
  <!-- Navigation tree for map A: -->
  <topicref 
    keyref="topic-a-root">
    <topicref
      keyref="topic-a-01"/>
    <topicref
      keyref="topic-a-02"/>
  </topicref>
</map>

The map establishes the scope "map-a" and within that scope has a map
reference with @scope="peer" to map "map-b", assigning it the scope name
"map-b".

Any topic used from Map A that is qualified with the scope "map-b" is then
explicitly a reference to a key defined in map B, e.g.:

<p>Cross reference to topic B-01: <xref
keyref="map-b.topic-b-01">B-01</xref></p>

In order to generate output with the key reference resolved to the
appropriate delivery-specific location for map B as rendered, you must use
some sort of two-pass process as described by Michael, e.g., by generating
literal maps that replace the original key definitions for Map B with key
definitions that bind the same key names to the topics as rendered.

I worked up examples by hand for this process using scoped keys and, by
propagating the scope names to the key definitions and key references, you
get a set of maps that can be processed normally using a 1.2 processor and
get working output where the cross-deliverable links work.

What I have not done is implemented the automatic generation of the
deliverable-specific maps: that will require some non-trivial coding against
the Toolkit and will probably require some help from Jarno to work out.

But I was pleased how well I was able to extend Chris' proposal to
accommodate cross-deliverable addressing. I proved at least to my
satisfaction that Chris' proposal does work: I worked up examples of using
the same maps and topics in different configurations and showed that the
same invariant scoped and unscoped key references would do the right thing
in all cases.

Thus, I would like to propose that my proposal 13041, cross-deliverable
addressing, be put on hold, replaced with additional language in 13004
specifying the exact meaning of @scope="peer" on map references with scopes.

If Chris and the TC are in agreement with this plan, I will add my name to
13004 and work with Chris to craft the necessary language.

My fully-worked examples are available from
https://github.com/drmacro/dita13-xpub-linking

Cheers,

Eliot

-- 
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/