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] Cross-Deliverable Linking: Requires a-priori knowledge of which maps are root maps

Hi Chris and Eliot,

I also worry about breaking current processing for scope="peer" on a
mapref, as mentioned at the end of the call yesterday, though theoretically
a new @processing-role value or new attribute could manage that. With DITA
1.2 we had a lot of discussion about the meaning of @scope, and decided
that it (together with @format and @href) always described something about
the target, rather than about content in that target. So, scope="peer"
means the map you are referencing is a peer map, not that the map is local
but keys or references inside it are peer. I still think that's the proper
course, though it resulted in some churn with tools I support that used to
take the opposite view.

For option one - I mentioned I had a bit more input, so here goes. We have
some limited support for cross-deliverable linking based on some
specialized map elements. The limited goal in our implementation was to
support cross-PDF links in the book version of the output. We ran into the
same issue of needing to know the "root map" of each deliverable for the
simple reason that PDF output is named for that root map. However, it seems
any solution like this would need to know the root map, because whether you
access that map or not, it is the best representation we have of the target

Given that we defined our specialization against pre-release DITA 1.2
(basically DITA 1.1 plus @keys), we were somewhat limited. The general way
we did it was to define each link target as:
1. @keys attribute, for example "linkTarget"
2. Associated @href (someFile.dita#topic)
3. With a nested <topicref> specialization, specify the root map
"otherDeliverable.ditamap", default to scope=peer, format=ditamap
4. Additional <data> specialization for other metadata useful to identify
target deliverables

As expected, content can then use keyref="linkTarget" to reference
someFile.dita#topic as used in otherDeliverable.ditamap.

I believe this isn't exactly the same issue that Eliot is working on (using
keys from another root map / key space), but I think some of the issues are
the same - in either situation, the root map is effectively the entry point
for anything we want to figure out about addresses/keys in another
deliverable. So, it makes sense to me that you would need to reference it
in some way when setting up cross deliverable links.

Robert D Anderson
IBM Authoring Tools Development
Chief Architect, DITA Open Toolkit (http://dita-ot.sourceforge.net/)

From:	Chris Nitchie <chris.nitchie@oberontech.com>
To:	Eliot Kimber <ekimber@rsicms.com>,
Cc:	dita <dita@lists.oasis-open.org>
Date:	03/20/2013 09:12
Subject:	Re: [dita] Cross-Deliverable Linking: Requires a-priori
            knowledge of which maps are root maps
Sent by:	<dita@lists.oasis-open.org>


I think option 2 could be made palatable when used in combination with
scoped keys. I am planning to rewrite the Phase 2 proposal for scoped keys
to state that keys defined in a scope will be accessible from outside that
scope, so a combination of a peer mapref for purposes of defining
cross-deliverable keys, with a keyscope attribute, would define keys with a
qualified name for use in the local scope, e.g.

<mapref scope="peer" keyscope="otherPublication"

Assuming otherPublication.ditamap defines a key named 'someKey', it could
be referenced via:

<xref keyref="otherPublication.someKey"/>

This wouldn't necessitate the presence of otherPublication as a peer map
for all uses of that xref, because a different top-level map could provide
an explicit definition for the qualified key name, e.g.

<topicref keys='otherPublication.someKey" href="someTopic.dita"/>

Or define that scope as a local child of the root keyspace

<topicgroup keyscope="otherPublication">
  <keydef keys="someKey" href="someTopic.dita"/>

The other thing I think might be desirable to make this work is some way to
mark the peer mapref that brings in the key definitions as being for that
purpose, something like processing-role="peer-keydefs", but I haven't
really thought that through. I just worry about existing, customized
processors that have special handling for peer maprefs being broken by new
spec-mandated processing requirements.


On Mar 18, 2013, at 8:27 PM, Eliot Kimber <ekimber@rsicms.com> wrote:

      In all our discussion of cross-deliverable linking we've talked about
      maps and processing root maps to generate intermediate key
      definitions and
      I've proposed adding the ability to address root maps (key spaces)

      However, something that I think may have gotten overlooked in this
      discussion is the implicit requirement that, for cross-deliverable
      to work, the author of a *referencing* map must know, by some means,
      the potential peer root maps are.

      Without this knowledge there is no way to know that a given map is or
      is not
      a root map: there is nothing inherent in maps generally that makes a
      map be or not be a root map: a map is a root map because it was the
      input to
      a processor and for no other reason.

      I don't think this knowledge requirement is a problem, it's simply a
      fact of
      how things work, a side effect of an implicit or explicit
      choice to not distinguish root maps from other maps at the markup
      level, a
      choice that was and is probably the correct choice.

      But it does mean that all solutions we consider can depend on *map
      knowing which maps, out of all the maps they have knowledge of, are
      maps and which are not.

      This is important because a key definition, by itself, caries no
      about what root map or maps it is a part of (and it may be part of
      many root

      The practical challenge is knowing, for a given peer key reference,
      peer root map that peer key reference applies to.

      In analyzing this more deeply I've come to the conclusion that there
      only two possible ways to know this:

      1. Define new addressing syntax that explicitly references the root
      map that
      defines the key space the referenced key is defined in (my proposal

      2. Directly include as peer maprefs the root maps that define keys
      you want
      to point to from the referencing map.

      Option (1) solves the problem directly by making the key-to-key-space
      binding explicit and direct. It avoids any requirement to make keys
      across all the peer maps referenced from a given referencing map.

      Option (2) solves the problem indirectly by establishing the root
      context of each key, with the implication being that the referenced
      peer map
      from which a given key definition is descended is the root map the
      applies to.

      Option (2) requires that keys be globally unique across all the
      peer maps: because in the general case every root map will include
      other root map as a peer, all keys defined in all the possible peer
      must be unique, otherwise, keys from one peer map could override keys
      another peer map, in which case it would be impossible to point to
      overridden keys. In practice, for a set of root maps developed
      (e.g., the document for a product or family of products or all the
      an enterprise produces) the keys must be globally unique because you
      predict what the peer-to-peer relationships might be in the future.
      would require either an impossibly omniscient information management
      or use of some form of UUID, both of which are pretty ugly options.

      It would mean that you couldn't ever have common set of key
      because each root map would need to have unique key names even for
      shared across root maps. Splitting or merging root maps wouldn't be a
      problem because all key names would remain unique after the split or
      but you couldn't use naming conventions that include the root map
      name in
      the key names without having to rewrite key names in the case of
      split or

      I am really uncomfortable with requiring global key spaces across
      peer maps:
      I think it requires what is essentially an impossible management
      in the general case. Thus, I continue to assert that proposal 13041
      essential for a practical solution to cross-deliverable addressing.

      However, I do recognize that including peer root maps with a scope of
      is sufficient to indicate the ultimate owning root map of a given key
      definition. But note that this requires that the *root map* be the
      included in the referencing map, not just a separate key definition
      that happens to be used from the root map.



      Eliot Kimber
      Senior Solutions Architect, RSI Content Solutions
      "Bringing Strategy, Content, and Technology Together"
      Main: 512.554.9368
      Book: DITA For Practitioners, from XML Press,

      To unsubscribe from this mail list, you must leave the OASIS TC that
      generates this mail.  Follow this link to all your TCs in OASIS at:

 Chris Nitchie                  
 Oberon Technologies, Inc.      
 2640 Wildwood Trail            
 Saline, MI 48176               
 Main: 734.666.0400             
 Direct: 734.330.2978           

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