Re: [dita] Conceptual Refinement for DITA 1.3: Navigation Tree

[Eliot Kimber <ekimber@reallysi.com>]

Good point.

I didn't mean to imply that every map represents a navigation tree--I was
trying to come from the other direction, namely, a navigation tree is
created by a map that contains normal-role topicrefs and is processed as a
root map.

Note that DITA necessarily makes a processing distinction between root maps
and subordinate maps. Unfortunately, there's nothing about a map, by itself,
that requires or prevents it from being processed as a root map, so we have
to either say "processed as a root map" or define the term "root map" to
mean "a map processed as a root map". I tend to use the term "publication"
but "publication" is too specific given the wise range of potential uses one
might put a map to.

I forgot about relationship tables, but that's clearly another type of
topicref that does not directly contribute to the navigation tree as I've
defined it. Other than "reltable topicrefs" we don't really have a crisp
name for those topicrefs either.

Note that a root map that has only resource-only topicrefs and reltables
certainly cannot have an explicit navigation tree, although it might be
possible to infer one based on the relationships established by the
relationship table.

That is, reltables are no resource-only topicrefs but since they lack
inherent ordering, at least in the general case, they can at best define a
"navigation set" or "navigation graph", not a "navigation tree".

Cheers,

E.

On 2/5/12 11:03 AM, "Michael Priestley" <mpriestl@ca.ibm.com> wrote:

> How would reltables factor into this?
> 
> Before DITA became a standard, we actually talked about DITA maps as
> "navigation maps", but then chose to go more generic to handle cases where the
> topicrefs are performing in ways other than strictly navigational - for
> example, reltables (although they could be argued to provide non-hierarchical
> navigation). But certainly not every map needs to express navigation trees.
> 
> That said, I agree it may be useful to codify the concept of a navigation tree
> as one of the things a map may express - I'm just not sure that we'd want to
> say that maps are necessarily about navigation trees.
> 
> Michael Priestley, Senior Technical Staff Member (STSM)
> Lead IBM DITA Architect
> mpriestl@ca.ibm.com
> http://dita.xml.org/blog/25 <http://dita.xml.org/blog/25>
> 
> 
> 
> From:       Eliot Kimber <ekimber@reallysi.com>
> To:       dita <dita@lists.oasis-open.org>,
> Date:       02/05/2012 10:51 AM
> Subject:       [dita] Conceptual Refinement for DITA 1.3: Navigation Tree
> Sent by:       <dita@lists.oasis-open.org>
> 
> 
> 
> 
> 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