From 7b2822ecf944a6aa429c05cc7f070001c3817934 Mon Sep 17 00:00:00 2001 From: Daniel Gustafsson Date: Wed, 2 Oct 2024 14:50:56 +0200 Subject: [PATCH] doc: Missing markup, punctuation and wordsmithing Various improvements to the documentation like adding missing markup, improving punctuation, ensuring consistent spelling of words and minor wordsmithing. Author: Oleg Sibiryakov Discussion: https://postgr.es/m/b7d0a03c-107e-48c7-a5c9-2c6f73cdf78f@postgrespro.ru --- doc/src/sgml/catalogs.sgml | 2 +- doc/src/sgml/charset.sgml | 4 ++-- doc/src/sgml/config.sgml | 6 +++--- doc/src/sgml/func.sgml | 2 +- doc/src/sgml/libpq.sgml | 19 ++++++++++--------- doc/src/sgml/protocol.sgml | 7 ++++--- doc/src/sgml/ref/alter_table.sgml | 4 ++-- doc/src/sgml/ref/copy.sgml | 4 ++-- doc/src/sgml/ref/create_subscription.sgml | 5 +++-- doc/src/sgml/ref/pgupgrade.sgml | 2 +- doc/src/sgml/sepgsql.sgml | 2 +- doc/src/sgml/syntax.sgml | 2 +- doc/src/sgml/system-views.sgml | 4 ++-- doc/src/sgml/trigger.sgml | 3 ++- doc/src/sgml/user-manag.sgml | 2 +- doc/src/sgml/wal.sgml | 4 ++-- 16 files changed, 38 insertions(+), 34 deletions(-) diff --git a/doc/src/sgml/catalogs.sgml b/doc/src/sgml/catalogs.sgml index bfb97865e18..964c819a02d 100644 --- a/doc/src/sgml/catalogs.sgml +++ b/doc/src/sgml/catalogs.sgml @@ -8041,7 +8041,7 @@ SCRAM-SHA-256$<iteration count>:&l If true, the associated replication slots (i.e. the main slot and the - table sync slots) in the upstream database are enabled to be + table synchronization slots) in the upstream database are enabled to be synchronized to the standbys diff --git a/doc/src/sgml/charset.sgml b/doc/src/sgml/charset.sgml index 834cb30c85a..1ef5322b912 100644 --- a/doc/src/sgml/charset.sgml +++ b/doc/src/sgml/charset.sgml @@ -862,7 +862,7 @@ SELECT * FROM test1 ORDER BY a || b COLLATE "fr_FR"; This SQL standard collation sorts using the Unicode Collation Algorithm with the Default Unicode Collation Element Table. It is available in all encodings. ICU support is required to use this - collation, and behavior may change if Postgres is built with a + collation, and behavior may change if PostgreSQL is built with a different version of ICU. (This collation has the same behavior as the ICU root locale; see .) @@ -897,7 +897,7 @@ SELECT * FROM test1 ORDER BY a || b COLLATE "fr_FR"; expressions), it uses the POSIX Compatible variant of Unicode Compatibility Properties. Behavior is efficient and stable within a - Postgres major version. This collation is + PostgreSQL major version. This collation is only available for encoding UTF8. diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml index 08173ecb5c4..9707d5238da 100644 --- a/doc/src/sgml/config.sgml +++ b/doc/src/sgml/config.sgml @@ -708,7 +708,7 @@ include_dir 'conf.d' - PostgreSQL sizes certain resources based directly on the value of + PostgreSQL sizes certain resources based directly on the value of max_connections. Increasing its value leads to higher allocation of those resources, including shared memory. @@ -6422,7 +6422,7 @@ SELECT * FROM parent WHERE key = 2400; If csvlog is included in log_destination, - log entries are output in comma separated + log entries are output in comma-separated value (CSV) format, which is convenient for loading logs into programs. See for details. @@ -10838,7 +10838,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' Turning this setting off is intended for environments where the configuration of PostgreSQL is managed by some external tool. - In such environments, a well intentioned superuser might + In such environments, a well-intentioned superuser might mistakenly use ALTER SYSTEM to change the configuration instead of using the external tool. This might result in unintended behavior, such as the external tool diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml index d6acdd3059e..7b4fbb50471 100644 --- a/doc/src/sgml/func.sgml +++ b/doc/src/sgml/func.sgml @@ -21437,7 +21437,7 @@ SELECT NULLIF(value, '(none)') ... Extracts the lower bound of the multirange (NULL if the - multirange is empty has no lower bound). + multirange is empty or has no lower bound). lower('{[1.1,2.2)}'::nummultirange) diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml index e56c12acfa2..afc9346757a 100644 --- a/doc/src/sgml/libpq.sgml +++ b/doc/src/sgml/libpq.sgml @@ -545,9 +545,9 @@ int PQsocketPoll(int sock, int forRead, int forWrite, the Unix epoch (that is, time_t times 1 million). Timeout is infinite if end_time is -1. Timeout is immediate (no blocking) if - end_time is 0 (or indeed, any time before now). - Timeout values can be calculated conveniently by adding the desired - number of microseconds to the result of + end_time is 0 (or indeed, any + time before now). Timeout values can be calculated conveniently by + adding the desired number of microseconds to the result of . Note that the underlying system calls may have less than microsecond precision, so that the actual delay may be imprecise. @@ -1830,11 +1830,12 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname direct - start SSL handshake directly after establishing the TCP/IP - connection. This is only allowed with sslmode=require or higher, - because the weaker settings could lead to unintended fallback to - plaintext authentication when the server does not support direct - SSL handshake. + start SSL handshake directly after establishing the TCP/IP + connection. This is only allowed with + sslmode=require or higher, because the weaker + settings could lead to unintended fallback to plaintext + authentication when the server does not support direct SSL + handshake. @@ -9582,7 +9583,7 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*) For backwards compatibility with earlier versions of PostgreSQL, if a root CA file exists, the behavior of - sslmode=require will be the same + sslmode=require will be the same as that of verify-ca, meaning the server certificate is validated against the CA. Relying on this behavior is discouraged, and applications that need certificate validation should always use diff --git a/doc/src/sgml/protocol.sgml b/doc/src/sgml/protocol.sgml index 2d2481bb8b8..057c46f3f57 100644 --- a/doc/src/sgml/protocol.sgml +++ b/doc/src/sgml/protocol.sgml @@ -3265,7 +3265,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - Comma separated list of publication names for which to subscribe + Comma-separated list of publication names for which to subscribe (receive changes). The individual publication names are treated as standard objects names and can be quoted the same as needed. At least one publication name is required. @@ -3330,8 +3330,9 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;" - Option to send changes by their origin. Possible values are "none" - to only send the changes that have no origin associated, or "any" + Option to send changes by their origin. Possible values are + none to only send the changes that have no origin + associated, or any to send the changes regardless of their origin. This can be used to avoid loops (infinite replication of the same data) among replication nodes. diff --git a/doc/src/sgml/ref/alter_table.sgml b/doc/src/sgml/ref/alter_table.sgml index 925f1084e00..c5a14674804 100644 --- a/doc/src/sgml/ref/alter_table.sgml +++ b/doc/src/sgml/ref/alter_table.sgml @@ -1123,8 +1123,8 @@ WITH ( MODULUS numeric_literal, REM - All the forms of ALTER TABLE that act on a single table, except - RENAME, SET SCHEMA, + All the forms of ALTER TABLE that act on a single table, + except RENAME, SET SCHEMA, ATTACH PARTITION, and DETACH PARTITION can be combined into a list of multiple alterations to be applied together. For example, it diff --git a/doc/src/sgml/ref/copy.sgml b/doc/src/sgml/ref/copy.sgml index fdbd20bc50b..33633447f16 100644 --- a/doc/src/sgml/ref/copy.sgml +++ b/doc/src/sgml/ref/copy.sgml @@ -427,7 +427,7 @@ COPY { table_name [ ( LOG_VERBOSITY - Specify the amount of messages emitted by a COPY + Specifies the amount of messages emitted by a COPY command: default or verbose. If verbose is specified, additional messages are emitted during processing. @@ -779,7 +779,7 @@ COPY count CSV Format - This format option is used for importing and exporting the Comma + This format option is used for importing and exporting the Comma- Separated Value (CSV) file format used by many other programs, such as spreadsheets. Instead of the escaping rules used by PostgreSQL's standard text format, it diff --git a/doc/src/sgml/ref/create_subscription.sgml b/doc/src/sgml/ref/create_subscription.sgml index 740b7d94210..8a3096e62b5 100644 --- a/doc/src/sgml/ref/create_subscription.sgml +++ b/doc/src/sgml/ref/create_subscription.sgml @@ -185,7 +185,7 @@ CREATE SUBSCRIPTION subscription_name When setting slot_name to a valid name and - create_slot to false, the + create_slot to false, the failover property value of the named slot may differ from the counterpart failover parameter specified in the subscription. Always ensure the slot property @@ -474,7 +474,8 @@ CREATE SUBSCRIPTION subscription_name If any table in the publication has a WHERE clause, rows for which the expression - evaluates to false or null will not be published. If the subscription has + evaluates to false or NULL will not be + published. If the subscription has several publications in which the same table has been published with different WHERE clauses, a row will be published if any of the expressions (referring to that publish operation) are satisfied. In diff --git a/doc/src/sgml/ref/pgupgrade.sgml b/doc/src/sgml/ref/pgupgrade.sgml index 41d5566a442..4777381dac2 100644 --- a/doc/src/sgml/ref/pgupgrade.sgml +++ b/doc/src/sgml/ref/pgupgrade.sgml @@ -67,7 +67,7 @@ PostgreSQL documentation - pg_upgrade supports upgrades from 9.2.X and later to the current + pg_upgrade supports upgrades from 9.2.X and later to the current major release of PostgreSQL, including snapshot and beta releases. diff --git a/doc/src/sgml/sepgsql.sgml b/doc/src/sgml/sepgsql.sgml index bc308e3142d..ca038d71042 100644 --- a/doc/src/sgml/sepgsql.sgml +++ b/doc/src/sgml/sepgsql.sgml @@ -87,7 +87,7 @@ Policy from config file: targeted - To build this module specify (when using make and autoconf ) or (when using , to compare one row against another as described in , and to use them in connection with subqueries, as discussed in , + linkend="functions-subquery"/>. diff --git a/doc/src/sgml/system-views.sgml b/doc/src/sgml/system-views.sgml index 634a4c0fab4..61d28e701f2 100644 --- a/doc/src/sgml/system-views.sgml +++ b/doc/src/sgml/system-views.sgml @@ -2586,7 +2586,7 @@ SELECT * FROM pg_locks pl LEFT JOIN pg_prepared_xacts ppx True if this logical slot conflicted with recovery (and so is now invalidated). When this column is true, check invalidation_reason column for the conflict - reason. Always NULL for physical slots. + reason. Always NULL for physical slots. @@ -3945,7 +3945,7 @@ SELECT * FROM pg_locks pl LEFT JOIN pg_prepared_xacts ppx range type column. (Null for non-range types.) - This histogram is calculated using the subtype_diff + This histogram is calculated using the subtype_diff range function regardless of whether range bounds are inclusive. diff --git a/doc/src/sgml/trigger.sgml b/doc/src/sgml/trigger.sgml index 49382d07fa8..a9abaab9056 100644 --- a/doc/src/sgml/trigger.sgml +++ b/doc/src/sgml/trigger.sgml @@ -357,7 +357,8 @@ If a foreign key constraint specifies referential actions (that is, cascading updates or deletes), those actions are performed via - ordinary SQL update or delete commands on the referencing table. + ordinary SQL UPDATE or DELETE + commands on the referencing table. In particular, any triggers that exist on the referencing table will be fired for those changes. If such a trigger modifies or blocks the effect of one of these commands, the end result could diff --git a/doc/src/sgml/user-manag.sgml b/doc/src/sgml/user-manag.sgml index 0a005481d1b..ed18704a9c2 100644 --- a/doc/src/sgml/user-manag.sgml +++ b/doc/src/sgml/user-manag.sgml @@ -407,7 +407,7 @@ REVOKE group_role FROM role1become the group role. In this state, the database session has access to the privileges of the group role rather than the original login role, and any database objects created are - considered owned by the group role not the login role. Second, member + considered owned by the group role, not the login role. Second, member roles that have been granted membership with the INHERIT option automatically have use of the privileges of those directly or indirectly a member of, though the diff --git a/doc/src/sgml/wal.sgml b/doc/src/sgml/wal.sgml index 0ba0c930b78..a34cddb5ed4 100644 --- a/doc/src/sgml/wal.sgml +++ b/doc/src/sgml/wal.sgml @@ -679,11 +679,11 @@ In some cases, when the WAL size on the primary increases quickly, - for instance during massive INSERT, + for instance during massive INSERT, the restartpoints_req counter on the standby may demonstrate a peak growth. This occurs because requests to create a new restartpoint due to increased - XLOG consumption cannot be performed because the safe checkpoint record + WAL consumption cannot be performed because the safe checkpoint record since the last restartpoint has not yet been replayed on the standby. This behavior is normal and does not lead to an increase in system resource consumption. -- 2.39.5