Index: doc/src/sgml/citext.sgml
===================================================================
RCS file: /projects/cvsroot/pgsql/doc/src/sgml/citext.sgml,v
retrieving revision 1.1
diff -u -r1.1 citext.sgml
--- doc/src/sgml/citext.sgml	29 Jul 2008 18:31:20 -0000	1.1
+++ doc/src/sgml/citext.sgml	12 Sep 2008 16:48:34 -0000
@@ -96,6 +96,72 @@
  </sect2>
 
  <sect2>
+  <title>String Comparison Notes</title>
+  <para>
+   In order to emulate a case-insentive collation as closely as possible, a
+   number all of the comparision operators and functions have been overridden
+   to support <type>citext</>. So, for example, the regular expression
+   operators <literal>~</> and <literal>~*</> exhibit the same behavior, which
+   is to say that they both compare case-insensitively. The same is true
+   for <literal>!~</> and <literal>!~*</>, as well as for the
+   <literal>LIKE</> operators <literal>~~</> and <literal>~~*</>, and
+   <literal>!~~</> and <literal>!~~*</>. If you'd like to match
+   case-sensitively, you can always cast to <type>text</> before comparing.
+  </para>
+
+  <para>
+   The same holds true for comparision functions. All of the following
+   functions behave case-insensitively if either of their comparators
+   is <type>citext</>:
+  </para>
+
+  <itemizedlist>
+   <listitem>
+    <para>
+      <function>regexp_replace()</>
+    </para>
+   </listitem>
+   <listitem>
+    <para>
+      <function>regexp_split_to_array()</>
+    </para>
+   </listitem>
+   <listitem>
+    <para>
+      <function>regexp_split_to_table()</>
+    </para>
+   </listitem>
+   <listitem>
+    <para>
+      <function>replace()</>
+    </para>
+   </listitem>
+   <listitem>
+    <para>
+      <function>split_part()</>
+    </para>
+   </listitem>
+   <listitem>
+    <para>
+      <function>strpos()</>
+    </para>
+   </listitem>
+   <listitem>
+    <para>
+      <function>translate()</>
+    </para>
+   </listitem>
+  </itemizedlist>
+
+  <para>
+   For the regexp functions, if you want to match case-sensitively, you can
+   always use the <quote>c</> flag to force a case-senstive match. Otherwise,
+   you must cast to <type>text</> before calling a function.
+  </para>
+
+ </sect2>
+
+ <sect2>
   <title>Limitations</title>
 
    <itemizedlist>
@@ -116,60 +182,6 @@
 
     <listitem>
      <para>
-      The pattern-matching comparison operators, such as <literal>LIKE</>,
-      <literal>~</>, <literal>~~</>, <literal>!~</>, <literal>!~~</>, etc.,
-      have been overloaded to make case-insensitive comparisons when their
-      left-hand argument is of type <type>citext</>.  However, related
-      functions have not been changed, including:
-     </para>
-
-     <itemizedlist>
-      <listitem>
-       <para>
-         <function>regexp_replace()</>
-       </para>
-      </listitem>
-      <listitem>
-       <para>
-         <function>regexp_split_to_array()</>
-       </para>
-      </listitem>
-      <listitem>
-       <para>
-         <function>regexp_split_to_table()</>
-       </para>
-      </listitem>
-      <listitem>
-       <para>
-         <function>replace()</>
-       </para>
-      </listitem>
-      <listitem>
-       <para>
-         <function>split_part()</>
-       </para>
-      </listitem>
-      <listitem>
-       <para>
-         <function>strpos()</>
-       </para>
-      </listitem>
-      <listitem>
-       <para>
-         <function>translate()</>
-       </para>
-      </listitem>
-     </itemizedlist>
-
-     <para>
-      Of course, for the regular expression functions, you can specify
-      case-insensitive comparisons in their <parameter>flags</> arguments, but
-      the same cannot be done for the the non-regexp functions.
-     </para>
-    </listitem>
-
-    <listitem>
-     <para>
        <type>citext</> is not as efficient as <type>text</> because the
        operator functions and the btree comparison functions must make copies
        of the data and convert it to lower case for comparisons. It is,