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: Issue for Future Consideration: No Direct Way To Address A Specific Use of A Topicref in Compound Map


[The purpose of this message is to register into the record a limitation in
DITA through DITA 1.3 for the purpose of future consideration. This is not a
proposal for DITA 1.3 nor is it a suggestion we need to address this issue
at this time. I just want to capture my thinking for later. One important
question, for example, is how common is the need for direct addressing of
specific uses of a given topic? I may be that this is very much an edge case
or it may be that there are important user communities for which this is an
essential requirement. I don't think we know at this time. I am simply
identifying the technical issue an making no representation about the need
for a solution.]

We have established that it is meaningful to have a cross reference to a
specific normal-processing-role topicref and that such a reference means
either "navigate to the topic referenced by this topicref" or "navigate to
this point in the navigation tree".

However, it is possible for a topicref to be included in a compound map
multiple times such that, with current addressing facilities, it is
impossible to unambiguously address a specific use of the topicref using a
direct address. It is possible address a specific use through the use of
multiple levels of key references, but that solution requires coordinated
creation and naming of keys among all the maps involved in a given compound
map, as explained below. That level of coordination is often either not
possible or not practical and thus cannot be seen as a complete solution,
although it does offer a workaround through DITA 1.3.

Consider root map R1 that includes two submaps, S1 and S2. Both of maps S1
and S2 include the submap map S3. Thus, all the topicrefs in map S3 occur
twice in the effective navigation tree built from the compound map.

Map R1:

<map>
  <title>Root map</title>
  <topichead navtitle="root">
   <mapref href="S1.ditamap"/>
   <mapref href="S2.ditamap"/>
   <topicref href="T2.dita"/>
  </topichead>
</map>

Map S1:

<map>
  <topichead navtitle="S1">
   <mapref href="S3.ditamap"/>
  </topichead>
</map>

Map S2:

<map>
  <topichead navtitle="S2">
   <mapref href="S3.ditamap"/>
  </topichead>
</map>

Map S3:

<map>
   <topicef id="tr-s3-01" href="T1.dita"/>
</map>

When map R1 is processed, the effective navigation tree is:

<topichead navtitle="root">
  <topichead navtitle="S1">
    <topicef id="tr-s3-01" href="T1.dita"/>
  </topichead>
  <topichead navtitle="S2">
    <topicef id="tr-s3-01" href="T1.dita"/>
  </topichead>
</topichead>

Note that the topicref "tr-s3-01" occurs twice.

Now consider topic T2, which wants to address the use of topic T1 in the
context of its use from map S2--there is no DITA-defined direct addressing
mechanism that would allow it.

It can be done by constructing keys such that, within the compound map, each
map defines a unique key that ultimately binds to its use of the topicref.

Within map S3, define a key that binds to the topicref, e.g.:

<map>
  <topicef 
    keys="map-S3.tr-s3-01"
    id="tr-s3-01" 
    href="T1.dita"/>
</map>

Within map S2 define a key that binds to the key in S3 and whose name will
be unique within the compound map (here ensured by including the map name
"S2" in the key name):

<map>
  <keydef 
    keys="S2.S3.tr-s3-01"
    keyref="S3.tr-s3-01"
  />
  <topichead navtitle="S2">
   <mapref href="S3.ditamap"/>
  </topichead>
</map>

Now a key reference to the key "S2.S3.tr-s3-01" can be understood to be a
reference to the use of topicref "tr-s3-01" in the context of map S2,
because of the chain of intermediate key references establishes the use
context unambiguously.

This works but requires that the intermediate keys be defined, which would
require either knowledge of the requirement to address a specific topicref
so that the necessary keys can be defined or automatic generation of such
keys for all topicrefs in a given map.

It also requires that processors maintain knowledge of the intermediate key
references when constructing the key space and use that knowledge when
resolving references to the keys. If a processor simply collapsed the key
"S2.S3.tr-s30-01" to the topic T1 and discarded knowledge of the
intermediate steps that got it there, then the reference becomes ambiguous
again because the reference has lost any use context information. The effect
in this case would simply be that the topic T1 has two keys bound to it, one
from each of S1 and S2, but those keys would no longer carry any information
about which use each key corresponds to. There is certainly nothing explicit
in the DITA 1.2 that would suggest that key processors should or must retain
knowledge of intermediate key references, although nothing that disallows it
either.

In addition, without the use of some sort of UUID it would be impossible, in
the general case, to define key names that are guaranteed to be unique
within a given compound map. Of course, in practice, content can be managed
so that names are reliably unique without resorting to true UUIDs, but only
within the scope of content developed within the same naming policy context,
which may be narrower than the scope of expected interchange of the content.

An alternative would, for example, be to provide a path-type syntax that
lets you address the path down the map tree explicitly. For example, given
keys defined only in the root map, one could have a key reference something
like:

  key01:key02:key03

Where "key01" would be the key for the highest ancestor mapref, "key02"
would be the child mapref, and "key03" would be the key of the topicref
being addressed.

Such references could either be used from other keys also defined in the
root map, effectively providing keys for specific uses of given topics, or
from keyrefs within topics where the set of maps available (and thus the
keys to name) is known or knowable to topic authors.

Because all the keys used in the hierarchical key reference can be defined
in the root map, the namespace can be managed by the root map author and
does not depend on universal uniqueness of keys provided by subordinate
maps.

Note that the scoped keys proposal as formulated as of 5 Feb 2012 does not
help because keys defined in subordinate key scopes are not visible from
ancestor scopes.

Thus, an item for post DITA 1.3 consideration is extending the key
addressing syntax to allow for this type of hierarchical addressing of
topicrefs within compound maps. Note that I am only thinking of the specific
case of addressing topicrefs. By staying purely in the domain of keys we
avoid any complexity stemming from addressing topics directly outside of any
map context.

Cheers,

E.

-- 
Eliot Kimber
Senior Solutions Architect
"Bringing Strategy, Content, and Technology Together"
Main: 512.554.9368
www.reallysi.com
www.rsuitecms.com



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