Make a code-cleanup pass over the collations patch.

This patch is almost entirely cosmetic --- mostly cleaning up a lot of
neglected comments, and fixing code layout problems in places where the
patch made lines too long and then pgindent did weird things with that.
I did find a bug-of-omission in equalTupleDescs().

Author: tglsfdc

doc/src/sgml/catalogs.sgml

@@ -2159,8 +2159,8 @@
    (<structfield>collname</>, <structfield>collnamespace</>).
    <productname>PostgreSQL</productname> generally ignores all
    collations that do not have <structfield>collencoding</> equal to
-   either the current database's encoding or -1, and creation of new
-   entries matching an entry with <structfield>collencoding</> = -1
+   either the current database's encoding or -1, and creation of new entries
+   with the same name as an entry with <structfield>collencoding</> = -1
    is forbidden.  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.
@@ -6138,8 +6138,8 @@
        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.
+       collatable type can have some other collation OID, if one was
+       specified for the domain.
       </para></entry>
      </row>
 

doc/src/sgml/indices.sgml

@@ -1004,12 +1004,11 @@ SELECT am.amname AS index_method,
 
 
  <sect1 id="indexes-collations">
-  <title>Collations and Indexes</title>
+  <title>Indexes and Collations</title>
 
   <para>
-   An index can only support one collation for one column or
-   expression.  If multiple collations are of interest, multiple
-   indexes may be created.
+   An index can support only one collation per index column.
+   If multiple collations are of interest, multiple indexes may be needed.
   </para>
 
   <para>
@@ -1022,23 +1021,21 @@ CREATE TABLE test1c (
 
 CREATE INDEX test1c_content_index ON test1c (content);
 </programlisting>
-   The created index automatically follows the collation of the
-   underlying column, and so a query of the form
+   The index automatically uses the collation of the
+   underlying column.  So a query of the form
 <programlisting>
-SELECT * FROM test1c WHERE content = <replaceable>constant</replaceable>;
+SELECT * FROM test1c WHERE content &gt; <replaceable>constant</replaceable>;
 </programlisting>
-   could use the index.
-  </para>
-
-  <para>
-   If in addition, a query of the form, say,
+   could use the index, because the comparison will by default use the
+   collation of the column.  However, this index cannot accelerate queries
+   that involve some other collation.  So if queries of the form, say,
 <programlisting>
 SELECT * FROM test1c WHERE content &gt; <replaceable>constant</replaceable> COLLATE "y";
 </programlisting>
-   is of interest, an additional index could be created that supports
-   the <literal>"y"</literal> collation, like so:
+   are also of interest, an additional index could be created that supports
+   the <literal>"y"</literal> collation, like this:
 <programlisting>
-CREATE INDEX test1c_content_index ON test1c (content COLLATE "y");
+CREATE INDEX test1c_content_y_index ON test1c (content COLLATE "y");
 </programlisting>
   </para>
  </sect1>

doc/src/sgml/ref/create_collation.sgml

@@ -108,8 +108,8 @@ CREATE COLLATION <replaceable>name</replaceable> FROM <replaceable>existing_coll
      <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.
+       will have the same properties as the existing one, but it
+       will be an independent object.
       </para>
      </listitem>
     </varlistentry>
@@ -134,7 +134,8 @@ CREATE COLLATION <replaceable>name</replaceable> FROM <replaceable>existing_coll
   <title>Examples</title>
 
   <para>
-   To create a collation from the locale <literal>fr_FR.utf8</literal>
+   To create a collation from the operating system locale
+   <literal>fr_FR.utf8</literal>
    (assuming the current database encoding is <literal>UTF8</literal>):
 <programlisting>
 CREATE COLLATION french (LOCALE = 'fr_FR.utf8');

doc/src/sgml/ref/create_domain.sgml

@@ -90,7 +90,7 @@ CREATE DOMAIN <replaceable class="parameter">name</replaceable> [ AS ] <replacea
        <para>
         An optional collation for the domain.  If no collation is
         specified, the underlying data type's default collation is used.
-        The underlying type must be collatable when <literal>COLLATE</>
+        The underlying type must be collatable if <literal>COLLATE</>
         is specified.
        </para>
       </listitem>

doc/src/sgml/ref/create_index.sgml

@@ -188,9 +188,8 @@ CREATE [ UNIQUE ] INDEX [ CONCURRENTLY ] [ <replaceable class="parameter">name</
         The name of the collation to use for the index.  By default,
         the index uses the collation declared for the column to be
         indexed or the result collation of the expression to be
-        indexed.  Indexes with nondefault collations are
-        available for use by queries that involve expressions using
-        nondefault collations.
+        indexed.  Indexes with non-default collations can be useful for
+        queries that involve expressions using non-default collations.
        </para>
       </listitem>
      </varlistentry>
@@ -537,6 +536,13 @@ CREATE INDEX ON films ((lower(title)));
    will choose a name, typically <literal>films_lower_idx</>.)
   </para>
 
+  <para>
+   To create an index with non-default collation:
+<programlisting>
+CREATE INDEX title_idx_german ON films (title COLLATE "de_DE");
+</programlisting>
+  </para>
+
   <para>
    To create an index with non-default sort ordering of nulls:
 <programlisting>

doc/src/sgml/ref/create_type.sgml

@@ -355,10 +355,10 @@ CREATE TYPE <replaceable class="parameter">name</replaceable>
   </para>
 
   <para>
-   If the optional
+   If the optional boolean
    parameter <replaceable class="parameter">collatable</replaceable>
    is true, column definitions and expressions of the type may carry
-   collation information and allow the use of
+   collation information through use of
    the <literal>COLLATE</literal> clause.  It is up to the
    implementations of the functions operating on the type to actually
    make use of the collation information; this does not happen

doc/src/sgml/regress.sgml

@@ -238,7 +238,7 @@ gmake check LANG=C ENCODING=EUC_JP
   </sect2>
 
   <sect2>
-   <title>Extra tests</title>
+   <title>Extra Tests</title>
 
    <para>
     The regression test suite contains a few test files that are not
@@ -253,8 +253,8 @@ gmake check EXTRA_TESTS=numeric_big
 <screen>
 gmake check EXTRA_TESTS=collate.linux.utf8 LANG=en_US.utf8
 </screen>
-    This test works only on Linux/glibc platforms and when run in a
-    UTF-8 locale.
+    The <literal>collate.linux.utf8</> test works only on Linux/glibc
+    platforms, and only when run in a locale that uses UTF-8 encoding.
    </para>
   </sect2>
   </sect1>

src/backend/access/common/tupdesc.c

@@ -360,6 +360,8 @@ equalTupleDescs(TupleDesc tupdesc1, TupleDesc tupdesc2)
 			return false;
 		if (attr1->attinhcount != attr2->attinhcount)
 			return false;
+		if (attr1->attcollation != attr2->attcollation)
+			return false;
 		/* attacl and attoptions are not even present... */
 	}
 
