Update citext's documentation to match the recently-applied patch,

per David Wheeler.

doc/src/sgml/citext.sgml

-<!-- $PostgreSQL: pgsql/doc/src/sgml/citext.sgml,v 1.1 2008/07/29 18:31:20 tgl Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/citext.sgml,v 1.2 2008/09/12 18:29:49 tgl Exp $ -->
 
 <sect1 id="citext">
  <title>citext</title>
@@ -96,31 +96,23 @@
  </sect2>
 
  <sect2>
-  <title>Limitations</title>
-
-   <itemizedlist>
-    <listitem>
+  <title>String Comparison Behavior</title>
   <para>
-      <type>citext</>'s behavior depends on
-      the <literal>LC_CTYPE</> setting of your database. How it compares
-      values is therefore determined when
-      <application>initdb</> is run to create the cluster. It is not truly
-      case-insensitive in the terms defined by the Unicode standard.
-      Effectively, what this means is that, as long as you're happy with your
-      collation, you should be happy with <type>citext</>'s comparisons. But
-      if you have data in different languages stored in your database, users
-      of one language may find their query results are not as expected if the
-      collation is for another language.
+   In order to emulate a case-insensitive collation as closely as possible,
+   there are <type>citext</>-specific versions of a number of the comparison
+   operators and functions.  So, for example, the regular expression
+   operators <literal>~</> and <literal>~*</> exhibit the same behavior when
+   applied to <type>citext</>: 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>
-    </listitem>
 
-    <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:
+   Similarly, all of the following functions perform matching
+   case-insensitively if their arguments are <type>citext</>:
   </para>
 
   <itemizedlist>
@@ -162,9 +154,30 @@
   </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.
+   For the regexp functions, if you want to match case-sensitively, you can
+   specify the <quote>c</> flag to force a case-sensitive match.  Otherwise,
+   you must cast to <type>text</> before using one of these functions if
+   you want case-sensitive behavior.
+  </para>
+
+ </sect2>
+
+ <sect2>
+  <title>Limitations</title>
+
+   <itemizedlist>
+    <listitem>
+     <para>
+      <type>citext</>'s behavior depends on
+      the <literal>LC_CTYPE</> setting of your database. How it compares
+      values is therefore determined when
+      <application>initdb</> is run to create the cluster. It is not truly
+      case-insensitive in the terms defined by the Unicode standard.
+      Effectively, what this means is that, as long as you're happy with your
+      collation, you should be happy with <type>citext</>'s comparisons. But
+      if you have data in different languages stored in your database, users
+      of one language may find their query results are not as expected if the
+      collation is for another language.
      </para>
     </listitem>
 
@@ -178,17 +191,6 @@
      </para>
     </listitem>
 
-    <listitem>
-     <para>
-      <productname>PostgreSQL</> supports casting between <type>text</>
-      and any other type (even non-string types) by using the other type's
-      I/O functions.  This doesn't work with <type>citext</>.  However,
-      you can cast via I/O functions in two steps, for example
-      <literal><replaceable>somevalue</>::text::citext</literal> or
-      <literal><replaceable>citextvalue</>::text::<replaceable>sometype</></literal>.
-     </para>
-    </listitem>
-
     <listitem>
      <para>
       <type>citext</> doesn't help much if you need data to compare