From 660376397e0e45a8e6d9fe241a161bd6df45346e Mon Sep 17 00:00:00 2001 From: Heikki Linnakangas Date: Mon, 19 Oct 2020 19:28:54 +0300 Subject: [PATCH] Misc documentation fixes. - 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 --- doc/src/sgml/catalogs.sgml | 2 +- doc/src/sgml/config.sgml | 4 ++-- doc/src/sgml/dblink.sgml | 8 ++++---- doc/src/sgml/func.sgml | 2 +- doc/src/sgml/gin.sgml | 4 ++-- doc/src/sgml/high-availability.sgml | 2 +- doc/src/sgml/isn.sgml | 2 +- doc/src/sgml/mvcc.sgml | 2 +- doc/src/sgml/plpgsql.sgml | 8 ++++---- doc/src/sgml/ref/select.sgml | 2 +- doc/src/sgml/ref/select_into.sgml | 2 +- doc/src/sgml/rules.sgml | 6 +++--- doc/src/sgml/seg.sgml | 4 ++-- doc/src/sgml/textsearch.sgml | 30 ++++++++++++++--------------- 14 files changed, 39 insertions(+), 39 deletions(-) diff --git a/doc/src/sgml/catalogs.sgml b/doc/src/sgml/catalogs.sgml index e7af4bae65d..e0eb49452d0 100644 --- a/doc/src/sgml/catalogs.sgml +++ b/doc/src/sgml/catalogs.sgml @@ -1425,7 +1425,7 @@ bool Role can log in. That is, this role can be given as the initial - session authorization identifier + session authorization identifier. diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml index 6fcc2901ac4..7e4d8c39257 100644 --- a/doc/src/sgml/config.sgml +++ b/doc/src/sgml/config.sgml @@ -7629,8 +7629,8 @@ LOG: CleanUpLock: deleting: lock(0xb7acd844) id(24688,24696,0,0,0,1) - 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). This parameter is only available if the LOCK_DEBUG diff --git a/doc/src/sgml/dblink.sgml b/doc/src/sgml/dblink.sgml index 53396ea174e..f320fcd0677 100644 --- a/doc/src/sgml/dblink.sgml +++ b/doc/src/sgml/dblink.sgml @@ -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 The SQL command that you wish to execute in the remote database, for example - insert into foo values(0,'a','{"a0","b0","c0"}'). + insert into foo values(0, 'a', '{"a0","b0","c0"}'). @@ -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 diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml index caf892f7486..35fbd239bcc 100644 --- a/doc/src/sgml/func.sgml +++ b/doc/src/sgml/func.sgml @@ -18832,7 +18832,7 @@ BEGIN obj.object_name, obj.object_identity; END LOOP; -END +END; $$; CREATE EVENT TRIGGER test_event_trigger_for_drops ON sql_drop diff --git a/doc/src/sgml/gin.sgml b/doc/src/sgml/gin.sgml index 1307113b676..d4d85ec5726 100644 --- a/doc/src/sgml/gin.sgml +++ b/doc/src/sgml/gin.sgml @@ -827,8 +827,8 @@ if a foreground cleanup does occur, it will take even longer. - gin_pending_list_limit can be overridden for individual - GIN indexes by changing storage parameters, and which allows each + gin_pending_list_limit 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. diff --git a/doc/src/sgml/high-availability.sgml b/doc/src/sgml/high-availability.sgml index 6e893b0efe8..545dfbe2023 100644 --- a/doc/src/sgml/high-availability.sgml +++ b/doc/src/sgml/high-availability.sgml @@ -1358,7 +1358,7 @@ primary_slot_name = 'node_a_slot' 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. archive_timeout can be used to make that delay shorter. Also note that you can't combine streaming replication with this method. diff --git a/doc/src/sgml/isn.sgml b/doc/src/sgml/isn.sgml index 97d1f79a3ad..8b99dec2ca7 100644 --- a/doc/src/sgml/isn.sgml +++ b/doc/src/sgml/isn.sgml @@ -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 diff --git a/doc/src/sgml/mvcc.sgml b/doc/src/sgml/mvcc.sgml index 58ca668569f..6dc7fdd614a 100644 --- a/doc/src/sgml/mvcc.sgml +++ b/doc/src/sgml/mvcc.sgml @@ -1232,7 +1232,7 @@ ERROR: could not serialize access due to read/write dependencies among transact The FOR UPDATE lock mode is also acquired by any DELETE on a row, and also by an - UPDATE that modifies the values on certain columns. Currently, + UPDATE that modifies the values of certain columns. Currently, the set of columns considered for the 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 diff --git a/doc/src/sgml/plpgsql.sgml b/doc/src/sgml/plpgsql.sgml index 5200c3fb94d..91e8973c421 100644 --- a/doc/src/sgml/plpgsql.sgml +++ b/doc/src/sgml/plpgsql.sgml @@ -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; 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; @@ -4889,7 +4889,7 @@ DECLARE f1 int; BEGIN RETURN f1; -END +END; $$ LANGUAGE plpgsql; WARNING: variable "f1" shadows a previously defined variable LINE 3: f1 int; diff --git a/doc/src/sgml/ref/select.sgml b/doc/src/sgml/ref/select.sgml index 034223115f8..18f6b0c2afb 100644 --- a/doc/src/sgml/ref/select.sgml +++ b/doc/src/sgml/ref/select.sgml @@ -38,7 +38,7 @@ SELECT [ ALL | DISTINCT [ ON ( expressionfrom_item [, ...] ] [ WHERE condition ] [ GROUP BY grouping_element [, ...] ] - [ HAVING condition [, ...] ] + [ HAVING condition ] [ WINDOW window_name AS ( window_definition ) [, ...] ] [ { UNION | INTERSECT | EXCEPT } [ ALL | DISTINCT ] select ] [ ORDER BY expression [ ASC | DESC | USING operator ] [ NULLS { FIRST | LAST } ] [, ...] ] diff --git a/doc/src/sgml/ref/select_into.sgml b/doc/src/sgml/ref/select_into.sgml index 84b0dd831f9..8d0045920ac 100644 --- a/doc/src/sgml/ref/select_into.sgml +++ b/doc/src/sgml/ref/select_into.sgml @@ -28,7 +28,7 @@ SELECT [ ALL | DISTINCT [ ON ( expressionfrom_item [, ...] ] [ WHERE condition ] [ GROUP BY expression [, ...] ] - [ HAVING condition [, ...] ] + [ HAVING condition ] [ WINDOW window_name AS ( window_definition ) [, ...] ] [ { UNION | INTERSECT | EXCEPT } [ ALL | DISTINCT ] select ] [ ORDER BY expression [ ASC | DESC | USING operator ] [ NULLS { FIRST | LAST } ] [, ...] ] diff --git a/doc/src/sgml/rules.sgml b/doc/src/sgml/rules.sgml index f4adf74f5ba..2de649c5a37 100644 --- a/doc/src/sgml/rules.sgml +++ b/doc/src/sgml/rules.sgml @@ -769,7 +769,7 @@ SELECT t1.a, t2.b, t1.ctid FROM t1, t2 WHERE t1.a = t2.a; - 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 PostgreSQL - ensures, that this is all information available about the query + ensures that this is all information available about the query up to that point. @@ -2086,7 +2086,7 @@ CREATE FUNCTION tricky(text, text) RETURNS bool AS $$ BEGIN RAISE NOTICE '% => %', $1, $2; RETURN true; -END +END; $$ LANGUAGE plpgsql COST 0.0000000000000000000001; SELECT * FROM phone_number WHERE tricky(person, phone); diff --git a/doc/src/sgml/seg.sgml b/doc/src/sgml/seg.sgml index 05eb6d44ffc..c5a36a8bb80 100644 --- a/doc/src/sgml/seg.sgml +++ b/doc/src/sgml/seg.sgml @@ -197,8 +197,8 @@ test=> select '6.25 .. 6.50'::seg as "pH"; - Because ... is widely used in data sources, it is allowed - as an alternative spelling of ... Unfortunately, this + Because the ... operator is widely used in data sources, it is allowed + as an alternative spelling of the .. operator. Unfortunately, this creates a parsing ambiguity: it is not clear whether the upper bound in 0...23 is meant to be 23 or 0.23. This is resolved by requiring at least one digit before the decimal diff --git a/doc/src/sgml/textsearch.sgml b/doc/src/sgml/textsearch.sgml index ce22fb8a370..133fa1993f1 100644 --- a/doc/src/sgml/textsearch.sgml +++ b/doc/src/sgml/textsearch.sgml @@ -2125,7 +2125,7 @@ ALTER TEXT SEARCH CONFIGURATION astro_en positions in tsvector, which in turn affect ranking: -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 @@ -2135,12 +2135,12 @@ SELECT to_tsvector('english','in the list of stop words'); calculated for documents with and without stop words are quite different: -SELECT ts_rank_cd (to_tsvector('english','in the list of stop words'), to_tsquery('list & stop')); +SELECT ts_rank_cd (to_tsvector('english', 'in the list of stop words'), to_tsquery('list & stop')); ts_rank_cd ------------ 0.05 -SELECT ts_rank_cd (to_tsvector('english','list stop words'), to_tsquery('list & stop')); +SELECT ts_rank_cd (to_tsvector('english', 'list stop words'), to_tsquery('list & stop')); ts_rank_cd ------------ 0.1 @@ -2199,12 +2199,12 @@ CREATE TEXT SEARCH DICTIONARY public.simple_dict ( Now we can test our dictionary: -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 ----------- {} @@ -2220,12 +2220,12 @@ SELECT ts_lexize('public.simple_dict','The'); 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 ----------- {} @@ -2339,7 +2339,7 @@ indices index* Then we will get these results: 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} @@ -2347,13 +2347,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':* @@ -2365,7 +2365,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 @@ -2928,7 +2928,7 @@ ts_debug( config re Here is a simple example: -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 | {} @@ -2979,7 +2979,7 @@ ALTER TEXT SEARCH CONFIGURATION public.english -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 | {} @@ -3018,7 +3018,7 @@ SELECT * FROM ts_debug('public.english','The Brightest supernovaes'); 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 | {} @@ -3166,7 +3166,7 @@ SELECT ts_lexize('english_stem', 'a'); where this can be confusing: -SELECT ts_lexize('thesaurus_astro','supernovae stars') is null; +SELECT ts_lexize('thesaurus_astro', 'supernovae stars') is null; ?column? ---------- t -- 2.39.5