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] index terms


Hi, Esteemed TC:

Before incorporating older publishing approaches in DITA, we should consider whether those approaches support the topic architecture and reuse.

Regarding indexing markers, I'd submit that most writers don't think they're indexing a point. They think they're indexing the content around the index marker.

If we want to be specific about our interpretation of a standalone index marker, a few alternatives are obvious:


None of the three approaches does violence to the fundamental assumption that the indexed content is around the index marker. Each of the three can lead to surprises for the writer.

Start and end markers, however, pose problems for reuse. Taking up the problem raised by JoAnn, let's say you want to index a range of three topics about web applications and put a start marker at the start of the first topic and an end marker at the end of the second topic:

In another information set, however, the start and end topics are organized in a different way:

In the second information set, the end marker precedes the start marker. Worse, content completely unrelated to web applications is in the middle of the range. Worst, there's no way to fix the problem for the second deliverable without invalidating the first deliverable.

The problem is architectural: properties that span multiple topics should be specified in the map context and not in the topic content.

We could move the start and end markers into the map itself:

Let's say you add conditional metadata, however, and filter out the start topic, the end topic, or both. It's ambiguous whether to apply the index term to the middle topic. Maybe the middle topic belongs in the indexed range only as part of a sequence including the start and end topics.

More importantly, it is much more natural to leverage the grouping provided by the parent element:
               <indexterm>Web applications</indexterm>
Finally, one of the main reasons for tagging is to define semantic units. Why wouldn't we want to take advantage of those semantic units when indexing?

In summary, defining a range with start and end points works better for a single, static discourse flow than for topics that can be organized in many different ways.

Regarding synonyms, it should at least be possible to maintain associations between controlled vocabularies globally. I've known publications departments (for instance, at Informix) that maintained all of the see synonyms at the end of the introduction because (by definition) a see synonym isn't associated with any particular piece of content. In DITA, however, the map is a much more natural place to maintain definitions that aren't associated with specific content.

Bruce has a good point about centralizing index labels through conref. Especially if keyrefs can be used in conref, that would seem to meet the requirement for being able to maintain index labels centrally.

Because an index term is always about content, an about-href attribute on indexterm would likely be overkill. Topicref already gives you the ability to attach an index term to a topic. (By the way, in passing, a popup for associative index links might be more useful than a ring of links.)

A last consideration. The <term> and <keyword> elements delimit controlled vocabularies that are embedded in the discourse. Should the writer have to add an index marker to index such instances of controlled vocabularies? Or would we be better off indexing delimited vocabularies (possibly under the control of policies)?


What do you think?


Erik Hennum
ehennum@us.ibm.com


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