[dita] Proposal 13041 and Cross-Publication Linking

["Nitchie, Chris" <cnitchie@ptc.com>]

Eliot, Michael,

In preparation for tomorrow's telcon, I spent some time going back over the cross-scope key reference discussions from August and September, thinking about how 13041 interacts with key scoping, and writing up a thorough description of why I thought cross-publication key referencing was a really bad idea. Somewhere during that process, though... I think I changed my mind. Eliot, tell me if I'm on the same page. Michael, let me know if this makes any sense. And I apologize if some of this is a bit pedantic; this was just my thought process.

Here's the quote from Eliot that clued me in to what he's going for (emphasis in the original) (http://lists.oasis-open.org/archives/dita/201109/msg00029.html):

<quote>
The author *of a topic* references some target by key. At the time they
author the reference to the key they can't know or care where the ultimate
target of the key might be in the content as authored or in the content as
rendered, for the simple reason that it is unknowable at authoring time.

If they are authoring in the context of a specific map then of course they
can know where the key resolves in the context of that map, but if they are
authoring the topic outside of a map context then they are simply stating
the requirement that there needs to be something at the end of the key in
whatever contexts that topic is used. But they cannot know all the possible
maps the topic might be used by in the future.

The author *of a map* that uses the topic has the responsibility of binding
the key to a resource. If the resource is in the same map, then no problem,
they just create a normal key reference and they're done.

But if the resource is *not* in the same map, *there is nothing they can do
today to indicate their intent to reference a resource in a different map*. 
</quote>

Ignore keys and key scopes and key spaces and all that stuff for a second. What's the correct way to code a reference to a specific location in a map that represents a separate publication? DITA 1.2 doesn't say, but I think it's this:

@format="ditamap"
@scope="peer"
@href="(map uri)#(branch ID)"

The current topic discussing the scope attribute in the 1.2 spec is both hard to understand ("Set scope to peer when the resource is part of the current set of content but is not accessible at build time") and a little bit weird ("An implementation may choose to open such resources in the same browser window to distinguish them from those with scope set to external"). But I think this formulation is reasonable. If not, maybe we need a new value for @scope, something like "sibling."

The big problem with cross-publication linking in any XML content system, not just DITA, is that the process of mapping an XML resource to its published URL depends on more variables than can be accounted for in a generic, one-size-fits-all way. Once the spec describes the appropriate way to encode a cross-publication reference (and again, I suggest the above), it must necessarily throw up its hands and say, "the processor does whatever it can to resolve this reference according to business rules and composition parameters and whatever other data it can get its hands on. Processors may not be able to resolve such references in all situations, and processing such references is not a requirement for conformance." You guys (Michael and Eliot) spent a lot of time last fall speculating about how hypothetical processors might solve the problem, but just for illustrative purposes, and not, I think, as proposals for the spec. I don't believe there's any way for the spec to prescribe a solution to this problem.

So let's take a key, "maintenance.intro". In one map, the maintenance manual is part of the publication, so the key definition is simple:

<keydef keys="maintenance.intro" href="maintenance/intro.dita"/>

In another map, the maintenance manual is its own publication. With any luck, the maintenance manual map has an ID on the topicref to intro.dita, so in those contexts you'd define the key like so:

<keydef keys="maintenance.intro" scope="peer"
  format="ditamap" href="maintenance.ditamap#intro"/>

This is sufficient information for any processor to try and resolve the reference. "I want to point to the 'intro' topic of the publication derived from maintenance.ditamap that applies for my current publishing context, however that's defined."

I think proposal 13041 essentially comes down to this: Given that the processing of peer references must be processor-dependent, you should be able to specify a key name for the above reference instead of a branch ID.

<keydef keys="maintenance.intro" scope="peer"
  format="ditamap" href="maintenance.ditamap#@intro"/>

(Note: I don't care what the URI structure ultimately is, the point is, it's a key, not an ID.)

The author's intent is clear. "Point to whatever content fulfills the role of 'intro' in the publication derived from 'maintance.ditamap' that applies for my current publishing context, however that's defined." The resolution is left up to the implementation. And topic authors are shielded from having to know anything about key scopes and usage contexts and all that stuff.

I'd prefer that we specify that processors should issue an error if the '@' syntax (or whatever) is used anywhere but on a peer-scoped references, and maybe even if it's used on anything but a resource-only key definition, as only map authors can know whether or not a given map is part of the same publication.

If my interpretation of the proposal is correct, count me as on board.

None of this, so far as I can tell, has anything to do with key scoping.


Chris Nitchie
Senior Software Engineer

T 734.352.2879   F 734.997.0201
E cnitchie@ptc.com

PTC.com