Re: [dita] Indirection, Keyref, and "Logical Name Reference" Requirements

["W. Eliot Kimber" <ekimber@innodata-isogen.com>]

W. Eliot Kimber wrote:

> 2. Referencing an ultimate target by reference to an invariant "logical 
> name" that is resolved to a specific target or targets based on 
> properties statically determined by the context of the reference, such 
> as audience, national language, etc. Typical specific use cases here 
> include:

>   - mentions of things that will vary based on things like the national 
> language for which the product being documented is localized, a typical 
> example being the descriptions of keys on a mobile phone keyboard. The 
> logical key name is invariant but the specific key name and graphic will 
> vary and can be statically stored in a separate data set or data base.

This use case is a little different from the variable case. For 
variables, the value resolved is static and invariant given a specific 
set of variable definitions. (This is also how keyref would work.)

However, there is another case where the values need to vary based on 
*static* properties in effect for the reference, what I call the 
"logical name" use case. (I stress static because there is yet another 
use cases where the properties are dynamic in that they are specified at 
rendition time rather than being in the data itself.)

For example, in a manual for a device that has some sort of keypad with 
labeled keys (e.g., a printer's control panel, a mobile phone keyboard, 
etc.), the function of a given button is invariant but the name and 
graphic for the button will likely vary for different national languages 
or different product variants.

In your content as authored you'd like to refer to the button by an 
invariant "logical name" that gets resolved to the appropriate specific 
name and graphic at processing time based on the local language of the 
content. [Note: this example uses national language as the variable 
local property but the requirement is not limited to just national 
language.]

For example, I might author my content in English originally:

<p xml:lang="en">To do blah, press the
<keylabel logical-name="blah"/> button.</p>

When the content is localized, the keylabel element doesn't change:

<p xml:lang="it">Per fare il blah, premi il
<keylabel logical-name="blah"/> tasto.</p>

The various values for the "blah" button are held in an 
application-specific database of some sort, either a literal database or 
some sort of XML markup that binds the logical name to various 
translations, e.g.:

<logicalname name="blah">
   <default_value>blah</default_value>
   <translation xml:lang="it">blah-o</translation>
   <translation xml:lang="fr">le blah</translation>
</logicalname>

You get the idea.

Output processors then use the database to resolve a logical name 
reference to a language-specific version based on the active national 
language at the point of reference. Processors have to know where the 
database is and how to use it--the database itself is not referenced by 
the input document in any way, it's a component of the processing 
application (somewhat analogous to the ditaval file use by the Open 
Toolkit today).

This is similar to the previously-described variable mechanism but adds 
the functionality of using reference-context properties to resolve to 
one of a set of possible values.

In addition, at least as I've implemented it in the past, the details of 
the references and the targets were very application specific, where 
there might be a good bit of intelligence in the reference resolution 
and there might be different kinds of references and databases for 
different kinds of things (keyboard keys, generic graphics, message 
strings, etc.).

Note that the keyref proposal does not directly address this use case 
because there is no generic mechanism in DITA for doing this type of 
property-based selection based on properties in effect at the point of 
reference. I believe that this use case would require an entirely new 
proposal. I also observe that such a mechanism would, necessarily, 
subsume much of the functionality provided by the keyref proposal.

The requirement could be somewhat addressed under certain circumstances 
by using keyref or my previously described variable mechanism by having, 
for example, a different map for each localization of a given logical 
document. However, it would *not* work for the case where you have a map 
that includes topics in different national languages (for example, you 
publish procedures where the different language versions of each step 
are presented together). It is this requirement to be able to handle 
different resolutions of the same name within the content of the same 
compound document that requires the use of a separate database rather 
than a simple variable definition mechanism.

Therefore, a simple name-to-value indirection mechanism is not 
sufficient to satisfy the general case outlined here.

Cheers,

Eliot

-- 
W. Eliot Kimber
Professional Services
Innodata Isogen
8500 N. Mopac, Suite 402
Austin, TX 78759
(214) 954-5198

ekimber@innodata-isogen.com
www.innodata-isogen.com