[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 book). 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. Cheers, E. 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 www.reallysi.com www.rsuitecms.com
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]