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] Conceptual Refinement for DITA 1.3: Navigation Tree

I just noticed that the description of the <anchor> element uses the term
"navigation tree":

"The <anchor> element provides an integration point that another map
can reference in order to insert its navigation into the _current navigation
tree_." (Emphasis mine)

I don't think I wrote that, since I have only recently become fully aware of
the anchor/anchorref feature (and I'm just now trying to describe it in my

Looking further, I see that in fact the term "navigation tree" is used quite
a bit in the Arch Spec.

However, it is not formally defined in the terminology section.

In thinking about this more, I also think that the term "navigation graph"
or "topic graph", meaning the set of links defined by the relationship
tables in a map, would be useful as well, to make it easier to talk about
the navigation tree as distinct from the topic graph, both of which are then
distinct from any resource-only role topicrefs in the map.



On 2/5/12 9:50 AM, "Eliot Kimber" <ekimber@reallysi.com> wrote:

> 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
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dita-unsubscribe@lists.oasis-open.org
> For additional commands, e-mail: dita-help@lists.oasis-open.org

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

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