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


Chris wrote:

> Thanks for this. In this example, keyspace addressing works, and is
> (relatively) simple, because the scope boundaries correlate cleanly
> to the publication’s structure, and that structure is constant over
> time. Here’s your sample topic:

>  
> <topic id="other"
>         <title>Other stuff</title>
>         <body><ul>
>                 <li><xref keyref="part1/intro"/></li>
>                 <li><xref keyref="intro"/></li>
>         </ul></body>
> </topic>

>
> There are a couple of assumptions implied here:
>  
> 1.       This topic will always be used in publications that can
> logically be subdivided into parts.


Rather: the topic will always be used in a publication that has two key definitions for "intro" - one with a keyscope, and one either without one or in the same keyscope as the topic.

> 2.       Those parts will have a consistent set of logical names
> (key scope names).


Rather: there is at least one key scope defined - for part1

> 3.       The topic will always be used in a map that declares key scopes.

Yes, but potentially only one

> 4.       The topic is not part of Part 1.

I think this is correct - but not a huge problem. It means you would need to pull the topic into part 1 within its own keyscope. You'd also want to provide a keydef for "intro" (the second xref's target) in the same scope.

> My concern is that these assumptions can’t always be made, and the
> lack of any one will require map authors to do more work.

>  
> 1.       If the topic is used in a map where there are no ‘part’
> boundaries, or where the parts of the initial publication are
> reorganized and recombined in new ways, the map author is going to
> have to do a lot of work to ensure that the key scopes are
> configured correctly, whereas if each cross-scope reference used a
> uniquely qualified name, that’s not an issue.

> 2.       If the topic is used in some map where there is no ‘part1’
> key scope, or where some other name is performing the role that this
> topic expects to be played by the name ‘part1’, then the map author
> is going to need some way to provide multiple names for a given key space.

> 3.       If this topic is used in the a standalone, simple map that
> doesn’t subdivide into key scopes, then that map is going to have to
> add scopes to accommodate this topic.

> 4.       If the topic is used in a Part 1 map, then the map needs to
> be able to specify that its default scope name is ‘part1’ in order
> for the reference to resolve.

>  
> I think my resistance to scoped keyrefs boils down to this: any key
> reference that specifies a scope imposes a requirement on any map
> that ever includes that reference to somehow define that scope. It’s
> also true that any non-scoped key reference in a topic imposes a
> requirement (or at least a strong suggestion) that the key be
> defined in any map that uses that topic, but I submit that defining
> a key is conceptually much, much simpler that configuring a scope. I
> envision key scopes as a feature that should only ever be used when
> absolutely necessary, because while they are necessary to support
> some use cases, they also add a lot of complexity to keyref
> resolution, both for processors and for people who have to manage
> and comprehend the map. The fewer situations that require the use of
> scopes, the better. Adding scoped references to a topic to
> accommodate its use in one map makes it impossible to use that topic
> in any map without scopes. And the whole point of keyrefs is the
> reduction of reuse constraints.


I view keyscopes as something that would be common practice for any documentation group dealing with software components - for example Eclipse. But really it would apply to any authoring group where key definitions are not globally managed, but instead managed in a distributed fashion. When using hrefs, the different directory paths provide scoping by component; but without directory paths, we need a similar scoping mechanism, or keys will have a high chance of collision, and use of DITA without a single central CMS becomes impossible. Even in IBM, where we have a strategic enterprise CMS, we still have to deal with content coming in from other parts of IBM, from opensource projects, from business partners, and from acquisitions. Scoping is the obvious and logical way to avoid conflicts among keys coming in from these different groups.

So the question for me is to how handle cross-scope linking - given that I fully expect that it will in fact be a common use case, at least for us.

I've got one question about your approach of redeclaring the keys outside a key scope - what happens if the author is using key scoping to provide different key resolutions for the same topic (one of your primary use cases)?

For example:

- Part1.ditamap and Part2.ditamap both pull in the same "prerequisites.dita" topic, with internal conrefs etc. that are resolved differently in the two different scopes
- part2/intro needs to reference both

Does your approach have an assumption that every topic is only referenced once by a map?

>  
> Chris
>  
>  
> From: Michael Priestley [mailto:mpriestl@ca.ibm.com]
> Sent: Tuesday, February 14, 2012 10:56 AM
> To: Nitchie, Chris
> Cc: Helfinstine, David; dita; Eliot Kimber; Nancy
> Subject: RE: [dita] Proposal 13041 and Cross-Publication Linking

