document backward compatibility issue possibility for empty type order
@@ -197,6 +197,13 @@ under the License.
</section>
<section id="uv3.backwards_compatibility.iterator">
+ <title>Subtle differences in iteration</title>
+
+ <para>There are a couple of areas where iteration order may be
+ different. These are areas where the previous iteration order was
+ unspecified.</para>
+
+ <section id="uv3.backwards_compatibility.iterator.undefined">
<title>Iteration Order for equal Feature Structures</title>
<para>When iterating using a sorted index, the sort order is determined by the Index's comparator.
@@ -212,6 +219,22 @@ under the License.
switching to version 3.</para>
</section>
+ <section id="uv3.backwards_compatibility.iterator.typeordermissing">
+ <title>Iteration Order with type ordering, where no type ordering has been specified</title>
+
+ <para>When defining Sorted indexes, one of the keys you can specify is the
+ type order. This allows using type priorities to specify which type
+ comes before another type in the order. The build-in Annotation index,
+ for example, sorts using the 3 keys of begin, end, and type order.</para>
+
+ <para>Type order only works when one or more type ordering priorities are
+ specified. In Version 3, if no type ordering priorities are specified,
+ then no type ordering is done. This may differ in the results obtained
+ with version 2, which was doing some kind of default (unknown) type ordering in this
+ case.</para>
+ </section>
+ </section>
+
<section id="uv3.backwards_compatibility.typesystem_sharing">
<title>Type System sharing</title>
