Misc documentation fixes.
authorHeikki Linnakangas <heikki.linnakangas@iki.fi>
Mon, 19 Oct 2020 16:28:54 +0000 (19:28 +0300)
committerHeikki Linnakangas <heikki.linnakangas@iki.fi>
Mon, 19 Oct 2020 16:29:56 +0000 (19:29 +0300)
- Misc grammar and punctuation fixes.

- Stylistic cleanup: use spaces between function arguments and JSON fields
  in examples. For example "foo(a,b)" -> "foo(a, b)". Add semicolon after
  last END in a few PL/pgSQL examples that were missing them.

- Make sentence that talked about "..." and ".." operators more clear,
  by avoiding to end the sentence with "..". That makes it look the same
  as "..."

- Fix syntax description for HAVING: HAVING conditions cannot be repeated

Patch by Justin Pryzby, per Yaroslav Schekin's report. Backpatch to all
supported versions, to the extent that the patch applies easily.

Discussion: https://www.postgresql.org/message-id/20201005191922.GE17626%40telsasoft.com

17 files changed:
doc/src/sgml/catalogs.sgml
doc/src/sgml/config.sgml
doc/src/sgml/dblink.sgml
doc/src/sgml/func.sgml
doc/src/sgml/gin.sgml
doc/src/sgml/high-availability.sgml
doc/src/sgml/indexam.sgml
doc/src/sgml/isn.sgml
doc/src/sgml/mvcc.sgml
doc/src/sgml/parallel.sgml
doc/src/sgml/plpgsql.sgml
doc/src/sgml/protocol.sgml
doc/src/sgml/ref/select.sgml
doc/src/sgml/ref/select_into.sgml
doc/src/sgml/rules.sgml
doc/src/sgml/seg.sgml
doc/src/sgml/textsearch.sgml

index 849ba347e2335611e10a78ddc10e10c9205e8db2..75622250737cddd6651ccb58b7d48b63864588e1 100644 (file)
       <entry><type>bool</type></entry>
       <entry>
        Role can log in. That is, this role can be given as the initial
-       session authorization identifier
+       session authorization identifier.
       </entry>
      </row>
 
index 8196a2f923cc57e3a4ffd850509818d5249e0fe3..48b2a412b6375b7a510d9842f0acd96441898096 100644 (file)
@@ -8817,8 +8817,8 @@ LOG:  CleanUpLock: deleting: lock(0xb7acd844) id(24688,24696,0,0,0,1)
       </term>
       <listitem>
        <para>
-        If set, do not trace locks for tables below this OID. (use to avoid
-        output on system tables)
+        If set, do not trace locks for tables below this OID (used to avoid
+        output on system tables).
        </para>
        <para>
         This parameter is only available if the <symbol>LOCK_DEBUG</symbol>
index 97dc3b81292871963c83855ee1930343812bba7a..0141c4b9908d0c7b62d2e44d2b57c4ecb76d22d9 100644 (file)
@@ -167,7 +167,7 @@ SELECT dblink_connect('myconn', 'fdtest');
  OK
 (1 row)
 
-SELECT * FROM dblink('myconn','SELECT * FROM foo') AS t(a int, b text, c text[]);
+SELECT * FROM dblink('myconn', 'SELECT * FROM foo') AS t(a int, b text, c text[]);
  a  | b |       c       
 ----+---+---------------
   0 | a | {a0,b0,c0}
@@ -616,7 +616,7 @@ dblink_exec(text sql [, bool fail_on_error]) returns text
       <para>
        The SQL command that you wish to execute in the remote database,
        for example
-       <literal>insert into foo values(0,'a','{"a0","b0","c0"}')</literal>.
+       <literal>insert into foo values(0, 'a', '{"a0","b0","c0"}')</literal>.
       </para>
      </listitem>
     </varlistentry>
@@ -653,7 +653,7 @@ SELECT dblink_connect('dbname=dblink_test_standby');
  OK
 (1 row)
 
-SELECT dblink_exec('insert into foo values(21,''z'',''{"a0","b0","c0"}'');');
+SELECT dblink_exec('insert into foo values(21, ''z'', ''{"a0","b0","c0"}'');');
    dblink_exec
 -----------------
  INSERT 943366 1
@@ -665,7 +665,7 @@ SELECT dblink_connect('myconn', 'dbname=regression');
  OK
 (1 row)
 