@@ -611,7 +613,9 @@ BuildDescForRelation(List *schema)
  * BuildDescFromLists
  *
  * Build a TupleDesc given lists of column names (as String nodes),
- * column type OIDs, and column typmods.  No constraints are generated.
+ * column type OIDs, typmods, and collation OIDs.
+ *
+ * No constraints are generated.
  *
  * This is essentially a cut-down version of BuildDescForRelation for use
  * with functions returning RECORD.

src/backend/catalog/dependency.c

@@ -2227,14 +2227,16 @@ getObjectDescription(const ObjectAddress *object)
 		case OCLASS_COLLATION:
 			{
 				HeapTuple	collTup;
+				Form_pg_collation coll;
 
 				collTup = SearchSysCache1(COLLOID,
 										  ObjectIdGetDatum(object->objectId));
 				if (!HeapTupleIsValid(collTup))
 					elog(ERROR, "cache lookup failed for collation %u",
 						 object->objectId);
+				coll = (Form_pg_collation) GETSTRUCT(collTup);
 				appendStringInfo(&buffer, _("collation %s"),
-				NameStr(((Form_pg_collation) GETSTRUCT(collTup))->collname));
+								 NameStr(coll->collname));
 				ReleaseSysCache(collTup);
 				break;
 			}

src/backend/catalog/heap.c

@@ -644,7 +644,7 @@ AddNewAttributeTuples(Oid new_rel_oid,
 
 	/*
 	 * First we add the user attributes.  This is also a convenient place to
-	 * add dependencies on their datatypes.
+	 * add dependencies on their datatypes and collations.
 	 */
 	for (i = 0; i < natts; i++)
 	{
@@ -666,7 +666,9 @@ AddNewAttributeTuples(Oid new_rel_oid,
 		referenced.objectSubId = 0;
 		recordDependencyOn(&myself, &referenced, DEPENDENCY_NORMAL);
 
-		if (OidIsValid(attr->attcollation))
+		/* The default collation is pinned, so don't bother recording it */
+		if (OidIsValid(attr->attcollation) &&
+			attr->attcollation != DEFAULT_COLLATION_OID)
 		{
 			referenced.classId = CollationRelationId;
 			referenced.objectId = attr->attcollation;
@@ -921,7 +923,7 @@ AddNewRelationType(const char *typeName,
 				   -1,			/* typmod */
 				   0,			/* array dimensions for typBaseType */
 				   false,		/* Type NOT NULL */
-				   InvalidOid); /* typcollation */
+				   InvalidOid); /* rowtypes never have a collation */
 }
 
 /* --------------------------------
@@ -1183,7 +1185,7 @@ heap_create_with_catalog(const char *relname,
 				   -1,			/* typmod */
 				   0,			/* array dimensions for typBaseType */
 				   false,		/* Type NOT NULL */
-				   InvalidOid); /* typcollation */
+				   InvalidOid); /* rowtypes never have a collation */
 
 		pfree(relarrayname);
 	}

