RE: [dita] review of index* elements [was: DITA 1.1 Language Specification -- draft (ditaref-alpha.pdf) uploaded]

["Chris Wong" <cwong@idiominc.com>]

Yes, an index-see-also always generates a page number. Here is the
example from the writeup:

"An index-see-also element expresses another entry that the reader may
reference in addition to that entry. For example,

 <indexterm>Carp
     <index-see-also>Goldfish</index-see-also>
 </indexterm>

This will typically generate a page reference to "Carp" and a
redirection:

	Carp, 56
		see also Goldfish"

As the writeup states, the element expresses a redirection IN ADDITION
to that entry. 

Concerning your other example:

	
<indexterm>$apple<index-sort-as>apple</index-sort-as></indexterm>
	. . .
	<indexterm>apple</indexterm>

This should always result in separate entries:

	$apple, 3
	apple, 7


This is because the operative phrase in index-sort-as is "sort as". This
does not mean "index as": the processor is not being told to convert
"$apple" to "apple". If the author intended to have "apple" appear in
the first indexterm, he should not have typed "$apple" in the indexterm.

I concur with Bruce that the "ignore unless leaf" rule does not apply to
index-sort-as.

As to your question concerning "universal sort order" at:

http://lists.oasis-open.org/archives/dita/200607/msg00076.html

I'm inclined to apply the index-sort-as directive only to the
multi-level indexterms to which the expressions apply (your first
option).

Chris


-----Original Message-----
From: Grosso, Paul [mailto:pgrosso@ptc.com] 
Sent: Thursday, September 21, 2006 6:53 PM
To: dita@lists.oasis-open.org
Subject: RE: [dita] review of index* elements [was: DITA 1.1 Language
Specification -- draft (ditaref-alpha.pdf) uploaded]

For all these issues, we need to develop wording for the spec.  I'm
willing to offer to do that once we come up with decisions, but for now,
I'm holding off on wording until we agree what we want to do.

> -----Original Message-----
> From: Esrig, Bruce (Bruce) [mailto:esrig@lucent.com]
> Sent: Wednesday, 2006 September 20 18:46
> To: Grosso, Paul
> Cc: dita@lists.oasis-open.org
> Subject: RE: [dita] review of index* elements [was: DITA 1.1 Language 
> Specification -- draft (ditaref-alpha.pdf) uploaded]
> 
> I have answers for some of your questions ...
> 

First, a clarification of terminology.

An index entry is something that gets generated in the resulting index.
So you don't mean "another index entry generates a page reference", you
mean "another indexterm generates a page reference".

I don't mean to be overly-pedantic about this, but this topic is so
confusing, you really need to be careful about terminology.

> For index-see/index-see-also, the rule I recall is that if you have an

> index-see but another index entry generates a page reference, the 
> index-see is treated as a see-also.

I'm assuming by omission that you are saying that an index-see-also
always generates a page number.  
So a single indexterm such as:

<indexterm>Carp
   <index-see-also>Goldfish</index-see-also>
</indexterm>

that falls on page 56 would generate something like:

* Carp, 56
  - See also Goldfish

even if there were never any other indexterm for Carp.

I agree, but we need to make it clear in the writeup for index-see-also
that an indexterm containing an index-see-also always generates both the
page reference and the "See also".

----

Now as far as implicitly treating an index-see as an index-see-also when
there is another indexterm that generates a page reference, I can see
how that might feel right.  But there are a couple problems with that.

First, we are guessing what the user meant when they did something that
didn't make sense.  Perhaps they really wanted a "See", and the other
indexterm is a mistake, and they would rather get an error message so
that they can fix this.  

DocBook [1] calls this an error ("...an entry in the index should never
have both a see and other content....DocBook cannot detect these
errors.").

Arbortext's index handling has always flagged such cases as errors.

Second, per what we just said above about index-see-also, I'm not sure
you really want to treat such an index-see as an index-see-also.  You
may not really want the page number on which the index-see occurred to
be added to the list of page numbers in the index entry.

I recommend we state that such a situation is an error; an
implementation may (but need not) give an error message, and may (but
need not) recover by treating the index-see as an index-see-also (in
which case the page number where the index-see-also occurred will also
appear in the index entry).

[1]
http://www.oasis-open.org/docbook/documentation/reference/html/see.html

----

We haven't directly addressed the case where an indexterm contains both
an index-see and an index-see-also.  I recommend we do similarly,
stating that this is an error, and an implementation may recover by
ignoring the index-see.

> 
> For your index-sort-as question, a single 
> <index-sort-as>apple</index-sort-as> at the highest level should cover

> the entire index entry, causing "$apple" to be sorted as "apple". If 
> index-sort-as appears at a lower level, it would affect the sorting of

> the value at that level only. If that doesn't answer the question, 
> then more examples might be needed.

I agree with what you say as far as it goes.  It parallels, for example,
what DocBook does with the "sortas" attribute on primary, secondary, and
tertiary.  Unfortunately, DocBook is no clearer on some issues here than
we are at the moment.

Suppose my document contains:

<indexterm>$apple<index-sort-as>apple</index-sort-as></indexterm>
. . .
<indexterm>apple</indexterm>

(where . . . represents several pages of content) such that the first
indexterm falls on page 3 and the second on page 7.

Would my generated index look something like:

	apple, 3, 7

or

	$apple, 3, 7

or

	apple, 3
	$apple, 7

or something else?

[Note, there are many more issues with respect to index-sort-as in the
prolog, aka "global sort order", but we aren't discussing that here.]

> 
> The "ignore unless a leaf" criterion wouldn't seem to apply to 
> index-sort-as, since its function is to affect processing of a value, 
> not to create a new index entry.

Agreed, and I'm not sure why I even raised this question, since the spec
is fine as is in this regard.

> 
> Not addressed in this response: the "global sort order" and "maximum 
> range" issues.

I await further responses for these issues.

paul

> 
> Best wishes,
> 
> Bruce
> 
> -----Original Message-----
> From: Grosso, Paul [mailto:pgrosso@ptc.com]
> Sent: Wednesday, September 20, 2006 11:49 AM
> To: dita@lists.oasis-open.org
> Subject: [dita] review of index* elements [was: DITA 1.1 Language 
> Specification -- draft (ditaref-alpha.pdf) uploaded]
> 
> index-see
> ---------
> The description doesn't make clear when a see becomes a see-also and 
> vice versa or whether there are error cases and/or when we ignore one 
> in favor of the other.
> 
> index-see-also
> --------------
> Will the "Content reference to..." in this description actually become

> a content reference in the next draft?
> 
> The description doesn't make clear when a see becomes a see-also and 
> vice versa or whether there are error cases and/or when we ignore one 
> in favor of the other.
> 
> indexterm
> ---------
> In the first bullet point ("In a map..."), there remains a question
> ("???") about how to define the maximum scope of a range specified in 
> a map file.
> 
> index-sort-as
> -------------
> There remains lots of issues about "global sort order" 
> using indexterms within the prolog.  For one thing, this contradicts 
> other decisions we made about what an indexterm within the prolog 
> means.
> See also my email of July 26:
> http://lists.oasis-open.org/archives/dita/200607/msg00076.html
> with other questions/issues about sort-as that have never been 
> answered.
> 
> Furthermore, it isn't clear to me how to use sort-as for a multilevel 
> index term.
> 
> It is unclear how to handle the "ignore unless a leaf" 
> issue for index-sort-as.
> 
> paul
>