Conceptual Refinement for DITA 1.3: Navigation Tree

[Eliot Kimber <ekimber@reallysi.com>]

When we added @processing-role to DITA in 1.2 we created a distinction
between "normal" and "resource-only" topicrefs. However, we never fully
defined what "normal" really means or what the result of processing the
normal-role topicrefs produces in terms of DITA's implicit or explicit
abstract model. (There is an abstract DITA model--the question is the degree
to which we've defined in clearly and explicitly and the degree to which we,
the TC, agree on what that model is. Until we make the model fully explicit
there is no way to come to agreement on what it is. We had to do some of
that in order to define and explain key references, but we didn't do it more
generally.) 

In my efforts to explain DITA I've found the need to talk about the
"navigation tree" as the abstract thing a map ultimately describes and from
which renditions are produced.

I think it would be useful in DITA 1.3 to codify the concept of navigation
tree and define it as formally as we can. In particular, it is useful, if
not necessary, to be able to talk about the resource-only aspect of the map
for processing purposes as distinct from the non-resource-only part of the
map. But we don't currently have a well-recognized name for the
non-resource-only part of the map, because until DITA 1.2, it was just "the
map".

What I mean by "navigation tree" is:

The effective tree of topicrefs rooted at the root map consisting of all
normal-processing-role topicrefs contributed by all submaps or otherwise
included into the navigation tree (e.g., through the use of topicsetref,
anchors, and etc.) following all key space construction, content reference
processing, filtering, @chunk and copy-to processing, and metadata
propagation down the map hierarchy.

Note that the result may not be a singly-rooted tree of topicrefs as there
is no requirement that a map have exactly one normal-role child topicref. So
this is either a potentially multiply-rooted tree or, if you prefer, there
is an implicit root node implied by the root map itself. [Which is *not* the
same as saying *each* map in the map tree implies a node in the navigation
tree--only the root of the publication can imply such a node, for the reason
that DITA already says in particular that the titles of submaps are ignored
and do not contribute to renditions--thus a node implied by a submap would
be equivalent to a topic group and would have no effect on the navigation
tree.]

I propose the term "navigation topicref" to mean a non-topic-group topicref
that contributes to the navigation tree. That is, normal-role topicrefs that
act as either topic heads or references to topics. I have defined this term
specifically to allow for future values for @processing-role that are
different from "normal" but still contribute to the navigation tree (not
that I can imagine what one such might be, but I have to allow for the
possibility).

The "navigation tree" is necessarily an abstraction constructed by
processors from DITA-defined processing of a tree of map documents. It can
be represented syntactically by constructing a new single-document map
reflecting the result of doing all the preprocessing and rewriting any IDs
(and corresponding references to those IDs) on topicrefs with IDs included
more than once in the navigation tree (note that it may not be possible to
unambiguously determine which copy of a given topicref a reference to the
original ID intends--in that case processors are free to choose one,
presumably the first in the navigation tree). But there is no requirement
that processors literally create such an intermediate map document.

For processing purposes, the navigation tree then determines the order and
content of the "publication" produced from the root map. Because of the @toc
attribute, the navigation tree may not directly reflect any table of
contents produced for a given publication. (So maybe a better term would be
"content tree"?)

Another way to think of it might be to say the navigation tree is the
"visible part" of the map.

In any case, I think it's important for us to have an agreed-upon term for
what it is that a map defines, because with DITA 1.2 "map" is not
sufficiently descriptive.

Cheers,

E.

-- 
Eliot Kimber
Senior Solutions Architect
"Bringing Strategy, Content, and Technology Together"
Main: 512.554.9368
www.reallysi.com
www.rsuitecms.com