OASIS Darwin Information Typing Architecture (DITA) TC

As DITA is as much about authoring as it is about delivery, DITA, unlike 
delivery-specific formats such as HTML or XSL-FO, must address the needs 
of managing links and addresses in an environment where the many 
components that make up a single logical unit of publication will have 
independent life cycles and often multiple versions in time that must be 
maintained and be processible in the appropriate context.

In particular, it is not practical, in the general case, to manage 
addresses as documents change over time without some form of indirect 
addressing or the imposition of severe (and otherwise unnecessary) 
constraints on how documents are stored and managed.

Currently, all DITA addresses are hard, direct pointers to their 
targets. Because DITA 1.x defines its own syntax and semantics for all 
addressing of DITA-defined components, it is not possible to 
unilaterally impose a existing indirection mechanism such as XIndirect 
(http://www.w3.org/TR/XIndirect/).

Proposal:

Define a DITA-specific address indirection element with the simple 
semantic of "indirect through me to my target" (cf., the 

Hi Eliot,

You'll want to take a close look at
the keyref proposal. It has the same use cases. Effectively it uses a topicref
as the indirect element.

Michael Priestley

IBM DITA Architect and Classification Schema PDT Lead

mpriestl@ca.ibm.com

http://dita.xml.org/blog/25





"W. Eliot Kimber"
<ekimber@innodata-isogen.com> 
03/19/2007 05:58 PM




To
"DITA TC list" <dita@lists.oasis-open.org>


cc



Subject
[dita] DITA 1.2 Feature Request: Support
for Indirect Addressing






As DITA is as much about authoring as it is about
delivery, DITA, unlike

delivery-specific formats such as HTML or XSL-FO, must address the needs

of managing links and addresses in an environment where the many

components that make up a single logical unit of publication will have

independent life cycles and often multiple versions in time that must be

maintained and be processible in the appropriate context.


In particular, it is not practical, in the general case, to manage

addresses as documents change over time without some form of indirect

addressing or the imposition of severe (and otherwise unnecessary)

constraints on how documents are stored and managed.


Currently, all DITA addresses are hard, direct pointers to their

targets. Because DITA 1.x defines its own syntax and semantics for all

addressing of DITA-defined components, it is not possible to

unilaterally impose a existing indirection mechanism such as XIndirect

(http://www.w3.org/TR/XIndirect/).


Proposal:


Define a DITA-specific address indirection element with the simple

semantic of "indirect through me to my target" (cf., the <indirect>

element in the XIndirect specification). Also provide a grouping

container for these indirections. Indirections and their containers

should be allowed as standalone documents (that is, they should not be

required to be contained by topics). In particular, it is essential to

the utility of indirection elements that they be stored in storage

objects that are distinct from either their targets or their addressees.


The use of an indirector does not affect the semantic of the link that

utters the initial address.


Indirectors may point to other indirectors (that is, there can be any

number of levels of indirection, although applications are free to

impose reasonable limits on how many levels they will resolve before

giving up.)


Indirector group and indirector elements should be specializable.


NOTE:


While this proposal is somewhat similar to the keyref proposal, this is

more general than keyref as it applies to all addresses regardless of

semantic. In addition, I think that keyref is (or should be) more about

referring to things by "logical name" rather than doing simple

indirection. That is, keyref implies some sort of resolution-time

selector based on parameters provided to processors, while this proposal

is a simple static address indirection mechanism.


I feel that further refinement of link management in the context of

versioned hyperdocuments is a content management issue that is outside

of DITA's scope to address.


Use case 1: Common Note


A common note exists that is conrefed from many many tasks.


In current DITA, every reference would be a hard link that is sensitive

to the specific location of the note element:


<note

conref="foo/bar/common/topics/topic_000234.xml#topic_000234/note_5654"/>


There could be 100s or 1000s of such references in a typical body of

topics for a complex system.


If the location of the note changes in any way, for example, the

containing document is moved or the note is moved to a different topic

or a later version of the note is created, all references to the note

must be updated if they want to point to the note in its new location

(and if the old version is destroyed or otherwise inaccessible [for

example, because your CMS only lets you get the latest version of

something via a link], then all references *must* be updated).


With an indirection mechanism, a single indirection element can be

created to act as a proxy for the note. All uses of the note then point

to the indirection. If the note subsequently changes location or a new

version is created, only that one indirection needs to be updated to

reflect the change--all uses of the indirection are unaffected:


Indirector element in document "note_00000124_latest.xml":


<?xml version="1.0"?>

<indirector id="note_000000001234"

href="foo/bar/common/topics/topic_000234.xml#topic_000234/note_5654"

format="dita" scope="local"

/>


In a topic that uses the note:


<note conref="foo/bar/proxies/note_00000124_latest.xml#note_000000001234/>


Authors who want to link irrevocably to time-specific versions of a

given element can either simply create a hard link as they would today

or create a new indirection that points to the specific version they want.


Use Case 2: Public Topics


An information provider creates a set of topics that are published as

DITA source for the express purpose of enabling the direct use of those

topics by third parties.


In order to protect users of those topics from changes in how those

topics are stored and managed by the information provider, the provider

creates a set of indirectors that act as a public "API" by which
third

parties can reliably and blindly address the published topics, e.g.:


Call this "http://www.example.com/topics/publictopics.xml":


<?xml version="1.0"?>

<indirectorset>

   <topicmeta>

     <!-- metadata that describes the topics proxied by these          indirectors, the publisher, etc. -->

   </topicmeta>

   <indirector id="topic-01" href="some opaque

location/fargle-bargle-12345.dita"/>

   <indirector id="topic-02" href="some opaque

location/fargle-bargle-A3CDF021.dita"/>

     ...

   <indirector id="topic-1000" href="some opaque

location/fargle-bargle-A3CDF021.dita"/>

</indirectorset>


These indirectors could then be used by one or maps also supplied by the

information supplier to provide convenient or useful organizations of

the published topics:


<map>

   <topichead navtitle="Some Cool Topics">

     <topicref

href="http://www.example.com/topics/publictopics.xml#topic-01"/>

     <topicref

href="http://www.example.com/topics/publictopics.xml#topic-02"/>

     <topicref

href="http://www.example.com/topics/publictopics.xml#topic-03"/>

   </topichead>

</map>



--

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