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] What are the implications of <navref> for key spaceconstruction?

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



Eliot Kimber
Senior Solutions Architect
"Bringing Strategy, Content, and Technology Together"
Main: 610.631.6770

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