OASIS Darwin Information Typing Architecture (DITA) TC

Before we get too deep into a discussion of keyref and my indirection 
proposal I want to make sure that we have clear definition of the use 
cases and requirements because I strongly suspect that there are both 
distinct requirements at work and a not necessarily crisp description of 
all the relevant use cases.

Here's what I think the primary use cases are that are addressed by some 
form of indirection or "dynamic" resolution:

1. Referencing an ultimate target by initial reference to an indirector 
whose own address is invariant (that is, protecting the initial 
reference from changes in the location of the ultimate target) where the 
form of initial address uses the same syntax and semantics as a direct 
reference to the ultimate target would use.

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:

   - "variables" where the variable name is invariant but the set of 
specific values used is determine based on properties set for the 
context in which the variable reference occurs, such as the national 
language or product identifier.

   - 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.

3. Referencing an ultimate target by reference to an invariant address 
that is resolved to different targets based on resolution-time 
parameters provided to the resolution processor. For example references 
to graphics where the specific graphic object is determined based on the 
target output format (HTML or PDF) and possibly other parameters 
(national language, etc.).

4. Referencing a reference topic "implicitly" simply by uttering a value 
of its metadata or content (e.g., title, short title, navtitle, etc.). 
The resolution is resolved either at processing time based on the actual 
content of the topics involved and not on some form of indirect address 
or database lookup.

Note the key differences between these use cases:

Case 1. is just about addressing and is completely static--there is no 
special resolution-time processing other than simply doing the re-direction.

Case 2. is resolved based on *static* properties determined by the 
content and metadata in the referencing context (e.g., by values set in 
a particular map). Returning the correct value requires that the 
resolution processor know where to look for a particular kind of value 
(that is, which database or which file) and which local properties to 
use to complete the lookup.

Case 3. is resolved based on *dynamic* properties specified at 
resolution time. Like case 2, the resolving system has to know where and 
how to look up a particular value (that is, which database or which file).

Case 4. is resolved based on processing time string matches and does not 
otherwise involve any sort separate database lookup.

I will try to expand on each of these use cases as time permits. In 
particular, I think that case 2 is important and I don't think it's 
really addressed by the current keyref proposal and it is certainly not 
addressed by my indirection proposal (because that's not the point of 
that proposal).

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

W. Eliot Kimber wrote:

[NOTE: this series of posts is an attempt to fully understand the 
requirements surrounding the various indirection proposals in order to 
then evaluate the proposed designs in terms of how well they satisfy the 
requirements at hand.]

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

The are several different use cases that demonstrate this requirement 
but one of the key ones is what I call the "variable" use case.

The general requirement is that you need to create references in the 
content to values that will vary under different circumstances but that 
are invariant for a given processing instance.

The typical example of a variable is "product name", where you have 
content that is common to a number of products but you need refer to the 
specific product name that the content is being published for.

One general approach to addressing this requirement is to define in your 
document type a "variable" mechanism that has two components:

1. Markup for defining name/value pairs (variables) and a way to include 
variable definition sets into documents, e.g.:

Document "variables.xml":






2. References to variables:

   
The 

A further refinement to this approach that I have used in the past is to 
have some or all metadata elements also act as variables where the 
metadata element name (or other predictable and unique property) is the 
variable name. For example, if in your metadata design you already 
provide a "productname" element, then there's no reason to have to 
define a separate variable with the same value.

In addition, this mechanism is defined to apply not just to a single 
syntactic document but to an entire *compound* document such as you 
would create using XInclude or a similar mechanism (in DITA, maps), such 
that the variables included by the top-level document then establish the 
values used by references within any component document.

For example, if I have two different products I would expect to have two 
different top-level documents, one for each product, and each 
product-specific document would pull in a different set of variable 
declarations that use the same names. In this way, the common content 
will reflect the intended product automatically.

In DITA terms this would naturally translate into binding the variable 
definitions to maps such that the map context establishes the values for 
the variables that are referenced from within topics within the map 
context. This binds the variable values to the map. You would also 
normally define the rule that the highest-level definition of a variable 
takes precedence over any other (that is, the declarations referenced 
from the root document win).

Because the variables are static for a given top-level document, 
implementation is relatively easy. In XSLT terms, you just create a key 
table for looking up variable values and then use that key table to 
resolve all variable references.

This approach is similar to but somewhat different from that described 
in the keyref proposal. In particular:

- It provides a distinct set of element types for variables, whereas 
keyref is more generic (the key-based referencing is to topics which 
then, as a side effect, provides indirection to specific elements, which 
could then be used with, for example, conrefs to phrases that act as 
variables in the sense meant here).

- It allows the possibility of integrating existing metadata elements 
with the variables to allow metadata values to *act as* variables. This 
cannot be done with the keyref proposal (because there's no existing 
DITA-defined mechanism for using a metadata value within content).

Note, that I am not (yet) proposing a specific variable mechanism for 
DITA, simply describing one way that I've successfully addressed the 
requirement in the past in order to make the requirement clearer and to 
compare it with the keyref proposal.

Note too that this requirement (using variables by name, not by address) 
cannot be satisfied by my generic indirection proposal because 
references to variables are not references to elements by address but to 
variables by name in an application-defined variable name space. 
However, the inclusion of variable sets *is* via address and in that 
case, my indirection proposal would apply (because it applies to all 
uses of addressing regardless of semantic).

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

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:

To do blah, press the


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

Per fare il blah, premi il


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.:



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

W. Eliot Kimber wrote:

> 3. Referencing an ultimate target by reference to an invariant address 
> that is resolved to different targets based on resolution-time 
> parameters provided to the resolution processor. For example references 
> to graphics where the specific graphic object is determined based on the 
> target output format (HTML or PDF) and possibly other parameters 
> (national language, etc.).

This use case is different from use case 2 in that the selector used to 
determine the value a given name resolves to is provided at processing 
time rather than being a static property of the content itself.

The typical example is selecting a specific version of a graphic based 
on the rendition target. The graphic is referenced by some kind of 
logical name that then resolves to a specific rendering of the graphic 
based on run-time variables such as the rendition target (PDF for print, 
PDF for the Web, HTML for the Web, HTML for help, embedded help for a 
device) or other conditions (expert version vs new user version, 
instructor vs student, etc.)

Like the "logical name" mechanism described previously, the resolution 
is done by reference to some sort of external (to the document being 
processed) database that maps logical names to specific values based on 
specific properties specified at run time.

Of course, the two mechanisms could be combined, such that the database 
lookup is a function of both static properties at the point of reference 
(national language) and dynamic properties specified at run time 
(rendition target, audience, etc.).

The keyref proposal may be able to address the dynamic aspect of this 
requirement by taking advantage of DITA's generic conditional processing 
mechanism.

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