[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]