RE: [dita] Indexterm: ... [ and mentions ]

["JoAnn Hackos" <joann.hackos@comtech-serv.com>]

Bruce et al.

I would support the 1a alternative for the reasons you give here.

 

One of the issues seems to center around "best practices." An index is not intended to be a concordance, despite the many bad automated indexing programs that used to "index" every instance of a term. I saw one that indexed all the punctuation in a document.

 

"mention" strikes me as bad practice in indexing unless I'm understanding it incorrectly.

 

Paul's principle of doing something one way is excellent, especially if we instantiate best practices rather than whatever anyone would like or want to do in their organizations. When we work with organizations implementing structured authoring (DITA or not), we focus on industry best practices as much as possible. Structured authoring is new to many organizations, especially when structure does not equal format. They actually have to change the way they think about writing content, a good thing in every instance we've worked with.

 

Certainly, indexing practices in most organizations are very poor. People are not trained in indexing, it's left til the last moment, and the indexes are worthless to the reader. But that should not result in our support for such practices. In general, I see the DITA model as recommending better practices in the industry. The strength of the model is not in the technology but in the conceptualization of best practices behind it.

 

JoAnn

---

From: Esrig, Bruce (Bruce) [mailto:esrig@lucent.com]
Sent: Wednesday, October 05, 2005 7:18 AM
To: 'Erik Hennum'
Cc: dita@lists.oasis-open.org
Subject: RE: [dita] Indexterm: ... [ and mentions ]

1a. Would we permit mentions within indexterm?

 

<indexterm>major index group

   <indexterm><mention>term</mention>

   </indexterm></indexterm>

 

1b. Alternatively, a weaker proposal: perhaps we could add an attribute to the mentions so that occurrences could be flagged to be included in the index.

 

The processing of

  <mention add-to-index="y">term</mention>

would be the same as for

  <mention>term</mention><indexterm>term</indexterm>

 

2. Thinking about which alternative is better in principle, alternative 1a seems a more robust design. Alternative 1b violates the "one way to do things rule", and forces a fall-back approach.

 

It follows instead, "offer a path to a context-appropriate result from every context", which requires the complementary rule "support consistent functionality along all paths".

 

The "context-appropriate result" is not the same along all paths. You can't get nested index entries using attributes on a mention, but you can get a mention into the index. That's appropriate for mentions. If you wanted a nested index entry, you could have started with that.

 

Bruce

-----Original Message-----
From: Erik Hennum [mailto:ehennum@us.ibm.com]
Sent: Tuesday, October 04, 2005 1:35 PM
To: Eliot Kimber
Cc: dita@lists.oasis-open.org
Subject: Re: [dita] Indexterm: page ranges

Hi, Eliot and TC:

Eliot Kimber <ekimber@innodata-isogen.com> wrote on 10/04/2005 08:00:11 AM:

> ... for many authors index terms are precisely a marker indicating the
> occurrence of a specific word or phrase at a specific location.
>
> That is, while sometimes index entries are exactly as Erik states (and
> this is why they would normally generate a page range in the rendered
> index) it is not an exclusive, or necessarly even typical, use of index
> markers.

Point taken. As the thread has noted previously, such occurrences of indexable language would be better handled as mentions delimited with <keyword> or <term> rather than with <indexterm> markers. Instead of requiring the writer to provide the term twice as in the following example

For the proper care and feeding of an element<indexterm>element</indexterm>, you usually supply content.

the processing might make use of the inline term for the index:

For the proper care and feeding of an <term>element</term>, you usually supply content.

A mention would never span multiple pages and thus wouldn't require a range.


Thanks,


Erik Hennum
ehennum@us.ibm.com