Fix incorrect example in CREATE INDEX reference page, per Josh Kupershmidt.

Also fix and uncomment an old example of creating a GIST index, and make
a couple of other minor editorial adjustments.

doc/src/sgml/ref/create_index.sgml

@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/create_index.sgml,v 1.72 2009/12/23 17:41:43 tgl Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/create_index.sgml,v 1.73 2010/03/17 15:55:50 tgl Exp $
 PostgreSQL documentation
 -->
 
@@ -266,10 +266,10 @@ CREATE [ UNIQUE ] INDEX [ CONCURRENTLY ] [ <replaceable class="parameter">name</
    <title id="SQL-CREATEINDEX-storage-parameters-title">Index Storage Parameters</title>
 
    <para>
-    The <literal>WITH</> clause can specify <firstterm>storage parameters</>
-    for indexes.  Each index method can have its own set of allowed storage
-    parameters.  The <literal>B-tree</literal>, <literal>hash</literal> and
-    <literal>GiST</literal> built-in index methods all accept a single parameter:
+    The optional <literal>WITH</> clause specifies <firstterm>storage
+    parameters</> for the index.  Each index method has its own set of allowed
+    storage parameters.  The B-tree, hash and GiST index methods all accept a
+    single parameter:
    </para>
 
    <variablelist>
@@ -281,10 +281,11 @@ CREATE [ UNIQUE ] INDEX [ CONCURRENTLY ] [ <replaceable class="parameter">name</
       The fillfactor for an index is a percentage that determines how full
       the index method will try to pack index pages.  For B-trees, leaf pages
       are filled to this percentage during initial index build, and also
-      when extending the index at the right (largest key values).  If pages
+      when extending the index at the right (adding new largest key values).
+      If pages
       subsequently become completely full, they will be split, leading to
       gradual degradation in the index's efficiency.  B-trees use a default
-      fillfactor of 90, but any value from 10 to 100 can be selected.
+      fillfactor of 90, but any integer value from 10 to 100 can be selected.
       If the table is static then fillfactor 100 is best to minimize the
       index's physical size, but for heavily updated tables a smaller
       fillfactor is better to minimize the need for page splits.  The
@@ -297,7 +298,7 @@ CREATE [ UNIQUE ] INDEX [ CONCURRENTLY ] [ <replaceable class="parameter">name</
    </variablelist>
 
    <para>
-    <literal>GIN</literal> indexes accept a different parameter:
+    GIN indexes accept a different parameter:
    </para>
 
    <variablelist>
@@ -373,7 +374,7 @@ CREATE [ UNIQUE ] INDEX [ CONCURRENTLY ] [ <replaceable class="parameter">name</
     command will fail but leave behind an <quote>invalid</> index. This index
     will be ignored for querying purposes because it might be incomplete;
     however it will still consume update overhead. The <application>psql</>
-    <command>\d</> command will mark such an index as <literal>INVALID</>:
+    <command>\d</> command will report such an index as <literal>INVALID</>:
 
 <programlisting>
 postgres=# \d tab
@@ -457,8 +458,8 @@ Indexes:
   <para>
    For index methods that support ordered scans (currently, only B-tree),
    the optional clauses <literal>ASC</>, <literal>DESC</>, <literal>NULLS
-   FIRST</>, and/or <literal>NULLS LAST</> can be specified to reverse
-   the normal sort direction of the index.  Since an ordered index can be
+   FIRST</>, and/or <literal>NULLS LAST</> can be specified to modify
+   the sort ordering of the index.  Since an ordered index can be
    scanned either forward or backward, it is not normally useful to create a
    single-column <literal>DESC</> index &mdash; that sort ordering is already
    available with a regular index.  The value of these options is that
@@ -539,7 +540,7 @@ CREATE UNIQUE INDEX title_idx ON films (title) WITH (fillfactor = 70);
   <para>
    To create a <acronym>GIN</> index with fast updates disabled:
 <programlisting>
-CREATE INDEX gin_idx ON documents_table (locations) WITH (fastupdate = off);
+CREATE INDEX gin_idx ON documents_table USING gin (locations) WITH (fastupdate = off);
 </programlisting>
   </para>
 
@@ -552,22 +553,17 @@ CREATE INDEX code_idx ON films (code) TABLESPACE indexspace;
 </programlisting>
   </para>
 
-<!--
-<comment>
-Is this example correct?
-</comment>
   <para>
    To create a GiST index on a point attribute so that we
    can efficiently use box operators on the result of the
    conversion function:
   <programlisting>
 CREATE INDEX pointloc
-    ON points USING GIST (point2box(location) box_ops);
+    ON points USING gist (box(location,location));
 SELECT * FROM points
-    WHERE point2box(points.pointloc) = boxes.box;
+    WHERE box(location,location) &amp;&amp; '(0,0),(1,1)'::box;
   </programlisting>
   </para>
--->
 
   <para>
    To create an index without locking out writes to the table: