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

Why do the part-1.intro and part2.intro keys have to be manually constructed by the information architect? Why can't they be implied by the presence of the scope?

It may leverage existing key capabilities, but it moves all the onus to the authors - for every case where they need to disambiguate their reference, they have to construct a new keydef.

When the information architect and the author are the same person, this will merely be troublesome and annoying. When they are different people, it creates a requirement loop across the roles.

Michael Priestley, Senior Technical Staff Member (STSM)
Lead IBM DITA Architect

From:        "Nitchie, Chris" <cnitchie@ptc.com>
To:        Michael Priestley/Toronto/IBM@IBMCA,
Cc:        "Helfinstine, David" <dhelfinstine@ptc.com>, "dita" <dita@lists.oasis-open.org>, "Eliot Kimber" <ekimber@reallysi.com>, "Nancy" <nancylph@gmail.com>
Date:        01/25/2012 03:20 PM
Subject:        RE: [dita] Proposal 13041 and Cross-Publication Linking

In the below example, there are three key names:

Part-1.intro - The intro to part 1
Part-2.intro - The intro to part 2
intro - The intro to whatever part I'm in right now.

Each part's map defines the other parts' keys using the cross-publication keyref syntax from 13041, and defines its own keys as well as the unqualified 'intro' key as a local resource, as normal.

The omnibus map provides definitions for each of the qualified keys that use local references, and then references each map as its own key scope so that unqualified 'intro' references go to the appropriate place for references in each map. Since key definitions in parent scopes override those in child scopes, the local cross-part references override the peer cross-part references from the lower-level maps.

 <title>Part 1</title>
 <keydef keys="Part-1.intro intro" scope="local" href="">  <keydef keys="Part-2.intro" scope="peer"
   format="ditamap" href="">  <!-- etc. -->

 <title>Part 2</title>
 <keydef keys="Part-1.intro" scope="peer"
   format="ditamap" href="">  <keydef keys="Part-2.intro intro" scope="local" href="">  <!-- etc. -->

 <keydef keys="Part-1.intro" href="">  <keydef keys="Part-2.intro" href="">  <mapref href="" keyscope="Part 1"/>
 <mapref href="" keyscope="Part 2"/>

I'm using well-qualified key names here instead of qualifying key references with a key scope. That leverages existing key capabilities without adding anything new, and still allows topic and map authors to solve this use case.

Now say Part 1 and Part 2 were authored separately, and when you combined them into the omnibus map, you wanted some references to 'intro' in Part 2 to point to Part 1's introduction instead of Part 2's. There is no way to solve this problem without modifying the reference. In the above, you'd change it to 'Part-2.intro.' If we somehow had a way to address a key scope, you'd *still* have to modify the reference so that it pointed to the 'Part-2' scope. Again, my way allows you to do this without adding anything new to the spec (aside from the items already under discussion).


From: Michael Priestley [
Sent: Wednesday, January 25, 2012 2:49 PM
To: Nitchie, Chris
Cc: Helfinstine, David; dita; Eliot Kimber; Nancy
Subject: RE: [dita] Proposal 13041 and Cross-Publication Linking

From your proposal:

The DITA 1.2 specification dictates that there be exactly one effective definition for a given key for all key references within a map structure (see "Effective key definitions" here). This is a severe limitation that prohibits some common use-cases, such as:

Omnibus publications that combine multiple standalone maps, each with their own set of key definitions.

Cases where a topic is reused at multiple locations in a map structure, but the behavior of links and/or text replacement for each use context must be different.

The omnibus publication case is the flipside of the cross-deliverable referencing. The same keyref must be resolvable as cross-deliverable in the separated case, or same-deliverable in the omnibus case.

From my message here:

        <topicref keys="a1" href=""
        <mapref processing-role="resource-only" href=""        <!--gets keys to allow a1.dita to reference b1.dita via keyref-->

        <topicref keys="b1" href=""

        Hey here's a cross ref: <xref keyref="b1"/> <!--resolves to b1.dita at authoring time-->

If we now add a requirement for scoping to this picture - that is, B.ditamap potentially has keys in conflict with A.ditamap keys - how can A1.dita's xref be adjusted in a way that it still builds normally in both the omnibus case and the separate deliverable case?

Michael Priestley, Senior Technical Staff Member (STSM)
Lead IBM DITA Architect

From:        "Nitchie, Chris" <cnitchie@ptc.com>
To:        Michael Priestley/Toronto/IBM@IBMCA, "Nancy" <nancylph@gmail.com>,
Cc:        "Helfinstine, David" <dhelfinstine@ptc.com>, "dita" <dita@lists.oasis-open.org>, "Eliot Kimber" <ekimber@reallysi.com>
Date:        01/25/2012 02:33 PM
Subject:        RE: [dita] Proposal 13041 and Cross-Publication Linking

They're not connected because they're two completely different use cases.
1.       Refer to a location in another publication via the map and key name from which the publication was generated, the resolution of which is processor-dependent.
2.       Have different key resolution behavior at different locations in a single map structure, the resolution of which is strictly controlled by the spec.
From: Michael Priestley [
Sent: Wednesday, January 25, 2012 2:20 PM
To: Nancy
Cc: Nitchie, Chris; Helfinstine, David; dita; Eliot Kimber
Subject: Re: [dita] Proposal 13041 and Cross-Publication Linking
Hi all,

My question is, why aren't the two more connected than they are?

If we can use map containment to distinguish between keys that we need to address, why can't we use map containment for scoping keys as well?

Or if we need a different scoping mechanism so that we can allow information architects to alternate between first-definition-wins and local-definition-wins in the keyref wars, then why can't that same scoping mechanism be used for cross-scope references?

If we need to be aware of both map containment and scope containment, that's two roughly equivalent trees of containment that will need to be preserved throughout any processing pipeline - can't we just make do with one?

I'm also assuming that either way we did it, the author would not need to code complex nested URIs - either way, they should be able to code simple two-part keyrefs:

For example, if we have either a nested scope or nested map structure - a map/scope contains b map/scope contains key x
       then x should be addressable in any of the following ways:
       keyref="b/x" finds the definition of x within b
       keyref="a/x" finds the first definition of x within a
       keyref="x" if the reference is from within b, finds the first definition of x within b; otherwise if the reference is from within a, finds the first definition of x from within a; otherwise finds the first definition of x in the whole keyspace (ie behaves normally)

Michael Priestley, Senior Technical Staff Member (STSM)
Lead IBM DITA Architect

From:        Nancy <nancylph@gmail.com>
To:        Eliot Kimber <ekimber@reallysi.com>,
Cc:        "Nitchie, Chris" <cnitchie@ptc.com>, Michael Priestley/Toronto/IBM@IBMCA, "Helfinstine, David" <dhelfinstine@ptc.com>, dita <dita@lists.oasis-open.org>
Date:        01/25/2012 01:40 PM
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)
> (
> <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]