Assorted editing for collation documentation.

I made a pass over this to familiarize myself with the feature, and found
some things that could be improved.

doc/src/sgml/catalogs.sgml

@@ -1128,8 +1128,8 @@
       <entry><type>oid</type></entry>
       <entry><literal><link linkend="catalog-pg-collation"><structname>pg_collation</structname></link>.oid</literal></entry>
       <entry>
-       The defined collation of the column, zero if the column does
-       not have a collatable type.
+       The defined collation of the column, or zero if the column is
+       not of a collatable datatype.
       </entry>
      </row>
 
@@ -2088,7 +2088,7 @@
    The catalog <structname>pg_collation</structname> describes the
    available collations, which are essentially mappings from an SQL
    name to operating system locale categories.
-   See <xref linkend="locale"> for more information.
+   See <xref linkend="collation"> for more information.
   </para>
 
   <table>
@@ -2132,38 +2132,48 @@
       <entry><structfield>collencoding</structfield></entry>
       <entry><type>int4</type></entry>
       <entry></entry>
-      <entry>
-       Encoding to which the collation is applicable.  SQL-level
-       commands such as <command>ALTER COLLATION</command> only
-       operate on the collation belonging to the current database
-       encoding.  But this field is necessary because when this
-       catalog is initialized, the encoding of future databases is not
-       yet known.  For practical purposes, collations that do not
-       match the current database encoding should be considered
-       invalid or invisible.  It could be useful, however, to create
-       collations whose encoding does not match the database encoding
-       in template databases.  This would currently have to be done
-       manually.
-      </entry>
+      <entry>Encoding to which the collation is applicable</entry>
      </row>
 
      <row>
       <entry><structfield>collcollate</structfield></entry>
       <entry><type>name</type></entry>
       <entry></entry>
-      <entry>LC_COLLATE for this collation object</entry>
+      <entry><symbol>LC_COLLATE</> for this collation object</entry>
      </row>
 
      <row>
       <entry><structfield>collctype</structfield></entry>
       <entry><type>name</type></entry>
       <entry></entry>
-      <entry>LC_CTYPE for this collation object</entry>
+      <entry><symbol>LC_CTYPE</> for this collation object</entry>
      </row>
     </tbody>
    </tgroup>
   </table>
 
+  <para>
+   Note that the unique key on this catalog is (<structfield>collname</>,
+   <structfield>collencoding</>, <structfield>collnamespace</>) not just
+   (<structfield>collname</>, <structfield>collnamespace</>).
+   <productname>PostgreSQL</productname> generally ignores all
+   collations not belonging to the current database's encoding; therefore
+   it is sufficient to use a qualified SQL name
+   (<replaceable>schema</>.<replaceable>name</>) to identify a collation,
+   even though this is not unique according to the catalog definition.
+   The current database's encoding is automatically used as an additional
+   lookup key.  The reason for defining the catalog this way is that
+   <application>initdb</> fills it in at cluster initialization time with
+   entries for all locales available on the system, so it must be able to
+   hold entries for all encodings that might ever be used in the cluster.
+  </para>
+
+  <para>
+   In the <literal>template0</> database, it could be useful to create
+   collations whose encoding does not match the database encoding,
+   since they could match the encodings of databases later cloned from
+   <literal>template0</>.  This would currently have to be done manually.
+  </para>
  </sect1>
 
  <sect1 id="catalog-pg-conversion">
@@ -6123,12 +6133,11 @@
       <entry><literal><link linkend="catalog-pg-collation"><structname>pg_collation</structname></link>.oid</literal></entry>
       <entry><para>
        <structfield>typcollation</structfield> specifies the collation
-       of the type.  If a type does not support collations, this will
-       be zero, collation analysis at parse time is skipped, and
-       the use of <literal>COLLATE</literal> clauses with the type is
-       invalid.  A base type that supports collations will have
-       <symbol>DEFAULT_COLLATION_OID</symbol> here.  A domain can have
-       another collation OID, if one was defined for the domain.
+       of the type.  If the type does not support collations, this will
+       be zero.  A base type that supports collations will have
+       <symbol>DEFAULT_COLLATION_OID</symbol> here.  A domain over a
+       collatable type can have some other collation OID, if one was defined
+       for the domain.
       </para></entry>
      </row>
 

