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

[Michael Priestley <mpriestl@ca.ibm.com>]

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