[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
I agree with Chris that a solution for referencing keys within scopes needs
to be coordinated with any keyspace-to-keyspace solution.
A key scope is really just a key space that is explicitly related to another
key space, which means that it's fundamentally no different from a
root-map-defined key space, it just has a known relationship to other key
spaces (it's ancestor key spaces and descendant key spaces) whereas a
root-map-defined keyspace has no known relationship to any other key spaces
(other than any descendant key scopes it might have).
So I think we have a common requirement for a new key reference syntax that
lets you specify the key space and key together, whether that key space is a
peer key space or a "scope" defined in the same root map as the reference.
As to Robert's concern about the meaning of scope="peer" on a mapref--if we
have this two-level key reference syntax, then I think we can say clearly:
"maps referenced as peers provide keys that may be referenced by a two-part
key reference. The keys within peer maps *do not* contribute to the key
space of the referencing map."
That is, you cannot directly reference a key in a peer map--you must address
both the map (key space) and the key together. To have a local key reference
that gets to a peer resource you must have two levels of key definition: one
for the local key that then provides the keyspace-specific reference to the
peer key.
I think that is consistent with Robert's understanding of our intent for the
meaning of peer and with the way current processors do or should process
peer maps.
For argument's sake and for my DITA NA demo I'm going to propose the syntax:
[{keyspace-name}::]{keyname}[/{elementId}]
As the syntax for key references, where "keyspace-name" is either a key
bound to a peer-scope mapref or the name of a defined key scope (however
that works out).
I've chosen to use "::" as the separator as being analogous to the axis/term
separator in XPath: the keyspace-name establishes the context ("axis") that
the specified key is resolved in. I can't think of any other separator that
wouldn't cause potential confusion (e.g., "/", ".", "#", "%", etc.) or that
isn't common to all keyboards (e.g, "^").
Thus, to refer to a key in another map, you would have something like this:
<map>
...
<!-- Peer reference to another root map (key space): -->
<mapref scope="peer"
keys="map-b"
href="../map-b/map-b.ditamap"
/>
<!-- Local key bound to key in Map B: -->
<keydef keys="local-key-01"
keyref="map-b::topic-b-01"
/>
...
</map>
Here a reference to the key "local-key-01" gets resolved to the key
"topic-b-01" as defined in map map-b.ditamap.
Likewise, from an xref you could address the topic in map B directly if that
was appropriate:
<xref keyref="map-b::topic-b-01"/>
Which is the author's way of saying "I know Map B will (or should) always
exist and I mean for this reference to unalterably be to Map B and nothing
else. There are times when that's what you want.
For the purposes of my demo for DITA NA I will use this proposed syntax, but
I'm not suggesting it's either the best answer or my most considered
suggestion, it's just what I've thought of at the moment.
Cheers,
E.
On 3/20/13 8:54 AM, "Robert D Anderson" <robander@us.ibm.com> wrote:
> 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
> deliverable.
>
> 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>
>
>
>
> Eliot,
>
> 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"
> href="otherPublication.ditamap"/>
>
> 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"/>
> </topicgroup>
>
> 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.
>
> Chris
>
>
> 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
> root
> maps and processing root maps to generate intermediate key
> definitions and
> I've proposed adding the ability to address root maps (key spaces)
> (proposal
> 13041).
>
> However, something that I think may have gotten overlooked in this
> discussion is the implicit requirement that, for cross-deliverable
> linking
> to work, the author of a *referencing* map must know, by some means,
> what
> 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
> given
> 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
> architectural
> 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
> authors*
> knowing which maps, out of all the maps they have knowledge of, are
> root
> maps and which are not.
>
> This is important because a key definition, by itself, caries no
> information
> about what root map or maps it is a part of (and it may be part of
> many root
> maps).
>
> The practical challenge is knowing, for a given peer key reference,
> which
> peer root map that peer key reference applies to.
>
> In analyzing this more deeply I've come to the conclusion that there
> are
> 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
> 13041)
>
> 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
> unique
> across all the peer maps referenced from a given referencing map.
>
> Option (2) solves the problem indirectly by establishing the root
> definition
> 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
> key
> applies to.
>
> Option (2) requires that keys be globally unique across all the
> coordinated
> peer maps: because in the general case every root map will include
> every
> other root map as a peer, all keys defined in all the possible peer
> maps
> must be unique, otherwise, keys from one peer map could override keys
> from
> another peer map, in which case it would be impossible to point to
> overridden keys. In practice, for a set of root maps developed
> together
> (e.g., the document for a product or family of products or all the
> products
> an enterprise produces) the keys must be globally unique because you
> cannot
> predict what the peer-to-peer relationships might be in the future.
> This
> would require either an impossibly omniscient information management
> system
> 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
> definitions
> because each root map would need to have unique key names even for
> topics
> 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
> merge,
> 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
> merge.
>
> I am really uncomfortable with requiring global key spaces across
> peer maps:
> I think it requires what is essentially an impossible management
> requirement
> in the general case. Thus, I continue to assert that proposal 13041
> is
> essential for a practical solution to cross-deliverable addressing.
>
> However, I do recognize that including peer root maps with a scope of
> "peer"
> 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
> thing
> included in the referencing map, not just a separate key definition
> file
> that happens to be used from the root map.
>
> Cheers,
>
> E.
>
> --
> Eliot Kimber
> Senior Solutions Architect, RSI Content Solutions
> "Bringing Strategy, Content, and Technology Together"
> Main: 512.554.9368
> www.rsicms.com
> www.rsuitecms.com
> Book: DITA For Practitioners, from XML Press,
> http://xmlpress.net/publications/dita/practitioners-1/
>
>
> ---------------------------------------------------------------------
> 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:
> https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php
>
>
>
>
>
>
>
> Chris Nitchie
> Oberon Technologies, Inc.
> 2640 Wildwood Trail
> Saline, MI 48176
> Main: 734.666.0400
> Direct: 734.330.2978
> Email:
> chris.nitchie@oberontech.com
> www.oberontech.com
>
>
>
>
>
>
>
>
>
>
> ---------------------------------------------------------------------
> 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:
> https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php
>
--
Eliot Kimber
Senior Solutions Architect, RSI Content Solutions
"Bringing Strategy, Content, and Technology Together"
Main: 512.554.9368
www.rsicms.com
www.rsuitecms.com
Book: DITA For Practitioners, from XML Press,
http://xmlpress.net/publications/dita/practitioners-1/
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]