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

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:] 
Sent: Wednesday, October 05, 2005 7:18 
AM
To: 'Erik Hennum'
Cc: 

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:]
Sent: Tuesday, October 04, 2005 1:35 
  PM
To: Eliot Kimber
Cc: 
  
Subject: Re: [dita] Indexterm: page 
  ranges

  
Hi, Eliot and TC:

Eliot Kimber 
  <> 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