doc/src/sgml/ref/create_collation.sgml

@@ -21,7 +21,7 @@
 CREATE COLLATION <replaceable>name</replaceable> (
     [ LOCALE = <replaceable>locale</replaceable>, ]
     [ LC_COLLATE = <replaceable>lc_collate</replaceable>, ]
-    [ LC_CTYPE = <replaceable>lc_ctype</replaceable>, ]
+    [ LC_CTYPE = <replaceable>lc_ctype</replaceable> ]
 )
 CREATE COLLATION <replaceable>name</replaceable> FROM <replaceable>existing_collation</replaceable>
 </synopsis>
@@ -32,7 +32,8 @@ CREATE COLLATION <replaceable>name</replaceable> FROM <replaceable>existing_coll
 
   <para>
    <command>CREATE COLLATION</command> defines a new collation using
-   the specified operating system locales or from an existing collation.
+   the specified operating system locale settings,
+   or by copying an existing collation.
  </para>
 
   <para>
@@ -53,26 +54,14 @@ CREATE COLLATION <replaceable>name</replaceable> FROM <replaceable>existing_coll
       <para>
        The name of the collation. The collation name can be
        schema-qualified. If it is not, the collation is defined in the
-       current schema. The collation name must be unique within a
+       current schema. The collation name must be unique within that
        schema.  (The system catalogs can contain collations with the
-       same name for other encodings, but these are not usable if the
+       same name for other encodings, but these are ignored if the
        database encoding does not match.)
       </para>
      </listitem>
     </varlistentry>
 
-    <varlistentry>
-     <term><replaceable>existing_collation</replaceable></term>
-
-     <listitem>
-      <para>
-       The name of an existing collation to copy.  The new collation
-       will have the same properties as the existing one, but they
-       will become independent objects.
-      </para>
-     </listitem>
-    </varlistentry>
-
     <varlistentry>
      <term><replaceable>locale</replaceable></term>
 
@@ -80,7 +69,7 @@ CREATE COLLATION <replaceable>name</replaceable> FROM <replaceable>existing_coll
       <para>
        This is a shortcut for setting <symbol>LC_COLLATE</symbol>
        and <symbol>LC_CTYPE</symbol> at once.  If you specify this,
-       you cannot specify either of the other parameters.
+       you cannot specify either of those parameters.
       </para>
      </listitem>
     </varlistentry>
@@ -112,6 +101,18 @@ CREATE COLLATION <replaceable>name</replaceable> FROM <replaceable>existing_coll
       </para>
      </listitem>
     </varlistentry>
+
+    <varlistentry>
+     <term><replaceable>existing_collation</replaceable></term>
+
+     <listitem>
+      <para>
+       The name of an existing collation to copy.  The new collation
+       will have the same properties as the existing one, but they
+       will become independent objects.
+      </para>
+     </listitem>
+    </varlistentry>
    </variablelist>
  </refsect1>
 
@@ -145,8 +146,8 @@ CREATE COLLATION french (LOCALE = 'fr_FR.utf8');
 <programlisting>
 CREATE COLLATION german FROM "de_DE";
 </programlisting>
-   This can be convenient to be able to use operating-system
-   independent collation names in applications.
+   This can be convenient to be able to use operating-system-independent
+   collation names in applications.
   </para>
  </refsect1>
 

doc/src/sgml/ref/drop_collation.sgml

@@ -94,7 +94,7 @@ DROP COLLATION german;
   <para>
    The <command>DROP COLLATION</command> command conforms to the
    <acronym>SQL</acronym> standard, apart from the <literal>IF
-   EXISTS</> option, which is a <productname>PostgreSQL</> extension..
+   EXISTS</> option, which is a <productname>PostgreSQL</> extension.
   </para>
  </refsect1>