RE: [dita] review of index* elements

["Grosso, Paul" <pgrosso@ptc.com>]

Here is my summary of where we are on the index* element 
issues.  Please note that the "proposed solutions" are
my proposals--they have not been approved by the TC, and
in at least one case are potentially controversial.  I'm
stating them here in an attempt to put a stake in the
ground so we can determine how much further we have to
go before we can call the issues closed.

I plan to fulfill my actions this week unless
I hear objections to the proposed resolutions asap.

There are also outstanding actions for others.

> -----Original Message-----
> From: Grosso, Paul [mailto:pgrosso@ptc.com] 
> Sent: Wednesday, 2006 September 20 10:49
> 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.

Proposed resolution:

It is an error if you have both an index-see as well 
as an index-see-also or indexterm for the same index
entry (technically, with an identical sort pattern).
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).

ACTION to Paul:  Provide suggested wording.

> 
> index-see-also
> --------------
> Will the "Content reference to..." in this description
> actually become a content reference in the next draft?
> 

ACTION to Don et al.:  Ensure the content reference in
index-see-also gets expanded.

> 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.
> 

Proposed resolution:

An index-see-also always generates a page number.
That is, an index-see-also is effectively a pointwise
indexterm (as well as the see-also reference).  Therefore,
there is never a situation where index-see-also becomes
an index-see.

ACTION to Paul:  Provide suggested wording.

> 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.
> 

ACTION to Michael:  Propose a resolution.

---

Issue:  What if an an indexterm contains both an index-see 
and an index-see-also.

Proposed resolution:

It is an error if an indexterm contains both an index-see 
and an index-see-also.  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).

ACTION to Paul:  Provide suggested wording.


> 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.
> 

Issue:  Given what we've recently decided about indexterms
in the prolog, are we still planning to allow index-sort-as
within the prolog define "global sort order"?

Proposed resolution:

Do away with the "global sort order" concept for DITA 1.1.
If and when we do define such, we should use different
markup than the usual indexterm/index-sort-as.

ACTION to Paul:  Provide suggested wording (or delete some
existing wording as necessary).

---

Issue:  What happens when two indexterms with different
content have identical sort-as values?

Proposed resolution:

The indexterm textual content itself is effectively considered
as a "secondary sort field" in addition to the sort-as value, 
so two indexterms with different content will never merge into
the same index entry.

ACTION to Paul:  Provide suggested wording.

> Furthermore, it isn't clear to me how to use sort-as for 
> a multilevel index term.
> 

Proposed resolution:

An index-sort-as provides the sort key for the indexterm
that is its parent.

ACTION to Paul:  Provide suggested wording.