You are correct that a given key definition may be overridden by an earlier definition in the map hierarchy, which is why you must establish a root map context before you can resolve any key. A key selector must reflect the *effective* key set, not the literal set of key definitions in a source map. For that reason, my suggestion to use the topicref hierarchy in the original map to guide a selector dialog is probably a bad idea upon reflection: it would be difficult, if not impossible, to generate a coherent tree of effective key definitions when they are pulled from many different maps. So forget that. In light of that analysis, the only ways I can think of to sensibly group keys are: 1. Group by map, such that for each active key definition, you group it under the map in which it is defined. In this context you could, possibly, reflect its grouping within the map, but that might be too hard to do. 2. Group alphabetically by key. This would provide useful groupings but wouldn't necessarily address the issue of potentially very long lists of keys in large key sets. 3. Group alphabetically by key target navigation title. This has the same long list potential problem but might be a more meaningful organization of targets--there's no requirement that keys reflect the target's details in any way (keys might be generated as some sort of UUID in some situations). 4. Group by the storage organization of the targets (that is, their file system or CMS organization). This may or may not provide a better tree less likely to have very long lists. Might not be a meaningful organization to authors. Not all CMS systems provide either a single storage organization or any storage organization (topics might be maintained as a flat pool of topics). So definitely a design challenge. Keys, because they are context-dependent, do introduce a conceptual challenge for authors in that they must understand that there is this contextual aspect. In many situations authors may not even understand that there are alternative bindings for keys they use. I suspect that in more complex environments the only way to enable sensible authoring is to provide significant customization around the management of and access to keys within the authoring system. For example, I saw an automotive authoring system that was not DITA-based but used the equivalent of DITA 1.2 keys to enable links to logical topics that would vary based on the context established in the process of setting up an authoring session for a particular tree of topics. In this case you selected the model, model year, and subsystem, which was the equivalent of establishing the root map and ditaval parameters. The system was effectively constructing a compound map dynamically reflecting a particular sub tree of a much larger taxonomy. Once you had established that context, only then could you get write access to topics, where the underlying CMS provided the context-specific binding of keys to context-specific targets. That is the equivalent of setting a root map and specific sub maps that then establishe the set of effective key definitions for the authoring session. In a generic system I think the closest you can get is simply providing a way to select the root map. But in a more customized environment you might implement exactly this sort of locked-down authoring access approach. But that would have to be customization because it will always be in terms of a business-specific, information-set-specific subject or organizational taxonomy (e.g., cars and car parts vs software and subsystems). The best Oxygen can do is provide appropriate APIs and extension points to enable easy-as-possible implementation of this sort of authoring environment. Cheers, E. On 9/17/09 3:17 AM, "Radu Coravu" <radu_coravu@sync.ro> wrote:
Hi Eliot,
See some answers below:
ekimber wrote:
I notice that the insert keyref dialog only shows the keys descending from the map selected in the map manager. I'm not sure what else you can do, but I think I would like to have the option of setting a "keyref resolution context" for an editing session or a project, which would normally be the root map I'm working under.
In the case of the DITA 1.2 spec, there is a root map and then a number of subordinate maps, each with its own set of key definitions specific to that map (e.g., one for the L&T module, one for the Machine Industry module, etc.).
If I'm editing an L&T topic I may still need to refer to a base element's key, but to do that, I have to explicitly select the master map, not the L&T map (which is where I probably am if I've either opened that initially or navigated to it from the main map before navigating to the topic I want to edit). Not a deal killer, but it means you have to have the map open in order to select keys from it (of course, the editor will have to have processed the map in any case to make keys available, even if it doesn't show it in the map manager).
I could see having the "default key context" be a project-level setting.
We considered the adopted solution (using the current edited DITA Map as the context) as the easiest way to choose/resolve keyrefs without the need for additional configuration on the user part. Indeed in the case of maps which refer other maps it is not always a good solution and requires sometimes opening the master map just so that you can reference a key from its context. We'll try to come up with a way of being able to specify the master-map.
On the other hand, in a large content set you might have 10s of thousands of keys organized into many submaps, so just presenting a flat list of keys will not always be practical. Might be useful to have a tree view of the keys reflecting their organization into maps and submaps. But in that scenario, I can see that showing only the keys in a specific map helps because it implicitly narrows the selection.
The decision to have a flat representation of the list of keys was made because, if my interpretation of the DITA 1.2 is correct, keys can overwrite each other. If the layout has a tree structure maybe the user chooses a key from a sub-map believing it hrefs a location and in fact the key is overwritten in a parent map to point to another location. What do you think about this situation?
In my map specializations I now include a generic "keyset" topicref that simply serves to organize sets of keys within a map. Might be useful to have a key selector reflect any topicref hierarchy and navigation titles used in the map, on the assumption that such groupings must be significant.
Yes, indeed a problem with the flat selector. Maybe a tree table with a third "Navtitle" column would be better.
From an integration API standpoint I would want to have a "key definition provider" extension point so that a CMS could, for example, provide keys without the need to first open a map, so one could edit a topic from the CMS and still create key-based links to things the CMS knows about--I didn't look to see if such an API is already provided.
We have no such thing in the API, yet but it will be discussed.
Cheers,
E.
---- Eliot
Regards, Radu
---- 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>