Navigation tree terminology conundrum

[Eliot Kimber <ekimber@contrext.com>]

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