[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: Navigation tree terminology conundrum
I raised the issue of the need for more precise language around the "navigation tree" (see Trello card for this task). Robert and I have discussed it some and not come to a complete consensus. In my review of the latest spec I was keeping an eye out for where either the term "navigation tree" or the concept of navigation tree comes up. The term is used in some places without being formally defined and I think the meaning it has in those places is what I intend it to mean. But that doesn't mean it actually does. A lot of this discussion is in the context of the navref/anchor/anchorref/topicset/topicsetref facilities, which are all about composing "navigation" dynamically. The mapref discussion also talks about the effect on "navigation". Here's a little history: Before DITA 1.2 topicrefs all had what we would now call a role of "normal" and the only control you had was @toc of yes or no: if @toc was "no" then a topic was not reflected *int the ToC*, but it was included in the rendered deliverable. Because the only way to address things was by direct URI reference, you could have topics that were only addressed by @conref and never referenced by any topicref. This would have the effect of using these topics content but not reflecting them in the output directly (because they were never referenced from any map). This was, of course, fundamentally broken. We fixed this in 1.2 by adding the necessary indirect addressing facility, keys. For DITA 1.2, with keys, we realized that *all* topics could (and should) be referenced from the map but that some topics are only used as resources. Thus we defined the @processing-role attribute with the two distinctions "normal" and "resource-only". So now we have two classes of resource: normal and resource-only. We understand resource-only topics to not contribute directly to any deliverable's content. But we never said what precisely it is that normal-role topics *do* contribute to. The @toc yes/no distinction is clearly about generated navigation *artifacts* in deliverables: tables of contents and things like that. The spec tries not to be too specific about what a table of contents is. It also makes it clear in 1.2 that not being in the table of contents is not the same as being resource-only: normal-role topics with @toc="no" are still included in the thing that normal-role topics are included in, whatever that is. I've using the term "navigation tree" to mean "the thing that normal-role topics contribute to" and meant that to be distinct from any navigation *artifacts*, like tables of contents. Robert points out that some people understood the table of contents to *be* the navigation tree. It certainly is *a* navigation tree (in that the point of a table of contents is to enable navigation and it is inherently a tree). But I never understood it to be *the* navigation tree. Robert also correctly points out that maps are not limited to the use case of defining the structures of deliverables or publications or whatever you call whatever it is you produce from your DITA maps: maps can be used to represent any collection of resources related together for any purpose. So we have to be careful not to over-specify what maps intrinsically mean for fear of inadvertently disallowing uses of maps that happen not be publications. But that starts to lead to lots of convoluted language like "when a map is used to produce some for of deliverable that reflects the contents of the resources referenced by the map, normal-role topicrefs are considered to contribute to the overall navigation structure or narrative sequencing of the resources as presented in the deliverable." When we're producing familiar things, like HTML or PDF or online help, we understand what we mean and the spec has lots of clear examples of producing those things. But it's when we need to define the normative meaning of general facilities like keyref, @toc, and navref that things get difficult: the normative language has to be precise and as unambiguous as possible without being overly constraining. That requires clear terms for all applicable concepts, terms that are, as much as possible, divorced from any particular processor, processing style, or deliverable type. Given that background, I think our terminology challenges are: - The abstract term for the thing that normal-role topicrefs define or contribute to. - A clear distinction between navigation artifacts, like tables of contents, which are necessarily specific to particular deliverable types or publication types, and the ordered hierarchical structure defined by the normal-role topicrefs in a map. I have been using the term "navigation tree" for this but it appears that this term is problematic. I think we could approach this problem in part by having some language along the lines of: Abstractly, a map serves to collect and organize resources (topics, maps, and non-DITA resources) in three ways: - Sets of resources referenced as "resource-only", meaning that the reference establishes a dependency on the resource but does not itself relate that resource to any other resource referenced by the map. This set of resources is referred to as the "resource-only resource set". - Sets of resources referenced as "normal-role", meaning that the reference establishes a use of the resource at a specific location within an ordered hierarchy of resources. This set of resources is referred to as the "???? resource set". - Sets of resources linked to other resources through non-hierarchal links (relationship tables). This set of resources is referred to as the "reltable resource set" [Not very happy with that term but I can't think of anything better at the moment] While the DITA specification does not limit the uses to which maps may be put, for the typical use case of producing deliverables intended primarily for reading by people, the normal-role resource hierarchy is understood to define the primary content of the deliverable, establishing its narrative flow and content, which the non-hierachical links establish additional relationships among resources, some or all of which may be rendered as navigation links. Cheers, E. ————— Eliot Kimber, Owner Contrext, LLC http://contrext.com
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]