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

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


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:


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

<indexterm>Fish food

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.


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

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

1.  this is the index-see writeup, but the example refers to
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.

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.

See my question in another email thread:

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

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>sheeps milk cheeses

is supposed to form a matching pair with


but I'll wait to get an answer to my earlier email at
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.
 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


The fourth paragraph currently reads:

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

 * 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

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.




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