-SELECT dblink_exec('myconn', 'insert into foo values(21,''z'',''{"a0","b0","c0"}'');');
+SELECT dblink_exec('myconn', 'insert into foo values(21, ''z'', ''{"a0","b0","c0"}'');');
    dblink_exec
 ------------------
  INSERT 6432584 1
index 0028e53ef1ed73499fb8babc32a135f44b4a1333..f055973491b4f105369297cf7a03c6db31742df9 100644 (file)
@@ -20987,7 +20987,7 @@ BEGIN
                      obj.object_name,
                      obj.object_identity;
     END LOOP;
-END
+END;
 $$;
 CREATE EVENT TRIGGER test_event_trigger_for_drops
    ON sql_drop
index cc7cd1ed2c4cc9152355f7f2e825919324581110..42eef1639cf0c7057a878b9b2bfd2b115b298e5a 100644 (file)
     </para>
     <para>
      <varname>gin_pending_list_limit</varname> can be overridden for individual
-     GIN indexes by changing storage parameters, and which allows each
+     GIN indexes by changing storage parameters, which allows each
      GIN index to have its own cleanup threshold.
      For example, it's possible to increase the threshold only for the GIN
      index which can be updated heavily, and decrease it otherwise.
index 72b424170d96c04aba63f92faa83ca68b5f2e603..46d29c820bd8baf3ca5153e99dcea13f5d43fe1e 100644 (file)
@@ -1499,7 +1499,7 @@ synchronous_standby_names = 'ANY 2 (s1, s2, s3)'
     Note that in this mode, the server will apply WAL one file at a
     time, so if you use the standby server for queries (see Hot Standby),
     there is a delay between an action in the master and when the
-    action becomes visible in the standby, corresponding the time it takes
+    action becomes visible in the standby, corresponding to the time it takes
     to fill up the WAL file. <varname>archive_timeout</varname> can be used to make that delay
     shorter. Also note that you can't combine streaming replication with
     this method.
