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


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