OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.


Help: OASIS Mailing Lists Help | MarkMail Help

dita message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]

Subject: Re: [dita] Proposal 13041 and Cross-Publication Linking


Thank you for the extremely clear explication of cross-scope key referencing, and Eliot, thank you for your succinct explanation of your and Michael's difference of opinion on it. 

It appears to me that the only real connection/dependency between cross-scope keys and key scoping may be in the attribute name being used.  End users may - almost certainly will - be confused by attributes with such similar names, especially when  both can be used in relation to keys.  After all, I was, and I'm not a new end-user.

@scope already exists, and @keyscope is certainly descriptive, but we'll have to include this in our 'users need lots of support if we don't what them to throw up their hands and pick another technology' bucket, as part of our 1.3 work on reducing DITA barriers to entry.


On Wed, Jan 25, 2012 at 10:04 AM, Eliot Kimber <ekimber@reallysi.com> wrote:

I need to take more time to read your analysis more carefully, but I believe
that you have correctly divined my intent: the ability to address by key
something in another "publication" as authored, as represented by its root

As you say, how a given processor makes that work in rendered results is
necessarily processor specific.

Where Michael and I were arriving at in our discussion was that one could
define a purely key-based way of representing the processed result by
creating intermediate key sets that point not at the content as authored but
at the content as rendered. Whether these keys are generated or authored or
manipulated by hand in the middle of some production process is
immaterial--the point is that such keys can fully represent the relationship
between a given key reference and any particular rendered version of the
target resource. Thus they can serve as both a standard language for talking
about those relationships in an abstract processing context and can serve as
a literal interchange format so that two otherwise distinct processors could
collaborate on output production.

The only place where I think Michael and I differ is on the need for the
specific key-based fragment identifier syntax. I feel strongly that we need
it and I'm pleased that you seem to be arriving at the same conclusion.



On 1/24/12 6:54 PM, "Nitchie, Chris" <cnitchie@ptc.com> wrote:

> 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="" 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=""> >
> 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=""> >
> 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=""> >
> (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
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dita-unsubscribe@lists.oasis-open.org
> For additional commands, e-mail: dita-help@lists.oasis-open.org

Eliot Kimber
Senior Solutions Architect
"Bringing Strategy, Content, and Technology Together"
Main: 512.554.9368

To unsubscribe, e-mail: dita-unsubscribe@lists.oasis-open.org
For additional commands, e-mail: dita-help@lists.oasis-open.org

Nancy Harrison
Infobridge Solutions 

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]