RE: [dita] comments on indexing wording in dita 1.1 draft

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

1 and 2: Any rewording that makes the documentation clearer would be
welcome. But I'm afraid I don't understand what you mean here.

3. Inverting the indexterm/index-range-* content models on a
design-approved proposal is a little drastic this late, isn't it? This
is the first time I've heard of this, so I'm rather taken aback. All the
new indexing elements are architected to be allowed only within an
indexterm. Indeed, that is the whole point of the index-base element
from which they specialize. The idea is that all of these elements only
make sense within an indexterm and should not clutter the content model
of other elements. Please consider the implications of turning all these
indexing elements' content models inside out.

4. I believe you are confusing the case of an indexterm within a map's
prolog (where it has no content context) and a map topicref's prolog
(where it has a topic's context). In the case of the former, there is
absolutely no content context from which a page reference can be
meaningfully derived. In the case of the latter, a page reference can be
derived from the topic's location.

Chris

-----Original Message-----
From: Esrig, Bruce (Bruce) [mailto:esrig@lucent.com] 
Sent: Tuesday, August 08, 2006 6:29 AM
To: Chris Wong
Cc: dita@lists.oasis-open.org
Subject: RE: [dita] comments on indexing wording in dita 1.1 draft

Hi Chris,

1. Do you agree that it would help to clarify in the language and/or
architecture guides "how an index entry is identified" (see for example
item 2)? We could say: "the complete name of an index entry is
<indexterm>[text and, if applicable, nested indexterms]</indexterm>. The
informal name is [text and, if applicable, nested indexterms]." Then we
can indicate where the complete name and the informal name are used.

2. The <index-see> element (and <index-see-also>) have the semantic form
index-see(source-indexterm, target-indexterm). In the presentation of
<index-see>, both the identity issue (item 1) and this issue should be
acknowledged by providing appropriate background in the text. "A
reference or redirection from a source indexterm to a target indexterm
is made by ..."

3. I can't recall why <indexterm> is the outermost element in the
following two scenarios.

3a. The range start and end markers formally should be of the form
<index-range-start><indexterm>...</indexterm></index-range-start>. Now
that we have clarified that only one range can start in each indexterm,
the question arises whether to adopt this more standard form. See also
3b.

3b. Are we nesting <index-see> inside of <indexterm> either (i) because
of a perceived benefit in reducing the number of tags that may appear in
para or (ii) to preserve existing authoring practices?

4. The language ref text for see-also currently states:

  You can currently [enter] an indexterm in a map's metadata outside of
any content (map/topicmeta/keywords/indexterm). In the absence of
content context, an indexterm shall never generate page references, even
if it contains an index-see-also element.

This is a puzzle for me ... Why would we specify "never generate page
references"? Isn't the topicmeta for a map an external place where index
entries can be generated for a topic? As a best practice, topic-level
index entries that may vary among assemblies of topics should be located
in topicmeta, in which case generating page references would be
appropriate in applicable output formats.

Best wishes,

Bruce

-----Original Message-----
From: Chris Wong [mailto:cwong@idiominc.com]
Sent: Monday, August 07, 2006 11:10 PM
To: Grosso, Paul; dita@lists.oasis-open.org
Subject: RE: [dita] comments on indexing wording in dita 1.1 draft

I wrote the langref entry on index-see/index-see-also using a conref
that duplicates an extended discussion of the two elements for each of
these elements. The extended discussion described both elements,
including usage examples. But each element also had an <example> that
specifically described that element. At least, that was how I submitted
them. I think something went wrong during the transfer into the lang
ref. I'm attaching the original two writeups in rendered form so you can
see the intended material.

The index-see-also reference page had a typo where the first sentence
starts with "An <index-see> element...". It should have said
"index-see-also".

Concerning your comment about an indexterm within an index-see-also,
this usage is intentional. The use case is that if you want to have a
see-also refer to an indexterm that looks like

<indexterm>Goldfish<indexterm>feeding</indexterm></indexterm>

you can't just put the "see-also" refer to just "feeding", since this is
a nested index entry. So a see-also reference to the above index entry
would look like:

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

This in turn would be a child of indexterm. Perhaps I should have
included the enclosing indexterm to make it clearer:

<indexterm>Fish food
<index-see-also>Goldfish<indexterm>feeding</indexterm></index-see-also>
</indexterm>

Concerning the page ranges wording, the "excluding nested topics" refers
to the fact that a topic can contain other topics. So if you only
limited index ranges to start and end within a topic, it is still
possible to orphan an index range if the index range terminates in one
of the child topics that is in turn included by a map's topicref. 

That said, I have no objections to your proposed wording changes to the
indexing proposals.

Chris

-----Original Message-----
From: Grosso, Paul [mailto:pgrosso@ptc.com]
Sent: Wednesday, July 26, 2006 4:01 PM
To: dita@lists.oasis-open.org
Subject: [dita] comments on indexing wording in dita 1.1 draft

Here are my comments on the latest language spec regarding indexing.

index-see
---------
The example here is wrong in at least a couple ways:

1.  this is the index-see writeup, but the example refers to
    index-see-also
2.  the text (and Contains/Contained by sections) clearly indicate
    that index-see(-also) should be within an indexterm, but the
    example has the indexterm within the index-see-also

Due to these errors, I have not been able to give a careful review to
the rest of this section.


index-see-also
--------------
The first sentence of this section refers to index-see instead of
index-see-also.

The example refers to index-see instead of index-see-also.

Most of the body of this section is just a reference to the index-see
section, so I have not been able to give a careful review to this
section.


index-sort-as
-------------
See my question in another email thread:
http://lists.oasis-open.org/archives/dita/200607/msg00076.html

I'll try to suggest wording once I have an answer to that question.


index-range-start
-----------------
The second paragraph currently reads:

 Page ranges indicate where the index entry refers to  an extended
discussion that goes over a number of pages.
 This would typically be manifested as a page range like 34-36.
 This is distinguished from individual references over  consecutive
pages (34, 35, 36). A page range is indicated  by a pair of <indexterm>
elements, one with an  <index-range-start/> marker and another with an
<index-range-end/> marker.

I object to the statement that individual references must result in 34,
35, 36.  That is not what most of our users want.  They specifically
expect sequential page references (each generated by a pointwise
indexterm) to be merged in the resulting index.  Besides, this is a
style issue, and the DITA spec should not be specifying this.

Also, this wording doesn't really define "pair of <indexterm> elements"
clearly.

I suggest we replace this paragraph with something like:

 A page range can be used to generate an index entry for  an extended
discussion that goes over a number of pages.
 A page range is indicated
 by a "matching range pair" of <indexterm> elements.  Two  indexterm
elements form a "matching range pair" if their  textual contents are
identical, and the first one (in  document order) has an
<index-range-start/> child and  the second one has an <index-range-end/>
child.

Even this wording doesn't really cover the case if

<indexterm>cheese<index-range-start/>
  <indexterm>sheeps milk cheeses
    <indexterm>pecorino<index-range-start/></indexterm>
  </indexterm>
</indexterm>

is supposed to form a matching pair with

<indexterm>cheese<index-range-end/></indexterm>

but I'll wait to get an answer to my earlier email at
http://lists.oasis-open.org/archives/dita/200607/msg00075.html
before trying to tackle this.

----

The third paragraph currently reads:

 Due to the potential for orphaned range markers during  map assembly,
page ranges cannot span topics at the topic  level. Index ranges that
start within a topic must end in  the same topic, excluding nested
topics. Topic spanning  can only occur at the map level by inserting
indexterm  elements into map metadata.

I think I understand what we mean by "span topics" and "topics at the
topic level", but I don't understand just what we mean by "excluding
nested topics".

Along with the rewording I suggest above, I'm suggesting something like
the following to replace this text (though it's not complete since I
don't know how to translate "excluding nested topics"):

 Every index-range-start must be "properly paired" with  an
index-range-end.  For and index-range-start and  index-range-end pair to
be "properly paired", the  index-range-start's parent indexterm element
and the  index-range-end's parent indexterm element must be  a "matching
range pair" of <indexterm> elements.
 Furthermore:
 1. if the index-range-start occurs within a map file,
    it is properly paired with its index-range-end only if
    the index-range-end occurs within the same map file.
2.  if the index-range-start occurs within a topic,
    it is properly paired with its index-range-end only if
    the index-range-end occurs within the same topic
    [excluding nested topics].

I'll try to complete my suggested rewrite when I get an answer to my
email at http://lists.oasis-open.org/archives/dita/200607/msg00078.html

---

The fourth paragraph currently reads:

 When page range markers are not properly paired, the  following
recommended processing should result in few
 surprises:

 * If there is an indexterm with a range start marker but
   does not have a corresponding indexterm that ends the range,
   it should just generate a single page number reference in
   a book as if there was no range start marker.
 * On the other hand, an indexterm that terminates a range
   but has no corresponding indexterm that starts the range
   should be dropped entirely from output.

With my previous rewording, we can simplify this paragraph.
I also have an issue with the second bullet point above that I've
outlined at
http://lists.oasis-open.org/archives/dita/200607/msg00079.html

Here is my suggested rewording that reflects my suggestion in that
email:

 It is an error if an index-range-start is not "properly  paired" with
an index-range-end.  An implementation  should recover by ignoring any
improperly paired  index-range-start or index-range-end.

----

The fifth paragraph currently reads:

 An <indexterm> element in a topic prolog lies outside  of the content
flow. It essentially points to the topic  itself. Consequently, page
ranges in a topic prolog have  no meaning. If a processor encounters
either an  <index-range-start/> or <index-range-end/> element in  a
topic prolog, it will ignore them.

The phrase "points to the topic itself" is ambiguous.
That could still mean "a range starting at the start of the topic and
ending at the end of the topic" (which might make sense, but I thought
we decided otherwise).

I suggest we replace this paragraph with something like:

 An <indexterm> element in a topic prolog is defined  to be an indexterm
referencing the beginning of the  topic itself.  Furthermore,
index-range-start and  index-range-end elements within an indexterm
within a  topic prolog are ignored.

paul