]> git.ipfire.org Git - thirdparty/postgresql.git/commitdiff
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:30:01 +0000 (19:30 +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

15 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/isn.sgml
doc/src/sgml/mvcc.sgml
doc/src/sgml/parallel.sgml
doc/src/sgml/plpgsql.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 e611f0d08666ccf347bfa00584dd929e9a72e7b0..c14f2e379e3a4819a97a780ba7816c64dba9e1d2 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 bc85aec4ef9e8472c2bcf8dd2a90a5ef06e67c4a..ca590d45bff4bfd2c79a8ea34a9187a0c3dea131 100644 (file)
@@ -8182,8 +8182,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 7f1f58b5712eca637fdd1e4d93ef6a9c002f4135..78387449425e5189244e3e060496441eb6f248b8 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>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 60c3d2a579eecedf1bdeb6bfb0220a66d9fc6684..11b550125d211754516c5c511c197ae20eeb0662 100644 (file)
@@ -20041,7 +20041,7 @@ BEGIN
                      obj.object_name,
                      obj.object_identity;
     END LOOP;
-END
+END;
 $$;
 CREATE EVENT TRIGGER test_event_trigger_for_drops
    ON sql_drop
index 05d92eb97502073dd8a19d44f3d1e79be8928056..9fe8289cee11f275043f39875bdf655f466699c0 100644 (file)
      if a foreground cleanup does occur, it will take even longer.
     </para>
     <para>
-     <varname>gin_pending_list_limit</> can be overridden for individual
-     GIN indexes by changing storage parameters, and which allows each
+     <varname>gin_pending_list_limit</varname> can be overridden for individual
+     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 f8780099223f12f5dae377fe3fbc050076a3e1bf..105ce5ceb52ec0f9a1204e0f2917f6339be4591b 100644 (file)
@@ -1411,7 +1411,7 @@ synchronous_standby_names = '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</> can be used to make that delay
     shorter. Also note that you can't combine streaming replication with
     this method.
index 97d1f79a3ad8a46e603cae7dd077498010a7b383..8b99dec2ca78b36f08c7ca65a5a2053bb344a881 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 29a4cc3a1e719f9b07b4a5cc0bb27a1ece1fee78..0349cbc20e2a18067b6c86822e697bec9fc95cad 100644 (file)
@@ -1235,7 +1235,7 @@ ERROR:  could not serialize access due to read/write dependencies among transact
         <para>
          The <literal>FOR UPDATE</> lock mode
          is also acquired by any <command>DELETE</> on a row, and also by an
-         <command>UPDATE</> that modifies the values on certain columns.  Currently,
+         <command>UPDATE</> that modifies the values of certain columns.  Currently,
          the set of columns considered for the <command>UPDATE</> 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 b4ae248985f42936d049afc499c0049ed7219eaf..3899cfd721fb0ccf77ba6a483dda650252b77294 100644 (file)
@@ -374,7 +374,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 35623a3f6548d9d757e36702e19a7c304bc4a5ad..58699eb7a13d0180ff68447d0e78862da2b5a689 100644 (file)
@@ -1127,7 +1127,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
@@ -1805,7 +1805,7 @@ BEGIN
         RETURN NEXT r; -- return current row of SELECT
     END LOOP;
     RETURN;
-END
+END;
 $BODY$
 LANGUAGE plpgsql;
 
@@ -1833,7 +1833,7 @@ BEGIN
     END IF;
 
     RETURN;
- END
+ END;
 $BODY$
 LANGUAGE plpgsql;
 
@@ -4899,7 +4899,7 @@ DECLARE
 f1 int;
 BEGIN
 RETURN f1;
-END
+END;
 $$ LANGUAGE plpgsql;
 WARNING:  variable "f1" shadows a previously defined variable
 LINE 3: f1 int;
index ec3bb2bd457f00ad22a077a17fef1160a200ea7b..5c521859cdfef71b61ff9c1a982618271cddff16 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 84b0dd831f915624165bd4f5baa6804ee475d70b..8d0045920ac84c442ca72ba2d607922b08aa6687 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 5dade806adcfbceb2f0346e8ae3020a74d619e50..9b1c12dfca4ac22d8995af3406c12498929d2e47 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 0df412da29361a801c46eff2e2d5ea67419f621f..838d1909d5ceeecb50fb2f41ed8e515947f7be13 100644 (file)
@@ -197,8 +197,8 @@ test=&gt; select '6.25 .. 6.50'::seg as "pH";
   </table>
 
   <para>
-   Because <literal>...</> is widely used in data sources, it is allowed
-   as an alternative spelling of <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</> is meant to be <literal>23</> or <literal>0.23</>.
    This is resolved by requiring at least one digit before the decimal
index 3da4aaa024ad6869ea368b6a6ed4876d0347a410..ec143ddecec343b29d1629bba6bad3e1321d1701 100644 (file)
@@ -2321,7 +2321,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
@@ -2331,12 +2331,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
@@ -2395,12 +2395,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
 -----------
  {}
@@ -2416,12 +2416,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
 -----------
  {}
@@ -2535,7 +2535,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}
@@ -2543,13 +2543,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':*
@@ -2561,7 +2561,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
@@ -3256,7 +3256,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 | {}
@@ -3307,7 +3307,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 | {}
@@ -3346,7 +3346,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 | {}
@@ -3494,7 +3494,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