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: DITA 1.3 Feature Request: Reference to Keys In non-Local Maps


A limitation in the 1.2 keyref mechanism is that there is no way to refer to
keys defined in a peer or external map. For example, given two peer root
maps that represent two related publications, it would be useful to be able
to create a cross reference to a topic used in the peer map by reference to
a key defined in that map.

In particular, without this feature, there is no way to create a
use-context-specific reference to a topic in another publication when that
topic is not itself included directly by the root map. (If the topic is
included in the root map, then a direct reference to the topicref is
unambiguous.)

Consider this set of maps, representing a publication organized into two
maps and a topic:

Publication A:

Pub-a.ditamap:

<map>
  <mapref href="submap01.ditamap"/>
</map>

submap01.ditamap:

<map>
  <topicref 
    keys="topic-a-01"
    id="tr-01" 
    href="topics/topic-12345.dita"/>
</map>

In the context of map Pub-a.ditamap, the key "topic-a-01" is bound to the
topic topic-12345.dita.

Now consider Publication B, which wants to include a topic that, in the
context of Publication B, refers to topic 12345 as used in the context of
Publication A:

Pub-b.ditamap:
<map>
  <topicref href="topics/topic-56789.dita"/>
</map>

Topic-56789.dita:

<topic id="t56789">
  <title>Points to Topic 12345 in Pub A</title>
  <body>
    <p><xref ???/></p>
  </body>
</topic>

In topic 56789, what can the xref use to point unambiguously to topic 12345
as used in the context of Publication A?

The answer is, nothing:

- An href to topic-12345.dita does not establish any use context for that
topic. If topic 12345 is used in more than one map, the reference is
absolutely ambiguous.

- An href to topicref pub-a-submap01.ditamap#tr-01 is likewise ambiguous
because the map submap01.ditamap could be used in multiple publications.

Even though the Publication A map defines a key for the topic, there is no
way in DITA 1.2 for publication B to point to that key because there is no
mechanism for establishing the key definition context for peer and external
scope references.

I want to capture this requirement in advance of developing a more
thought-out proposal.

The general requirement is that, for references to peer and external
resources, there be a way to establish the key definition context. This
could, for example, be a new attribute, keydef-context, whose value is a key
that resolves to a key definition that points to another map document as a
peer or external resource, specifying that that map document is the root map
of the key-defining map tree in which other keyrefs on the same element are
resolved., e.g., for the example xref above:

In map Pub-b.ditamap:

<keydef keys="pub-a"
 href="Pub-a.ditamap"
 scope="peer"
/>

In topic 567879:

<xref keydef-context="pub-a"
   keyref="topic-a-01"
   scope="peer"
 />

The keydef context for the key topic-a-01 could be pushed to map
Pub-b.ditamap:

<keydef keys="topic-a-01"
  keydef-context="pub-a"
  keyref="topic-a-01"
  scope="peer"
/>

Making the xref now:

<xref keyref="topic-a-01"/>

Note that in this second configuration, the xref should not specify @scope
because it can't know whether the key will resolve to a local or peer
resource.

An alternative syntax would be to extend the keyref syntax itself in some
way, perhaps allowing a pair of keys, where the first key of the pair
establishes the key definition context (through a key definition as above),
e.g.:

keyref="pub-a/topic-a-01"

Having written it, I kind of like that approach better. [It's not my intent
to do so here, but that syntax might also provide a sane way to establish
local key contexts as well, if we want to pursue that as well in DITA 1.3.]

In any case, we'll have to think through the details.

But without this feature, it is currently impossible to have unambiguous
publication-to-publication references when the target publication is
composed of two or more maps.

Cheers,

E. 

----
Eliot Kimber | Senior Solutions Architect | Really Strategies, Inc.
email:  ekimber@reallysi.com <mailto:ekimber@reallysi.com>
office: 610.631.6770 | cell: 512.554.9368
2570 Boulevard of the Generals | Suite 213 | Audubon, PA 19403
www.reallysi.com <http://www.reallysi.com>  | http://blog.reallysi.com
<http://blog.reallysi.com> | www.rsuitecms.com <http://www.rsuitecms.com> 



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