[oXygen-user] [ann] oXygen 11 beta

ekimber
Thu Sep 17 08:28:54 CDT 2009


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" <> 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:   <mailto:>
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> 




More information about the oXygen-user mailing list