Re: [dita] What are the implications of <navref> for key space construction?

[Robert D Anderson <robander@us.ibm.com>]

Hi Eliot - that fits with my understanding of navref.

Robert D Anderson
IBM Authoring Tools Development
Chief Architect, DITA Open Toolkit

Eliot Kimber <ekimber@reallysi.com> wrote on 12/07/2009 11:11:23 AM:

> Re: [dita] What are the implications of <navref> for key space
construction?
>
> Here's what I think is the only way <navref> can work with respect to key
> definitions and reliably produce a correct result.
>
> If we accept that a primary use case for <navref> is that the referenced
map
> is not processed as part of the output generation for the main map tree,
> then several things must be true:
>
> 1. The navreffed map must establish a distinct key space, otherwise it
would
> not be possible to process that map in isolation and support key
references
> within it.
>
> 2. Key references from the main map tree context can never be to topics
as
> used from the navreffed map because there is no way in DITA 1.2 to
> explicitly point to the key-space-defining map for a given key reference.
>
> That means that <navref> *must* be ignored for the purposes of key space
> construction. This implies that the navref-included map must be processed
> separately, at a minimum for the purpose of resolving key references,
since
> key references from topics and maps referenced by the navreffed map
*cannot*
> resolve to key definitions effective for the root map (they must always
> resolve to key definitions effective for the navref-included map
processed
> as a separate root map). This is true even if the navref-referenced map
is
> also included normally in the main map tree.
>
> That is, if map B is included from map A by both <navref> and <topicref>,
> map B is processed as a root map for purposes of determining the
effective
> rendered result for the <navref> and also processed as a submap of the
map
> tree rooted at map A.
>
> This means that there *must* be two result copies of each map and topic
used
> by map B in this case, one with key references resolved in the context of
> map B's key space and one with key references resolved in the context of
map
> A's key space.
>
> As a larger issue to consider in 1.3, it seems to me that the
> Eclipse-specific case that <navref> was originally designed to support is
a
> specific instance of more general peer-map-to-peer-map relationships,
> something DITA already has a way to express, namely the @scope attribute
on
> topicref. To that degree <navref> is both redundant and underspecified
(for
> example, we didn't add @keyref to <navref>, which we absolutely should
do,
> if we think it is at all useful).
>
> A tool that needs to do something specific with peer relationships can
> always do two things:
>
> 1. Define a specialization of topicref that expresses the desired
> peer-to-peer semantic and sets @scope to "peer" and/or define in prose a
> convention for the meaning of @scope="peer".
>
> 2. Implement whatever behavior it wants or needs as part of a
tool-specific
> output process.
>
> For DITA 1.3 we definitely need to rethink <navref> and provide a more
> complete and architected alternative.
>
> For DITA 1.2 we simply need to make clear what the key-related
implications
> are.
>
> Cheers,
>
> Eliot
>
> --
> Eliot Kimber
> Senior Solutions Architect
> "Bringing Strategy, Content, and Technology Together"
> Main: 610.631.6770
> www.reallysi.com
> www.rsuitecms.com
>