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
www.innodata-isogen.com
