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

["W. Eliot Kimber" <ekimber@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":
<?xml version="1.0"?>
<variable_set>
   <variable name="product-name">DitaMaster Pro</variable>
</variable_set>

<?xml version="1.0"?>
<mydoc>
   ...
   <variable_set_ref href="variables.xml"/>
   ...
</mydoc>

2. References to variables:

   <p>The <varref name="product-name"/> does everything...</p>

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