src/backend/catalog/index.c

@@ -351,7 +351,6 @@ ConstructTupleDescriptor(Relation heapRelation,
 			to->atthasdef = false;
 			to->attislocal = true;
 			to->attinhcount = 0;
-
 			to->attcollation = collationObjectId[i];
 		}
 		else
@@ -388,7 +387,6 @@ ConstructTupleDescriptor(Relation heapRelation,
 			to->attcacheoff = -1;
 			to->atttypmod = -1;
 			to->attislocal = true;
-
 			to->attcollation = collationObjectId[i];
 
 			ReleaseSysCache(tuple);
@@ -653,6 +651,7 @@ UpdateIndexRelation(Oid indexoid,
  * indexColNames: column names to use for index (List of char *)
  * accessMethodObjectId: OID of index AM to use
  * tableSpaceId: OID of tablespace to use
+ * collationObjectId: array of collation OIDs, one per index column
  * classObjectId: array of index opclass OIDs, one per index column
  * coloptions: array of per-index-column indoption settings
  * reloptions: AM-specific options
@@ -871,7 +870,8 @@ index_create(Relation heapRelation,
 	 * ----------------
 	 */
 	UpdateIndexRelation(indexRelationId, heapRelationId, indexInfo,
-	   collationObjectId, classObjectId, coloptions, isprimary, is_exclusion,
+						collationObjectId, classObjectId, coloptions,
+						isprimary, is_exclusion,
 						!deferrable,
 						!concurrent);
 
@@ -965,9 +965,11 @@ index_create(Relation heapRelation,
 		}
 
 		/* Store dependency on collations */
+		/* The default collation is pinned, so don't bother recording it */
 		for (i = 0; i < indexInfo->ii_NumIndexAttrs; i++)
 		{
-			if (OidIsValid(collationObjectId[i]))
+			if (OidIsValid(collationObjectId[i]) &&
+				collationObjectId[i] != DEFAULT_COLLATION_OID)
 			{
 				referenced.classId = CollationRelationId;
 				referenced.objectId = collationObjectId[i];
@@ -2445,8 +2447,8 @@ validate_index(Oid heapId, Oid indexId, Snapshot snapshot)
 	ivinfo.num_heap_tuples = heapRelation->rd_rel->reltuples;
 	ivinfo.strategy = NULL;
 
-	state.tuplesort = tuplesort_begin_datum(TIDOID,
-										  TIDLessOperator, InvalidOid, false,
+	state.tuplesort = tuplesort_begin_datum(TIDOID, TIDLessOperator,
+											InvalidOid, false,
 											maintenance_work_mem,
 											false);
 	state.htups = state.itups = state.tups_inserted = 0;

src/backend/catalog/pg_type.c

@@ -643,8 +643,9 @@ GenerateTypeDependencies(Oid typeNamespace,
 		recordDependencyOn(&myself, &referenced, DEPENDENCY_NORMAL);
 	}
 
-	/* Normal dependency from a domain to its base type's collation. */
-	if (OidIsValid(typeCollation))
+	/* Normal dependency from a domain to its collation. */
+	/* We know the default collation is pinned, so don't bother recording it */
+	if (OidIsValid(typeCollation) && typeCollation != DEFAULT_COLLATION_OID)
 	{
 		referenced.classId = CollationRelationId;
 		referenced.objectId = typeCollation;

src/backend/commands/indexcmds.c

@@ -350,7 +350,8 @@ DefineIndex(RangeVar *heapRelation,
 	collationObjectId = (Oid *) palloc(numberOfAttributes * sizeof(Oid));
 	classObjectId = (Oid *) palloc(numberOfAttributes * sizeof(Oid));
 	coloptions = (int16 *) palloc(numberOfAttributes * sizeof(int16));
-	ComputeIndexAttrs(indexInfo, collationObjectId, classObjectId, coloptions, attributeList,
+	ComputeIndexAttrs(indexInfo, collationObjectId, classObjectId,
+					  coloptions, attributeList,
 					  exclusionOpNames, relationId,
 					  accessMethodName, accessMethodId,
 					  amcanorder, isconstraint);
@@ -395,7 +396,8 @@ DefineIndex(RangeVar *heapRelation,
 	indexRelationId =
 		index_create(rel, indexRelationName, indexRelationId,
 					 indexInfo, indexColNames,
-			  accessMethodId, tablespaceId, collationObjectId, classObjectId,
+					 accessMethodId, tablespaceId,
+					 collationObjectId, classObjectId,
 					 coloptions, reloptions, primary,
 					 isconstraint, deferrable, initdeferred,
 					 allowSystemTableMods,