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