>  
> Hi Chris,
>
> Here's how I'd rework your example to use scoped key references. I'm
> also dropping your cross-publication link syntax - as I think we've
> discussed, I believe it's inadequate to make informed processing
> choices about the output href to create. IE, knowing the target DITA
> map doesn't tell us whether the target will become a PDF or an HTML
> page, or whether the target will be built with one set of ditaval
> conditions or another, or what chunking options have been selected,
> etc. Instead I would prefer to create key definitions as part of the
> output process for a deliverable, which can then be reused by other
> deliverables that wish to reference its content:
>
> That gives us a separate collection map for each deliverable. The
> per-chapter deliverables pull in the key definitions from the other
> chapters as resource-only, with key scoping, so they can easily be
> swapped for the deliverable-specific equivalent hrefs. The omnibus
> deliverable pulls in all definitions as normal navigation, with the
> same key scoping so cross-references that use the scopes continue to work.
>
> Deliverable maps - deciding what navigation maps to pull in and how,
> and applying scoping:
>
> Part-1-solo.ditamap
> -----------------------------
> <map>
>   <mapref href=""> >  <mapref href="" keyscope="Part 2" processing-
> role="resource-only"/>
> </map>
>
> Part-2-solo.ditamap
> -----------------------------
> <map>
>   <mapref href="" keyscope="Part 1" processing-
> role="resource-only"/>
>  <mapref href=""> > </map>
>
> Omnibus.ditamap
> ---------------
> <map>
>  <title>Omnibus</title>
>  <mapref href="" keyscope="Part 1"/>
>  <mapref href="" keyscope="Part 2"/>
> </map>
>
> TOC/navigation maps:
>
> Part-1.ditamap
> --------------
> <map>
>  <title>Part 1</title>
>  <topicref keys="intro" href=""> > </map>
>
> Part-2.ditamap
> --------------
> <map>
>  <title>Part 2</title>
>  <topicref keys="intro" href=""
>   <topicref keys="other" href=""> >  <!-- etc. -->
> </map>
>
>
> And finally, a topic in Part 2 that references both intros:
>
> Other.dita
> ----------
> <topic id="other"
>         <title>Other stuff</title>
>         <body><ul>
>                 <li><xref keyref="part1/intro"/></li>
>                 <li><xref keyref="intro"/></li>
>         </ul></body>
> </topic>
>
> Michael Priestley, Senior Technical Staff Member (STSM)
> Lead IBM DITA Architect
> mpriestl@ca.ibm.com
>
http://dita.xml.org/blog/25
>
>
>
> 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
> Sent by:        <dita@lists.oasis-open.org>

>
>
>
>
> 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.
>
> Part-1.ditamap
> --------------
> <map>
>  <title>Part 1</title>
>  <keydef keys="Part-1.intro intro" scope="local" href=""> >  <keydef keys="Part-2.intro" scope="peer"
>    format="ditamap" href=""> >  <!-- etc. -->
> </map>
>
> Part-2.ditamap
> --------------
> <map>
>  <title>Part 2</title>
>  <keydef keys="Part-1.intro" scope="peer"
>    format="ditamap" href=""> >  <keydef keys="Part-2.intro intro" scope="local" href=""> >  <!-- etc. -->
> </map>
>
> Omnibus.ditamap
> ---------------
> <map>
>  <title>Omnibus</title>
>  <keydef keys="Part-1.intro" href=""> >  <keydef keys="Part-2.intro" href=""> >  <mapref href="" keyscope="Part 1"/>
>  <mapref href="" keyscope="Part 2"/>
> </map>
>
> 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).
>
> Chris
>    
>
> From: Michael Priestley [
mailto:mpriestl@ca.ibm.com]
> 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:
http://lists.oasis-open.org/archives/dita/
> 201109/msg00028.html
>
> A.ditamap
>         <topicref keys="a1" href=""
>         <mapref processing-role="resource-only" href=""> > <!--gets keys to allow a1.dita to reference b1.dita via keyref-->
>
> B.ditamap
>         <topicref keys="b1" href=""
>
> A1.dita
>         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
> mpriestl@ca.ibm.com
>
http://dita.xml.org/blog/25
>
>
>
> 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.
>  
> Chris
>  
> From: Michael Priestley [
mailto:mpriestl@ca.ibm.com]
> 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
> mpriestl@ca.ibm.com
>
http://dita.xml.org/blog/25
>
>
>
> 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
> ________________________________________
>
>
>
>
> Chris,
>
> 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.
>
> Regards,
> Nancy
>
>
>
> On Wed, Jan 25, 2012 at 10:04 AM, Eliot Kimber <ekimber@reallysi.com> wrote:
> Chris,
>
> 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
> map.
>
> 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.
>
> Cheers,
>
> E.
>
> 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 compositionparameters
> > 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
>
www.reallysi.com
>
www.rsuitecms.com
>
>
> ---------------------------------------------------------------------
> 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  
> nharrison@infobridge-solutions.com
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dita-unsubscribe@lists.oasis-open.org
> For additional commands, e-mail: dita-help@lists.oasis-open.org


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