index 40b9d78e0fe95cf5bf2f84f68751b0d74af88f77..da3d423abd513a56b4a0ee4cddc0a8d2f40cc211 100644 (file)
@@ -543,7 +543,7 @@ amgettuple (IndexScanDesc scan,
    will pass the caller's snapshot test.  On success, <function>amgettuple</function>
    must also set <literal>scan-&gt;xs_recheck</literal> to true or false.
    False means it is certain that the index entry matches the scan keys.
-   true means this is not certain, and the conditions represented by the
+   True means this is not certain, and the conditions represented by the
    scan keys must be rechecked against the heap tuple after fetching it.
    This provision supports <quote>lossy</quote> index operators.
    Note that rechecking will extend only to the scan conditions; a partial
index 130404172640e7dac14b8572e0c7e738bde98851..75964cb459592b83e1c6c70d1df73a58dbae2388 100644 (file)
@@ -14,7 +14,7 @@
   hard-coded list of prefixes; this list of prefixes is also used to hyphenate
   numbers on output.  Since new prefixes are assigned from time to time, the
   list of prefixes may be out of date.  It is hoped that a future version of
-  this module will obtained the prefix list from one or more tables that
+  this module will obtain the prefix list from one or more tables that
   can be easily updated by users as needed; however, at present, the
   list can only be updated by modifying the source code and recompiling.
   Alternatively, prefix validation and hyphenation support may be
index b64f79c49e3fc18fcc92a4393084f34f595c1915..6341174f5d6e0abfeb9e133bfc8931feaa685086 100644 (file)
@@ -1239,7 +1239,7 @@ ERROR:  could not serialize access due to read/write dependencies among transact
         <para>
          The <literal>FOR UPDATE</literal> lock mode
          is also acquired by any <command>DELETE</command> on a row, and also by an
-         <command>UPDATE</command> that modifies the values on certain columns.  Currently,
+         <command>UPDATE</command> that modifies the values of certain columns.  Currently,
          the set of columns considered for the <command>UPDATE</command> case are those that
          have a unique index on them that can be used in a foreign key (so partial
          indexes and expressional indexes are not considered), but this may change
index 891586f83d4dc0971913a15e6d16f7d3e6691ef5..3d860788406aca1f5995b84f0167e90199a2cd01 100644 (file)
@@ -496,7 +496,7 @@ EXPLAIN SELECT * FROM pgbench_accounts WHERE filler LIKE '%x%';
   </para>
 
   <para>
-    The following operations are always parallel restricted.
+    The following operations are always parallel restricted:
   </para>
 
   <itemizedlist>
index b139f76920b9177fb6252b9d2328ab72984298e6..93dacabc1610ccaeedd28cc098bba3fec4f5077e 100644 (file)
@@ -1121,7 +1121,7 @@ BEGIN
     SELECT users.userid INTO STRICT userid
         FROM users WHERE users.username = get_userid.username;
     RETURN userid;
-END
+END;
 $$ LANGUAGE plpgsql;
 </programlisting>
      On failure, this function might produce an error message such as
@@ -1799,7 +1799,7 @@ BEGIN
         RETURN NEXT r; -- return current row of SELECT
     END LOOP;
     RETURN;
-END
+END;
 $BODY$
 LANGUAGE plpgsql;
 
@@ -1827,7 +1827,7 @@ BEGIN
     END IF;
 
     RETURN;
- END
+ END;
 $BODY$
 LANGUAGE plpgsql;
 
@@ -1901,7 +1901,7 @@ DECLARE myvar int := 5;
 BEGIN
   CALL triple(myvar);
   RAISE NOTICE 'myvar = %', myvar;  -- prints 15
-END
+END;
 $$;
 </programlisting>
     </para>
@@ -3501,7 +3501,7 @@ BEGIN
             ROLLBACK;
         END IF;
     END LOOP;
-END
+END;
 $$;
 
 CALL transaction_test1();
@@ -5103,7 +5103,7 @@ DECLARE
 f1 int;
 BEGIN
 RETURN f1;
-END
+END;
 $$ LANGUAGE plpgsql;
 WARNING:  variable "f1" shadows a previously defined variable
 LINE 3: f1 int;
index d6f111e28f76bb0a26684e2a3d9042640f96183d..9b9e824628142a08fb3f0be737c5a592ce56fb38 100644 (file)
@@ -2730,7 +2730,7 @@ The commands accepted in replication mode are:
   <para>
    Every sent transaction contains zero or more DML messages (Insert,
    Update, Delete). In case of a cascaded setup it can also contain Origin
-   messages. The origin message indicated that the transaction originated on
+   messages. The origin message indicates that the transaction originated on
    different replication node. Since a replication node in the scope of logical
    replication protocol can be pretty much anything, the only identifier
    is the origin name. It's downstream's responsibility to handle this as
index c34e3621939dcaa0198b15ddf03f12e764cb62e5..1e0f09e6623fbdc2f96398e5c7f7f37b19db1f4f 100644 (file)
@@ -38,7 +38,7 @@ SELECT [ ALL | DISTINCT [ ON ( <replaceable class="parameter">expression</replac
     [ FROM <replaceable class="parameter">from_item</replaceable> [, ...] ]
     [ WHERE <replaceable class="parameter">condition</replaceable> ]
     [ GROUP BY <replaceable class="parameter">grouping_element</replaceable> [, ...] ]
-    [ HAVING <replaceable class="parameter">condition</replaceable> [, ...] ]
+    [ HAVING <replaceable class="parameter">condition</replaceable> ]
     [ WINDOW <replaceable class="parameter">window_name</replaceable> AS ( <replaceable class="parameter">window_definition</replaceable> ) [, ...] ]
     [ { UNION | INTERSECT | EXCEPT } [ ALL | DISTINCT ] <replaceable class="parameter">select</replaceable> ]
     [ ORDER BY <replaceable class="parameter">expression</replaceable> [ ASC | DESC | USING <replaceable class="parameter">operator</replaceable> ] [ NULLS { FIRST | LAST } ] [, ...] ]
index 6c1a25f5ed59818fc859f30bbba424070e823f42..b030f85eacc91332729f8fb6e5c96e91035458a0 100644 (file)
@@ -28,7 +28,7 @@ SELECT [ ALL | DISTINCT [ ON ( <replaceable class="parameter">expression</replac
     [ FROM <replaceable class="parameter">from_item</replaceable> [, ...] ]
     [ WHERE <replaceable class="parameter">condition</replaceable> ]
     [ GROUP BY <replaceable class="parameter">expression</replaceable> [, ...] ]
-    [ HAVING <replaceable class="parameter">condition</replaceable> [, ...] ]
+    [ HAVING <replaceable class="parameter">condition</replaceable> ]
     [ WINDOW <replaceable class="parameter">window_name</replaceable> AS ( <replaceable class="parameter">window_definition</replaceable> ) [, ...] ]
     [ { UNION | INTERSECT | EXCEPT } [ ALL | DISTINCT ] <replaceable class="parameter">select</replaceable> ]
     [ ORDER BY <replaceable class="parameter">expression</replaceable> [ ASC | DESC | USING <replaceable class="parameter">operator</replaceable> ] [ NULLS { FIRST | LAST } ] [, ...] ]
index 2610645663f009742ff9c3731ba0028d29a53053..3d9d8b400d97e41ccf22bfb9ec3754a1d4c2293a 100644 (file)
@@ -769,7 +769,7 @@ SELECT t1.a, t2.b, t1.ctid FROM t1, t2 WHERE t1.a = t2.a;
 </para>
 
 <para>
-    The benefit of implementing views with the rule system is,
+    The benefit of implementing views with the rule system is
     that the planner has all
     the information about which tables have to be scanned plus the
     relationships between these tables plus the restrictive
@@ -781,7 +781,7 @@ SELECT t1.a, t2.b, t1.ctid FROM t1, t2 WHERE t1.a = t2.a;
     the best path to execute the query, and the more information
     the planner has, the better this decision can be. And
     the rule system as implemented in <productname>PostgreSQL</productname>
-    ensures, that this is all information available about the query
+    ensures that this is all information available about the query
     up to that point.
 </para>
 </sect2>
@@ -2086,7 +2086,7 @@ CREATE FUNCTION tricky(text, text) RETURNS bool AS $$
 BEGIN
     RAISE NOTICE '% =&gt; %', $1, $2;
     RETURN true;
-END
+END;
 $$ LANGUAGE plpgsql COST 0.0000000000000000000001;
 
 SELECT * FROM phone_number WHERE tricky(person, phone);
index c8bb89c0bdb5e89672120234cbb90e5f417135ef..b04ddc9b08c7eeb6ed7985253c49e7c0ab403fff 100644 (file)
@@ -197,8 +197,8 @@ test=&gt; select '6.25 .. 6.50'::seg as "pH";
   </table>
 
   <para>
-   Because <literal>...</literal> is widely used in data sources, it is allowed
-   as an alternative spelling of <literal>..</literal>.  Unfortunately, this
+   Because the <literal>...</literal> operator is widely used in data sources, it is allowed
+   as an alternative spelling of the <literal>..</literal> operator.  Unfortunately, this
    creates a parsing ambiguity: it is not clear whether the upper bound
    in <literal>0...23</literal> is meant to be <literal>23</literal> or <literal>0.23</literal>.
    This is resolved by requiring at least one digit before the decimal
index c066e7c8a99b924fc6ced4295dd9dfab0243c97f..48d6d76385d73e4333f8bf230bbfea8fa7274268 100644 (file)
@@ -2401,7 +2401,7 @@ ALTER TEXT SEARCH CONFIGURATION astro_en
     positions in <type>tsvector</type>, which in turn affect ranking:
 
 <screen>
-SELECT to_tsvector('english','in the list of stop words');
+SELECT to_tsvector('english', 'in the list of stop words');
         to_tsvector
 ----------------------------
  'list':3 'stop':5 'word':6
@@ -2411,12 +2411,12 @@ SELECT to_tsvector('english','in the list of stop words');
     calculated for documents with and without stop words are quite different:
 
 <screen>
-SELECT ts_rank_cd (to_tsvector('english','in the list of stop words'), to_tsquery('list &amp; stop'));
+SELECT ts_rank_cd (to_tsvector('english', 'in the list of stop words'), to_tsquery('list &amp; stop'));
  ts_rank_cd
 ------------
        0.05
 
-SELECT ts_rank_cd (to_tsvector('english','list stop words'), to_tsquery('list &amp; stop'));
+SELECT ts_rank_cd (to_tsvector('english', 'list stop words'), to_tsquery('list &amp; stop'));
  ts_rank_cd
 ------------
         0.1
@@ -2475,12 +2475,12 @@ CREATE TEXT SEARCH DICTIONARY public.simple_dict (
     Now we can test our dictionary:
 
 <screen>
-SELECT ts_lexize('public.simple_dict','YeS');
+SELECT ts_lexize('public.simple_dict', 'YeS');
  ts_lexize
 -----------
  {yes}
 
-SELECT ts_lexize('public.simple_dict','The');
+SELECT ts_lexize('public.simple_dict', 'The');
  ts_lexize
 -----------
  {}
@@ -2496,12 +2496,12 @@ SELECT ts_lexize('public.simple_dict','The');
 <screen>
 ALTER TEXT SEARCH DICTIONARY public.simple_dict ( Accept = false );
 
-SELECT ts_lexize('public.simple_dict','YeS');
+SELECT ts_lexize('public.simple_dict', 'YeS');
  ts_lexize
 -----------
 
 
-SELECT ts_lexize('public.simple_dict','The');
+SELECT ts_lexize('public.simple_dict', 'The');
  ts_lexize
 -----------
  {}
@@ -2615,7 +2615,7 @@ indices index*
     Then we will get these results:
 <screen>
 mydb=# CREATE TEXT SEARCH DICTIONARY syn (template=synonym, synonyms='synonym_sample');
-mydb=# SELECT ts_lexize('syn','indices');
+mydb=# SELECT ts_lexize('syn', 'indices');
  ts_lexize
 -----------
  {index}
@@ -2623,13 +2623,13 @@ mydb=# SELECT ts_lexize('syn','indices');
 
 mydb=# CREATE TEXT SEARCH CONFIGURATION tst (copy=simple);
 mydb=# ALTER TEXT SEARCH CONFIGURATION tst ALTER MAPPING FOR asciiword WITH syn;
-mydb=# SELECT to_tsvector('tst','indices');
+mydb=# SELECT to_tsvector('tst', 'indices');
  to_tsvector
 -------------
  'index':1
 (1 row)
 
-mydb=# SELECT to_tsquery('tst','indices');
+mydb=# SELECT to_tsquery('tst', 'indices');
  to_tsquery
 ------------
  'index':*
@@ -2641,7 +2641,7 @@ mydb=# SELECT 'indexes are very useful'::tsvector;
  'are' 'indexes' 'useful' 'very'
 (1 row)
 
-mydb=# SELECT 'indexes are very useful'::tsvector @@ to_tsquery('tst','indices');
+mydb=# SELECT 'indexes are very useful'::tsvector @@ to_tsquery('tst', 'indices');
  ?column?
 ----------
  t
@@ -3336,7 +3336,7 @@ ts_debug(<optional> <replaceable class="parameter">config</replaceable> <type>re
    Here is a simple example:
 
 <screen>
-SELECT * FROM ts_debug('english','a fat  cat sat on a mat - it ate a fat rats');
+SELECT * FROM ts_debug('english', 'a fat  cat sat on a mat - it ate a fat rats');
    alias   |   description   | token |  dictionaries  |  dictionary  | lexemes 
 -----------+-----------------+-------+----------------+--------------+---------
  asciiword | Word, all ASCII | a     | {english_stem} | english_stem | {}
@@ -3387,7 +3387,7 @@ ALTER TEXT SEARCH CONFIGURATION public.english
 </programlisting>
 
 <screen>
-SELECT * FROM ts_debug('public.english','The Brightest supernovaes');
+SELECT * FROM ts_debug('public.english', 'The Brightest supernovaes');
    alias   |   description   |    token    |         dictionaries          |   dictionary   |   lexemes   
 -----------+-----------------+-------------+-------------------------------+----------------+-------------
  asciiword | Word, all ASCII | The         | {english_ispell,english_stem} | english_ispell | {}
@@ -3426,7 +3426,7 @@ SELECT * FROM ts_debug('public.english','The Brightest supernovaes');
 
 <screen>
 SELECT alias, token, dictionary, lexemes
-FROM ts_debug('public.english','The Brightest supernovaes');
+FROM ts_debug('public.english', 'The Brightest supernovaes');
    alias   |    token    |   dictionary   |   lexemes   
 -----------+-------------+----------------+-------------
  asciiword | The         | english_ispell | {}
@@ -3574,7 +3574,7 @@ SELECT ts_lexize('english_stem', 'a');
      where this can be confusing:
 
 <screen>
-SELECT ts_lexize('thesaurus_astro','supernovae stars') is null;
+SELECT ts_lexize('thesaurus_astro', 'supernovae stars') is null;
  ?column?
 ----------
  t