agora inbox for pgsql-docs@postgresql.org
help / color / mirror / Atom feedDocumentation improvement patch
23+ messages / 4 participants
[nested] [flat]
* Documentation improvement patch
@ 2024-09-05 09:33 Oleg Sibiryakov <o.sibiryakov@postgrespro.ru>
2024-09-06 13:20 ` Re: Documentation improvement patch Daniel Gustafsson <daniel@yesql.se>
0 siblings, 1 reply; 23+ messages in thread
From: Oleg Sibiryakov @ 2024-09-05 09:33 UTC (permalink / raw)
To: pgsql-docs@lists.postgresql.org
Dear all,
I have prepared a patch containing some minor inconsistencies in the
documentation. Please, take a look.
The inconsistencies were noticed by: Ekaterina Kiryanova, Elena
Indrupskaya, Maxim Yablokov, Anna Uraskova, Elena Karavaeva, and me.
We will be looking forward to your feedback.
The patch shall be applied to the REL_17_STABLE branch.
--
Regards,
Oleg Sibiryakov
Technical Writer
Postgres Professional, The Russian Postgres Company
https://postgrespro.ru
Attachments:
[text/x-patch] doc-improvements.patch (24.5K, ../../b7d0a03c-107e-48c7-a5c9-2c6f73cdf78f@postgrespro.ru/3-doc-improvements.patch)
download | inline diff:
diff --git a/doc/src/sgml/catalogs.sgml b/doc/src/sgml/catalogs.sgml
index a63cc71efa2..7a905fd6a3a 100644
--- a/doc/src/sgml/catalogs.sgml
+++ b/doc/src/sgml/catalogs.sgml
@@ -8029,7 +8029,7 @@ SCRAM-SHA-256$<replaceable><iteration count></replaceable>:<replaceable>&l
</para>
<para>
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
</para></entry>
</row>
diff --git a/doc/src/sgml/charset.sgml b/doc/src/sgml/charset.sgml
index 834cb30c85a..a76e9579a14 100644
--- a/doc/src/sgml/charset.sgml
+++ b/doc/src/sgml/charset.sgml
@@ -382,8 +382,8 @@ initdb --locale-provider=icu --icu-locale=en
</para>
<para>
The <literal>C</literal> locale behavior is identical to the
- <literal>C</literal> locale in the libc provider. When using this
- locale, the behavior may depend on the database encoding.
+ <literal>C</literal> locale in the <literal>libc</literal> provider. When
+ using this locale, the behavior may depend on the database encoding.
</para>
<para>
The <literal>C.UTF-8</literal> locale is available only for when the
@@ -400,7 +400,7 @@ initdb --locale-provider=icu --icu-locale=en
<listitem>
<para>
The <literal>icu</literal> provider uses the external
- ICU<indexterm><primary>ICU</primary></indexterm>
+ <indexterm><primary>ICU</primary></indexterm>
library. <productname>PostgreSQL</productname> must have been
configured with support.
</para>
@@ -862,8 +862,9 @@ 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
- different version of ICU. (This collation has the same behavior as
+ collation, and behavior may change if
+ <productname>PostgreSQL</productname> is built with a different version
+ of ICU. (This collation has the same behavior as
the ICU root locale; see <xref
linkend="collation-managing-predefined-icu-und-x-icu"/>.)
</para>
@@ -897,7 +898,7 @@ SELECT * FROM test1 ORDER BY a || b COLLATE "fr_FR";
expressions), it uses the POSIX Compatible variant of Unicode <ulink
url="https://www.unicode.org/reports/tr18/#Compatibility_Properties">Compatibility
Properties</ulink>. Behavior is efficient and stable within a
- <productname>Postgres</productname> major version. This collation is
+ <productname>PostgreSQL</productname> major version. This collation is
only available for encoding <literal>UTF8</literal>.
</para>
</listitem>
diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml
index 7c60aeab4f6..2027308f89f 100644
--- a/doc/src/sgml/config.sgml
+++ b/doc/src/sgml/config.sgml
@@ -708,9 +708,10 @@ include_dir 'conf.d'
</para>
<para>
- PostgreSQL sizes certain resources based directly on the value of
- <varname>max_connections</varname>. Increasing its value leads to
- higher allocation of those resources, including shared memory.
+ <productname>PostgreSQL</productname> sizes certain resources based
+ directly on the value of <varname>max_connections</varname>. Increasing
+ its value leads to higher allocation of those resources, including
+ shared memory.
</para>
<para>
@@ -9384,7 +9385,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv;
<para>
If <varname>transaction_timeout</varname> is shorter or equal to
<varname>idle_in_transaction_session_timeout</varname> or <varname>statement_timeout</varname>
- then the longer timeout is ignored.
+ then the longer timeout is ignored.
</para>
<para>
@@ -10842,7 +10843,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir'
Turning this setting off is intended for environments where the
configuration of <productname>PostgreSQL</productname> is managed by
some external tool.
- In such environments, a well intentioned superuser might
+ In such environments, a well-intentioned superuser might
<emphasis>mistakenly</emphasis> use <command>ALTER SYSTEM</command>
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/ddl.sgml b/doc/src/sgml/ddl.sgml
index 220683b5eb4..1d2987e628d 100644
--- a/doc/src/sgml/ddl.sgml
+++ b/doc/src/sgml/ddl.sgml
@@ -313,7 +313,7 @@ INSERT INTO people (id, name, address) VALUE (<emphasis>DEFAULT</emphasis>, 'C',
<para>
The data type of an identity column must be one of the data types supported
- by sequences. (See <xref linkend="sql-createsequence"/>.) The properties
+ by sequences (see <xref linkend="sql-createsequence"/>). The properties
of the associated sequence may be specified when creating an identity
column (see <xref linkend="sql-createtable"/>) or changed afterwards (see
<xref linkend="sql-altertable"/>).
diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index 03b63f74191..b876c5cf939 100644
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -21381,7 +21381,7 @@ SELECT NULLIF(value, '(none)') ...
</para>
<para>
Extracts the lower bound of the multirange (<literal>NULL</literal> if the
- multirange is empty has no lower bound).
+ multirange is empty or has no lower bound).
</para>
<para>
<literal>lower('{[1.1,2.2)}'::nummultirange)</literal>
diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml
index 068ee60771c..855806b739b 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, <type>time_t</type> times 1 million).
Timeout is infinite if <parameter>end_time</parameter>
is <literal>-1</literal>. Timeout is immediate (no blocking) if
- end_time is <literal>0</literal> (or indeed, any time before now).
- Timeout values can be calculated conveniently by adding the desired
- number of microseconds to the result of
+ <parameter>end_time</parameter> is <literal>0</literal> (or indeed, any
+ time before now). Timeout values can be calculated conveniently by adding
+ the desired number of microseconds to the result of
<xref linkend="libpq-PQgetCurrentTimeUSec"/>.
Note that the underlying system calls may have less than microsecond
precision, so that the actual delay may be imprecise.
@@ -1831,8 +1831,9 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname
<listitem>
<para>
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
+ connection. This is only allowed with
+ <literal>sslmode=require</literal> or higher, because the weaker
+ settings could lead to unintended fallback to
plaintext authentication when the server does not support direct
SSL handshake.
</para>
@@ -9556,7 +9557,7 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*)
<para>
For backwards compatibility with earlier versions of PostgreSQL, if a
root CA file exists, the behavior of
- <literal>sslmode</literal>=<literal>require</literal> will be the same
+ <literal>sslmode=require</literal> will be the same
as that of <literal>verify-ca</literal>, 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 1b27d0a5479..659e77bcf2d 100644
--- a/doc/src/sgml/protocol.sgml
+++ b/doc/src/sgml/protocol.sgml
@@ -3247,7 +3247,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
</term>
<listitem>
<para>
- 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.
@@ -3312,11 +3312,11 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
</term>
<listitem>
<para>
- 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.
+ Option to send changes by their origin. Possible values are
+ <literal>none</literal> to only send the changes that have no origin
+ associated, or <literal>any</literal> to send the changes regardless of
+ their origin. This can be used to avoid loops (infinite replication of
+ the same data) among replication nodes.
</para>
</listitem>
</varlistentry>
diff --git a/doc/src/sgml/ref/alter_table.sgml b/doc/src/sgml/ref/alter_table.sgml
index 1a49f321cf7..3867a826e5f 100644
--- a/doc/src/sgml/ref/alter_table.sgml
+++ b/doc/src/sgml/ref/alter_table.sgml
@@ -1121,8 +1121,8 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
</para>
<para>
- All the forms of ALTER TABLE that act on a single table, except
- <literal>RENAME</literal>, <literal>SET SCHEMA</literal>,
+ All the forms of <command>ALTER TABLE</command> that act on a single table,
+ except <literal>RENAME</literal>, <literal>SET SCHEMA</literal>,
<literal>ATTACH PARTITION</literal>, and
<literal>DETACH PARTITION</literal> 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 1518af8a045..9ec9b85b3f5 100644
--- a/doc/src/sgml/ref/copy.sgml
+++ b/doc/src/sgml/ref/copy.sgml
@@ -427,7 +427,7 @@ COPY { <replaceable class="parameter">table_name</replaceable> [ ( <replaceable
<term><literal>LOG_VERBOSITY</literal></term>
<listitem>
<para>
- Specify the amount of messages emitted by a <command>COPY</command>
+ Specifies the amount of messages emitted by a <command>COPY</command>
command: <literal>default</literal> or <literal>verbose</literal>. If
<literal>verbose</literal> is specified, additional messages are emitted
during processing.
diff --git a/doc/src/sgml/ref/create_database.sgml b/doc/src/sgml/ref/create_database.sgml
index 7653cb902ee..af4eb1e4313 100644
--- a/doc/src/sgml/ref/create_database.sgml
+++ b/doc/src/sgml/ref/create_database.sgml
@@ -223,9 +223,9 @@ CREATE DATABASE <replaceable class="parameter">name</replaceable>
<term><replaceable class="parameter">builtin_locale</replaceable></term>
<listitem>
<para>
- Specifies the builtin provider locale for the database default
- collation order and character classification, overriding the setting
- <xref linkend="create-database-locale"/>. The <link
+ Specifies the <literal>builtin</literal> provider locale for the database
+ default collation order and character classification, overriding the
+ setting <xref linkend="create-database-locale"/>. The <link
linkend="create-database-locale-provider">locale provider</link> must
be <literal>builtin</literal>. The default is the setting of <xref
linkend="create-database-locale"/> if specified; otherwise the same
diff --git a/doc/src/sgml/ref/create_subscription.sgml b/doc/src/sgml/ref/create_subscription.sgml
index 740b7d94210..674ed23a02a 100644
--- a/doc/src/sgml/ref/create_subscription.sgml
+++ b/doc/src/sgml/ref/create_subscription.sgml
@@ -129,8 +129,8 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
Since no connection is made when this option is
<literal>false</literal>, no tables are subscribed. To initiate
replication, you must manually create the replication slot, enable
- the failover if required, enable the subscription, and refresh the
- subscription. See
+ the <literal>failover</literal> if required, enable the subscription,
+ and refresh the subscription. See
<xref linkend="logical-replication-subscription-examples-deferred-slot"/>
for examples.
</para>
@@ -185,7 +185,7 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
<para>
When setting <literal>slot_name</literal> to a valid name and
- <literal>create_slot</literal> to false, the
+ <literal>create_slot</literal> to <literal>false</literal>, the
<literal>failover</literal> property value of the named slot may
differ from the counterpart <literal>failover</literal> parameter
specified in the subscription. Always ensure the slot property
@@ -474,13 +474,13 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
<para>
If any table in the publication has a <literal>WHERE</literal> clause, rows
for which the <replaceable class="parameter">expression</replaceable>
- 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 <literal>WHERE</literal> clauses, a row will be published if any
- of the expressions (referring to that publish operation) are satisfied. In
- the case of different <literal>WHERE</literal> clauses, if one of the
- publications has no <literal>WHERE</literal> clause (referring to that
- publish operation) or the publication is declared as
+ evaluates to <literal>false</literal> or <literal>NULL</literal> will not be
+ published. If the subscription has several publications in which the same
+ table has been published wit different <literal>WHERE</literal> clauses, a
+ row will be published if an of the expressions (referring to that publish
+ operation) are satisfied. I the case of different <literal>WHERE</literal>
+ clauses, if one of the publications has no <literal>WHERE</literal> clause
+ (referring to that publish operation) or the publication is declared as
<link linkend="sql-createpublication-params-for-all-tables"><literal>FOR ALL TABLES</literal></link>
or <link linkend="sql-createpublication-params-for-tables-in-schema"><literal>FOR TABLES IN SCHEMA</literal></link>,
rows are always published regardless of the definition of the other
diff --git a/doc/src/sgml/ref/create_table.sgml b/doc/src/sgml/ref/create_table.sgml
index f19306e7760..975b2a1992b 100644
--- a/doc/src/sgml/ref/create_table.sgml
+++ b/doc/src/sgml/ref/create_table.sgml
@@ -2330,7 +2330,7 @@ CREATE TABLE cities_partdef
<para>
Currently, <productname>PostgreSQL</productname> does not record names
- for not-null constraints at all, so they are not
+ for <literal>NOT NULL</literal> constraints at all, so they are not
subject to the uniqueness restriction. This might change in a future
release.
</para>
diff --git a/doc/src/sgml/ref/createdb.sgml b/doc/src/sgml/ref/createdb.sgml
index 5c4e0465ed9..125a04d9256 100644
--- a/doc/src/sgml/ref/createdb.sgml
+++ b/doc/src/sgml/ref/createdb.sgml
@@ -154,8 +154,8 @@ PostgreSQL documentation
<term><option>--builtin-locale=<replaceable class="parameter">locale</replaceable></option></term>
<listitem>
<para>
- Specifies the locale name when the builtin provider is used. Locale support
- is described in <xref linkend="locale"/>.
+ Specifies the locale name when the <literal>builtin</literal> provider
+ is used. Locale support is described in <xref linkend="locale"/>.
</para>
</listitem>
</varlistentry>
diff --git a/doc/src/sgml/ref/initdb.sgml b/doc/src/sgml/ref/initdb.sgml
index bdd613e77ff..883d3515921 100644
--- a/doc/src/sgml/ref/initdb.sgml
+++ b/doc/src/sgml/ref/initdb.sgml
@@ -324,8 +324,8 @@ PostgreSQL documentation
<term><option>--builtin-locale=<replaceable>locale</replaceable></option></term>
<listitem>
<para>
- Specifies the locale name when the builtin provider is used. Locale support
- is described in <xref linkend="locale"/>.
+ Specifies the locale name when the <literal>builtin</literal> provider
+ is used. Locale support is described in <xref linkend="locale"/>.
</para>
</listitem>
</varlistentry>
diff --git a/doc/src/sgml/ref/merge.sgml b/doc/src/sgml/ref/merge.sgml
index 97b34b9fcaf..aa83a500b43 100644
--- a/doc/src/sgml/ref/merge.sgml
+++ b/doc/src/sgml/ref/merge.sgml
@@ -263,9 +263,10 @@ DELETE
<para>
If both <literal>WHEN NOT MATCHED BY SOURCE</literal> and
<literal>WHEN NOT MATCHED [BY TARGET]</literal> clauses are specified,
- the <command>MERGE</command> command will perform a <literal>FULL</literal>
- join between <replaceable class="parameter">data_source</replaceable>
- and the target table. For this to work, at least one
+ the <command>MERGE</command> command will perform a
+ <literal>FULL JOIN</literal> between
+ <replaceable class="parameter">data_source</replaceable> and the target
+ table. For this to work, at least one
<replaceable class="parameter">join_condition</replaceable> subexpression
must use an operator that can support a hash join, or all of the
subexpressions must use operators that can support a merge join.
diff --git a/doc/src/sgml/ref/pg_basebackup.sgml b/doc/src/sgml/ref/pg_basebackup.sgml
index 82d0c8e0088..e3e83b2ddc8 100644
--- a/doc/src/sgml/ref/pg_basebackup.sgml
+++ b/doc/src/sgml/ref/pg_basebackup.sgml
@@ -245,9 +245,9 @@ PostgreSQL documentation
that <application>pg_basebackup</application> is using, so that
streaming replication and <link linkend="logicaldecoding-replication-slots-synchronization">
logical replication slot synchronization</link> will use the same
- settings later on. The dbname will be recorded only if the dbname was
- specified explicitly in the connection string or <link linkend="libpq-envars">
- environment variable</link>.
+ settings later on. <literal>dbname</literal> will be recorded only
+ if it was specified explicitly in the connection string or
+ <link linkend="libpq-envars">environment variable</link>.
</para>
</listitem>
diff --git a/doc/src/sgml/ref/pgupgrade.sgml b/doc/src/sgml/ref/pgupgrade.sgml
index 9877f2f01c6..77019bab8fc 100644
--- a/doc/src/sgml/ref/pgupgrade.sgml
+++ b/doc/src/sgml/ref/pgupgrade.sgml
@@ -67,8 +67,9 @@ PostgreSQL documentation
</para>
<para>
- pg_upgrade supports upgrades from 9.2.X and later to the current
- major release of <productname>PostgreSQL</productname>, including snapshot and beta releases.
+ <application>pg_upgrade</application> supports upgrades from 9.2.X and later
+ to the current major release of <productname>PostgreSQL</productname>,
+ including snapshot and beta releases.
</para>
</refsect1>
diff --git a/doc/src/sgml/sepgsql.sgml b/doc/src/sgml/sepgsql.sgml
index 1b848f1977c..954b461c32a 100644
--- a/doc/src/sgml/sepgsql.sgml
+++ b/doc/src/sgml/sepgsql.sgml
@@ -87,7 +87,7 @@ Policy from config file: targeted
</para>
<para>
- To build this module specify <xref
+ To build this module, specify <xref
linkend="configure-option-with-sepgsql"/> (when using <link
linkend="install-make">make and autoconf</link> ) or <xref
linkend="configure-with-sepgsql-meson"/> (when using <link
diff --git a/doc/src/sgml/syntax.sgml b/doc/src/sgml/syntax.sgml
index 4dfbbd08626..916189a7d68 100644
--- a/doc/src/sgml/syntax.sgml
+++ b/doc/src/sgml/syntax.sgml
@@ -2496,7 +2496,7 @@ SELECT getf1(CAST(ROW(11,'this is a test',2.5) AS myrowtype));
linkend="functions-comparison"/>, to compare one row against another
as described in <xref linkend="functions-comparisons"/>, and to
use them in connection with subqueries, as discussed in <xref
- linkend="functions-subquery"/>,
+ linkend="functions-subquery"/>.
</para>
</sect2>
diff --git a/doc/src/sgml/system-views.sgml b/doc/src/sgml/system-views.sgml
index 8c18bea902f..db63d094ff2 100644
--- a/doc/src/sgml/system-views.sgml
+++ b/doc/src/sgml/system-views.sgml
@@ -2548,7 +2548,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
<structfield>invalidation_reason</structfield> column for the conflict
- reason. Always NULL for physical slots.
+ reason. Always <literal>NULL</literal> for physical slots.
</para></entry>
</row>
@@ -3907,7 +3907,7 @@ SELECT * FROM pg_locks pl LEFT JOIN pg_prepared_xacts ppx
range type column. (Null for non-range types.)
</para>
<para>
- This histogram is calculated using the <literal>subtype_diff</literal>
+ This histogram is calculated using the <function>subtype_diff</function>
range function regardless of whether range bounds are inclusive.
</para></entry>
</row>
diff --git a/doc/src/sgml/trigger.sgml b/doc/src/sgml/trigger.sgml
index 31626536a2e..f998e03acd3 100644
--- a/doc/src/sgml/trigger.sgml
+++ b/doc/src/sgml/trigger.sgml
@@ -357,10 +357,10 @@
<para>
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.
- 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
+ ordinary SQL <command>UPDATE</command> or <command>DELETE</command> 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
be to break referential integrity. It is the trigger programmer's
responsibility to avoid that.
</para>
diff --git a/doc/src/sgml/user-manag.sgml b/doc/src/sgml/user-manag.sgml
index 07a16247d76..9cf65ec749c 100644
--- a/doc/src/sgml/user-manag.sgml
+++ b/doc/src/sgml/user-manag.sgml
@@ -407,7 +407,7 @@ REVOKE <replaceable>group_role</replaceable> FROM <replaceable>role1</replaceabl
temporarily <quote>become</quote> 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
<literal>INHERIT</literal> 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 d5df65bc693..2eb282ab000 100644
--- a/doc/src/sgml/wal.sgml
+++ b/doc/src/sgml/wal.sgml
@@ -679,11 +679,11 @@
<para>
In some cases, when the WAL size on the primary increases quickly,
- for instance during massive INSERT,
+ for instance during massive <command>INSERT</command>,
the <structfield>restartpoints_req</structfield> 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.
^ permalink raw reply [nested|flat] 23+ messages in thread
* Re: Documentation improvement patch
2024-09-05 09:33 Documentation improvement patch Oleg Sibiryakov <o.sibiryakov@postgrespro.ru>
@ 2024-09-06 13:20 ` Daniel Gustafsson <daniel@yesql.se>
2024-09-10 11:46 ` Re: Documentation improvement patch Oleg Sibiryakov <o.sibiryakov@postgrespro.ru>
0 siblings, 1 reply; 23+ messages in thread
From: Daniel Gustafsson @ 2024-09-06 13:20 UTC (permalink / raw)
To: Oleg Sibiryakov <o.sibiryakov@postgrespro.ru>; +Cc: pgsql-docs@lists.postgresql.org
> On 5 Sep 2024, at 11:33, Oleg Sibiryakov <o.sibiryakov@postgrespro.ru> wrote:
>
> Dear all,
> I have prepared a patch containing some minor inconsistencies in the documentation. Please, take a look.
> The inconsistencies were noticed by: Ekaterina Kiryanova, Elena Indrupskaya, Maxim Yablokov, Anna Uraskova, Elena Karavaeva, and me.
> We will be looking forward to your feedback.
> The patch shall be applied to the REL_17_STABLE branch.
Most of these seem fine, but I need another read-through to digest them fully.
Just a few small comments:
- Specifies the builtin provider locale for the database default
- collation order and character classification, overriding the setting
- <xref linkend="create-database-locale"/>. The <link
+ Specifies the <literal>builtin</literal> provider locale for the database
+ default collation order and character classification, overriding the
+ setting <xref linkend="create-database-locale"/>. The <link
and
- Specifies the locale name when the builtin provider is used. Locale support
- is described in <xref linkend="locale"/>.
+ Specifies the locale name when the <literal>builtin</literal> provider
+ is used. Locale support is described in <xref linkend="locale"/>.
I don't think this use of "builtin" refers to the config value but rather the
type of locale, so I think it's correct to not use <literal> here.
- for not-null constraints at all, so they are not
+ for <literal>NOT NULL</literal> constraints at all, so they are not
This seems mostly to be a question of taste, I don't think not-null is
incorrect here.
--
Daniel Gustafsson
^ permalink raw reply [nested|flat] 23+ messages in thread
* Re: Documentation improvement patch
2024-09-05 09:33 Documentation improvement patch Oleg Sibiryakov <o.sibiryakov@postgrespro.ru>
2024-09-06 13:20 ` Re: Documentation improvement patch Daniel Gustafsson <daniel@yesql.se>
@ 2024-09-10 11:46 ` Oleg Sibiryakov <o.sibiryakov@postgrespro.ru>
2024-09-10 13:02 ` Re: Documentation improvement patch Daniel Gustafsson <daniel@yesql.se>
0 siblings, 1 reply; 23+ messages in thread
From: Oleg Sibiryakov @ 2024-09-10 11:46 UTC (permalink / raw)
To: Daniel Gustafsson <daniel@yesql.se>; +Cc: pgsql-docs@lists.postgresql.org
Thank you for your feedback.
1. Since we do not want to use <literal> here, I suggest we hyphenate it
as "built-in". What's your take on it?
2. Leaving not-null is fine.
--
Oleg Sibiryakov
On 06.09.2024 16:20, Daniel Gustafsson wrote:
>> On 5 Sep 2024, at 11:33, Oleg Sibiryakov <o.sibiryakov@postgrespro.ru> wrote:
>>
>> Dear all,
>> I have prepared a patch containing some minor inconsistencies in the documentation. Please, take a look.
>> The inconsistencies were noticed by: Ekaterina Kiryanova, Elena Indrupskaya, Maxim Yablokov, Anna Uraskova, Elena Karavaeva, and me.
>> We will be looking forward to your feedback.
>> The patch shall be applied to the REL_17_STABLE branch.
> Most of these seem fine, but I need another read-through to digest them fully.
> Just a few small comments:
>
> - Specifies the builtin provider locale for the database default
> - collation order and character classification, overriding the setting
> - <xref linkend="create-database-locale"/>. The <link
> + Specifies the <literal>builtin</literal> provider locale for the database
> + default collation order and character classification, overriding the
> + setting <xref linkend="create-database-locale"/>. The <link
> and
> - Specifies the locale name when the builtin provider is used. Locale support
> - is described in <xref linkend="locale"/>.
> + Specifies the locale name when the <literal>builtin</literal> provider
> + is used. Locale support is described in <xref linkend="locale"/>.
>
>
> I don't think this use of "builtin" refers to the config value but rather the
> type of locale, so I think it's correct to not use <literal> here.
>
>
> - for not-null constraints at all, so they are not
> + for <literal>NOT NULL</literal> constraints at all, so they are not
>
> This seems mostly to be a question of taste, I don't think not-null is
> incorrect here.
>
> --
> Daniel Gustafsson
>
>
>
^ permalink raw reply [nested|flat] 23+ messages in thread
* Re: Documentation improvement patch
2024-09-05 09:33 Documentation improvement patch Oleg Sibiryakov <o.sibiryakov@postgrespro.ru>
2024-09-06 13:20 ` Re: Documentation improvement patch Daniel Gustafsson <daniel@yesql.se>
2024-09-10 11:46 ` Re: Documentation improvement patch Oleg Sibiryakov <o.sibiryakov@postgrespro.ru>
@ 2024-09-10 13:02 ` Daniel Gustafsson <daniel@yesql.se>
2024-09-11 09:53 ` Re: Documentation improvement patch Peter Eisentraut <peter@eisentraut.org>
0 siblings, 1 reply; 23+ messages in thread
From: Daniel Gustafsson @ 2024-09-10 13:02 UTC (permalink / raw)
To: Oleg Sibiryakov <o.sibiryakov@postgrespro.ru>; +Cc: pgsql-docs@lists.postgresql.org
> On 10 Sep 2024, at 13:46, Oleg Sibiryakov <o.sibiryakov@postgrespro.ru> wrote:
> 1. Since we do not want to use <literal> here, I suggest we hyphenate it as "built-in". What's your take on it?
I think that's the right choice given the hyphenation used in the rest of the
docs. There are a few more places on that same page which should be built-in
rather than builtin to separate the concept from the parameter value.
--
Daniel Gustafsson
^ permalink raw reply [nested|flat] 23+ messages in thread
* Re: Documentation improvement patch
2024-09-05 09:33 Documentation improvement patch Oleg Sibiryakov <o.sibiryakov@postgrespro.ru>
2024-09-06 13:20 ` Re: Documentation improvement patch Daniel Gustafsson <daniel@yesql.se>
2024-09-10 11:46 ` Re: Documentation improvement patch Oleg Sibiryakov <o.sibiryakov@postgrespro.ru>
2024-09-10 13:02 ` Re: Documentation improvement patch Daniel Gustafsson <daniel@yesql.se>
@ 2024-09-11 09:53 ` Peter Eisentraut <peter@eisentraut.org>
2024-09-13 10:50 ` Re: Documentation improvement patch Oleg Sibiryakov <o.sibiryakov@postgrespro.ru>
0 siblings, 1 reply; 23+ messages in thread
From: Peter Eisentraut @ 2024-09-11 09:53 UTC (permalink / raw)
To: Daniel Gustafsson <daniel@yesql.se>; Oleg Sibiryakov <o.sibiryakov@postgrespro.ru>; +Cc: pgsql-docs@lists.postgresql.org
On 10.09.24 15:02, Daniel Gustafsson wrote:
>> On 10 Sep 2024, at 13:46, Oleg Sibiryakov <o.sibiryakov@postgrespro.ru> wrote:
>
>> 1. Since we do not want to use <literal> here, I suggest we hyphenate it as "built-in". What's your take on it?
>
> I think that's the right choice given the hyphenation used in the rest of the
> docs. There are a few more places on that same page which should be built-in
> rather than builtin to separate the concept from the parameter value.
I suspect that this would lead to the opposite confusion, people
complaining that the provider is called "builtin" not "built-in".
Arguably, the other providers are also "built in". There are no
user-pluggable providers at this time.
^ permalink raw reply [nested|flat] 23+ messages in thread
* Re: Documentation improvement patch
2024-09-05 09:33 Documentation improvement patch Oleg Sibiryakov <o.sibiryakov@postgrespro.ru>
2024-09-06 13:20 ` Re: Documentation improvement patch Daniel Gustafsson <daniel@yesql.se>
2024-09-10 11:46 ` Re: Documentation improvement patch Oleg Sibiryakov <o.sibiryakov@postgrespro.ru>
2024-09-10 13:02 ` Re: Documentation improvement patch Daniel Gustafsson <daniel@yesql.se>
2024-09-11 09:53 ` Re: Documentation improvement patch Peter Eisentraut <peter@eisentraut.org>
@ 2024-09-13 10:50 ` Oleg Sibiryakov <o.sibiryakov@postgrespro.ru>
2024-10-01 08:04 ` Re: Documentation improvement patch Oleg Sibiryakov <o.sibiryakov@postgrespro.ru>
0 siblings, 1 reply; 23+ messages in thread
From: Oleg Sibiryakov @ 2024-09-13 10:50 UTC (permalink / raw)
To: Peter Eisentraut <peter@eisentraut.org>; Daniel Gustafsson <daniel@yesql.se>; +Cc: pgsql-docs@lists.postgresql.org
Here is a patch without the builtin/built-in corrections (find attached).
But I still believe the issue should be discussed further.
We actually have two options: it is either a spelling mistake (since
built-in should written with a hyphen), or we miss the <literal> tag
(since it is actually also a value).
So I do think we cannot really leave it as is.
--
Oleg Sibiryakov
On 11.09.2024 12:53, Peter Eisentraut wrote:
> On 10.09.24 15:02, Daniel Gustafsson wrote:
>>> On 10 Sep 2024, at 13:46, Oleg Sibiryakov
>>> <o.sibiryakov@postgrespro.ru> wrote:
>>
>>> 1. Since we do not want to use <literal> here, I suggest we
>>> hyphenate it as "built-in". What's your take on it?
>>
>> I think that's the right choice given the hyphenation used in the
>> rest of the
>> docs. There are a few more places on that same page which should be
>> built-in
>> rather than builtin to separate the concept from the parameter value.
>
> I suspect that this would lead to the opposite confusion, people
> complaining that the provider is called "builtin" not "built-in".
>
> Arguably, the other providers are also "built in". There are no
> user-pluggable providers at this time.
>
>
>
Attachments:
[text/x-patch] doc-improvements_v2.patch (62.9K, ../../8718aeb8-4ecf-4090-a153-cc60760c307d@postgrespro.ru/2-doc-improvements_v2.patch)
download | inline diff:
diff --git a/doc/src/sgml/catalogs.sgml b/doc/src/sgml/catalogs.sgml
index a63cc71efa2..7a905fd6a3a 100644
--- a/doc/src/sgml/catalogs.sgml
+++ b/doc/src/sgml/catalogs.sgml
@@ -8012,41 +8012,41 @@ SCRAM-SHA-256$<replaceable><iteration count></replaceable>:<replaceable>&l
for authentication
</para></entry>
</row>
<row>
<entry role="catalog_table_entry"><para role="column_definition">
<structfield>subrunasowner</structfield> <type>bool</type>
</para>
<para>
If true, the subscription will be run with the permissions
of the subscription owner
</para></entry>
</row>
<row>
<entry role="catalog_table_entry"><para role="column_definition">
<structfield>subfailover</structfield> <type>bool</type>
</para>
<para>
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
</para></entry>
</row>
<row>
<entry role="catalog_table_entry"><para role="column_definition">
<structfield>subconninfo</structfield> <type>text</type>
</para>
<para>
Connection string to the upstream database
</para></entry>
</row>
<row>
<entry role="catalog_table_entry"><para role="column_definition">
<structfield>subslotname</structfield> <type>name</type>
</para>
<para>
Name of the replication slot in the upstream database (also used
for the local replication origin name);
diff --git a/doc/src/sgml/charset.sgml b/doc/src/sgml/charset.sgml
index 834cb30c85a..a76e9579a14 100644
--- a/doc/src/sgml/charset.sgml
+++ b/doc/src/sgml/charset.sgml
@@ -365,59 +365,59 @@ initdb --locale-provider=icu --icu-locale=en
Regardless of the locale provider, the operating system is still used to
provide some locale-aware behavior, such as messages (see <xref
linkend="guc-lc-messages"/>).
</para>
<para>
The available locale providers are listed below:
</para>
<variablelist>
<varlistentry>
<term><literal>builtin</literal></term>
<listitem>
<para>
The <literal>builtin</literal> provider uses built-in operations. Only
the <literal>C</literal> and <literal>C.UTF-8</literal> locales are
supported for this provider.
</para>
<para>
The <literal>C</literal> locale behavior is identical to the
- <literal>C</literal> locale in the libc provider. When using this
- locale, the behavior may depend on the database encoding.
+ <literal>C</literal> locale in the <literal>libc</literal> provider. When
+ using this locale, the behavior may depend on the database encoding.
</para>
<para>
The <literal>C.UTF-8</literal> locale is available only for when the
database encoding is <literal>UTF-8</literal>, and the behavior is
based on Unicode. The collation uses the code point values only. The
regular expression character classes are based on the "POSIX
Compatible" semantics, and the case mapping is the "simple" variant.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>icu</literal></term>
<listitem>
<para>
The <literal>icu</literal> provider uses the external
- ICU<indexterm><primary>ICU</primary></indexterm>
+ <indexterm><primary>ICU</primary></indexterm>
library. <productname>PostgreSQL</productname> must have been
configured with support.
</para>
<para>
ICU provides collation and character classification behavior that is
independent of the operating system and database encoding, which is
preferable if you expect to transition to other platforms without any
change in results. <literal>LC_COLLATE</literal> and
<literal>LC_CTYPE</literal> can be set independently of the ICU
locale.
</para>
<note>
<para>
For the ICU provider, results may depend on the version of the ICU
library used, as it is updated to reflect changes in natural language
over time.
</para>
</note>
</listitem>
</varlistentry>
@@ -845,76 +845,77 @@ SELECT * FROM test1 ORDER BY a || b COLLATE "fr_FR";
separate <quote>collate</quote> and <quote>ctype</quote> settings, so
they are always the same. Also, ICU collations are independent of the
encoding, so there is always only one ICU collation of a given name in
a database.
</para>
<sect3 id="collation-managing-standard">
<title>Standard Collations</title>
<para>
On all platforms, the following collations are supported:
<variablelist>
<varlistentry>
<term><literal>unicode</literal></term>
<listitem>
<para>
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
- different version of ICU. (This collation has the same behavior as
+ collation, and behavior may change if
+ <productname>PostgreSQL</productname> is built with a different version
+ of ICU. (This collation has the same behavior as
the ICU root locale; see <xref
linkend="collation-managing-predefined-icu-und-x-icu"/>.)
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>ucs_basic</literal></term>
<listitem>
<para>
This SQL standard collation sorts using the Unicode code point values
rather than natural language order, and only the ASCII letters
<quote><literal>A</literal></quote> through
<quote><literal>Z</literal></quote> are treated as letters. The
behavior is efficient and stable across all versions. Only available
for encoding <literal>UTF8</literal>. (This collation has the same
behavior as the libc locale specification <literal>C</literal> in
<literal>UTF8</literal> encoding.)
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>pg_c_utf8</literal></term>
<listitem>
<para>
This collation sorts by Unicode code point values rather than natural
language order. For the functions <function>lower</function>,
<function>initcap</function>, and <function>upper</function>, it uses
Unicode simple case mapping. For pattern matching (including regular
expressions), it uses the POSIX Compatible variant of Unicode <ulink
url="https://www.unicode.org/reports/tr18/#Compatibility_Properties">Compatibility
Properties</ulink>. Behavior is efficient and stable within a
- <productname>Postgres</productname> major version. This collation is
+ <productname>PostgreSQL</productname> major version. This collation is
only available for encoding <literal>UTF8</literal>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>C</literal> (equivalent to <literal>POSIX</literal>)</term>
<listitem>
<para>
The <literal>C</literal> and <literal>POSIX</literal> collations are
based on <quote>traditional C</quote> behavior. They sort by byte
values rather than natural language order, and only the ASCII letters
<quote><literal>A</literal></quote> through
<quote><literal>Z</literal></quote> are treated as letters. The
behavior is efficient and stable across all versions for a given
database encoding, but behavior may vary between different database
encodings.
</para>
</listitem>
</varlistentry>
diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml
index 7c60aeab4f6..2027308f89f 100644
--- a/doc/src/sgml/config.sgml
+++ b/doc/src/sgml/config.sgml
@@ -691,43 +691,44 @@ include_dir 'conf.d'
</para>
</listitem>
</varlistentry>
<varlistentry id="guc-max-connections" xreflabel="max_connections">
<term><varname>max_connections</varname> (<type>integer</type>)
<indexterm>
<primary><varname>max_connections</varname> configuration parameter</primary>
</indexterm>
</term>
<listitem>
<para>
Determines the maximum number of concurrent connections to the
database server. The default is typically 100 connections, but
might be less if your kernel settings will not support it (as
determined during <application>initdb</application>). This parameter can
only be set at server start.
</para>
<para>
- PostgreSQL sizes certain resources based directly on the value of
- <varname>max_connections</varname>. Increasing its value leads to
- higher allocation of those resources, including shared memory.
+ <productname>PostgreSQL</productname> sizes certain resources based
+ directly on the value of <varname>max_connections</varname>. Increasing
+ its value leads to higher allocation of those resources, including
+ shared memory.
</para>
<para>
When running a standby server, you must set this parameter to the
same or higher value than on the primary server. Otherwise, queries
will not be allowed in the standby server.
</para>
</listitem>
</varlistentry>
<varlistentry id="guc-reserved-connections" xreflabel="reserved_connections">
<term><varname>reserved_connections</varname> (<type>integer</type>)
<indexterm>
<primary><varname>reserved_connections</varname> configuration parameter</primary>
</indexterm>
</term>
<listitem>
<para>
Determines the number of connection <quote>slots</quote> that are
reserved for connections by roles with privileges of the
@@ -9367,41 +9368,41 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv;
<varlistentry id="guc-transaction-timeout" xreflabel="transaction_timeout">
<term><varname>transaction_timeout</varname> (<type>integer</type>)
<indexterm>
<primary><varname>transaction_timeout</varname> configuration parameter</primary>
</indexterm>
</term>
<listitem>
<para>
Terminate any session that spans longer than the specified amount of
time in a transaction. The limit applies both to explicit transactions
(started with <command>BEGIN</command>) and to an implicitly started
transaction corresponding to a single statement.
If this value is specified without units, it is taken as milliseconds.
A value of zero (the default) disables the timeout.
</para>
<para>
If <varname>transaction_timeout</varname> is shorter or equal to
<varname>idle_in_transaction_session_timeout</varname> or <varname>statement_timeout</varname>
- then the longer timeout is ignored.
+ then the longer timeout is ignored.
</para>
<para>
Setting <varname>transaction_timeout</varname> in
<filename>postgresql.conf</filename> is not recommended because it would
affect all sessions.
</para>
<note>
<para>
Prepared transactions are not subject to this timeout.
</para>
</note>
</listitem>
</varlistentry>
<varlistentry id="guc-lock-timeout" xreflabel="lock_timeout">
<term><varname>lock_timeout</varname> (<type>integer</type>)
<indexterm>
<primary><varname>lock_timeout</varname> configuration parameter</primary>
@@ -10825,41 +10826,41 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir'
<literal>off</literal>, an error is returned if the <command>ALTER
SYSTEM</command> command is executed. This parameter can only be set in
the <filename>postgresql.conf</filename> file or on the server command
line. The default value is <literal>on</literal>.
</para>
<para>
Note that this setting must not be regarded as a security feature. It
only disables the <literal>ALTER SYSTEM</literal> command. It does not
prevent a superuser from changing the configuration using other SQL
commands. A superuser has many ways of executing shell commands at
the operating system level, and can therefore modify
<literal>postgresql.auto.conf</literal> regardless of the value of
this setting.
</para>
<para>
Turning this setting off is intended for environments where the
configuration of <productname>PostgreSQL</productname> is managed by
some external tool.
- In such environments, a well intentioned superuser might
+ In such environments, a well-intentioned superuser might
<emphasis>mistakenly</emphasis> use <command>ALTER SYSTEM</command>
to change the configuration instead of using the external tool.
This might result in unintended behavior, such as the external tool
overwriting the change at some later point in time when it updates the
configuration.
Setting this parameter to <literal>off</literal> can
help avoid such mistakes.
</para>
<para>
This parameter only controls the use of <command>ALTER SYSTEM</command>.
The settings stored in <filename>postgresql.auto.conf</filename>
take effect even if <literal>allow_alter_system</literal> is set to
<literal>off</literal>.
</para>
</listitem>
</varlistentry>
</variablelist>
</sect2>
diff --git a/doc/src/sgml/ddl.sgml b/doc/src/sgml/ddl.sgml
index 220683b5eb4..1d2987e628d 100644
--- a/doc/src/sgml/ddl.sgml
+++ b/doc/src/sgml/ddl.sgml
@@ -296,41 +296,41 @@ INSERT INTO people (id, name, address) VALUE (<emphasis>DEFAULT</emphasis>, 'C',
value.
</para>
<para>
The clauses <literal>ALWAYS</literal> and <literal>BY DEFAULT</literal> in
the column definition determine how explicitly user-specified values are
handled in <command>INSERT</command> and <command>UPDATE</command>
commands. In an <command>INSERT</command> command, if
<literal>ALWAYS</literal> is selected, a user-specified value is only
accepted if the <command>INSERT</command> statement specifies
<literal>OVERRIDING SYSTEM VALUE</literal>. If <literal>BY
DEFAULT</literal> is selected, then the user-specified value takes
precedence. Thus, using <literal>BY DEFAULT</literal> results in a
behavior more similar to default values, where the default value can be
overridden by an explicit value, whereas <literal>ALWAYS</literal> provides
some more protection against accidentally inserting an explicit value.
</para>
<para>
The data type of an identity column must be one of the data types supported
- by sequences. (See <xref linkend="sql-createsequence"/>.) The properties
+ by sequences (see <xref linkend="sql-createsequence"/>). The properties
of the associated sequence may be specified when creating an identity
column (see <xref linkend="sql-createtable"/>) or changed afterwards (see
<xref linkend="sql-altertable"/>).
</para>
<para>
An identity column is automatically marked as <literal>NOT NULL</literal>.
An identity column, however, does not guarantee uniqueness. (A sequence
normally returns unique values, but a sequence could be reset, or values
could be inserted manually into the identity column, as discussed above.)
Uniqueness would need to be enforced using a <literal>PRIMARY KEY</literal>
or <literal>UNIQUE</literal> constraint.
</para>
<para>
In table inheritance hierarchies, identity columns and their properties in
a child table are independent of those in its parent tables. A child table
does not inherit identity columns or their properties automatically from
the parent. During <command>INSERT</command> or <command>UPDATE</command>,
a column is treated as an identity column if that column is an identity
diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index 6b2759e25a1..3bca9bc353f 100644
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -21364,41 +21364,41 @@ SELECT NULLIF(value, '(none)') ...
</para>
<para>
Description
</para>
<para>
Example(s)
</para></entry>
</row>
</thead>
<tbody>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>lower</primary>
</indexterm>
<function>lower</function> ( <type>anymultirange</type> )
<returnvalue>anyelement</returnvalue>
</para>
<para>
Extracts the lower bound of the multirange (<literal>NULL</literal> if the
- multirange is empty has no lower bound).
+ multirange is empty or has no lower bound).
</para>
<para>
<literal>lower('{[1.1,2.2)}'::nummultirange)</literal>
<returnvalue>1.1</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>upper</primary>
</indexterm>
<function>upper</function> ( <type>anymultirange</type> )
<returnvalue>anyelement</returnvalue>
</para>
<para>
Extracts the upper bound of the multirange (<literal>NULL</literal> if the
multirange is empty or has no upper bound).
</para>
<para>
diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml
index 068ee60771c..855806b739b 100644
--- a/doc/src/sgml/libpq.sgml
+++ b/doc/src/sgml/libpq.sgml
@@ -528,43 +528,43 @@ int PQsocketPoll(int sock, int forRead, int forWrite,
pg_usec_time_t end_time);
</synopsis>
</para>
<para>
This function performs polling of a file descriptor, optionally with
a timeout.
If <parameter>forRead</parameter> is nonzero, the
function will terminate when the socket is ready for
reading. If <parameter>forWrite</parameter> is nonzero,
the function will terminate when the
socket is ready for writing.
</para>
<para>
The timeout is specified by <parameter>end_time</parameter>, which
is the time to stop waiting expressed as a number of microseconds since
the Unix epoch (that is, <type>time_t</type> times 1 million).
Timeout is infinite if <parameter>end_time</parameter>
is <literal>-1</literal>. Timeout is immediate (no blocking) if
- end_time is <literal>0</literal> (or indeed, any time before now).
- Timeout values can be calculated conveniently by adding the desired
- number of microseconds to the result of
+ <parameter>end_time</parameter> is <literal>0</literal> (or indeed, any
+ time before now). Timeout values can be calculated conveniently by adding
+ the desired number of microseconds to the result of
<xref linkend="libpq-PQgetCurrentTimeUSec"/>.
Note that the underlying system calls may have less than microsecond
precision, so that the actual delay may be imprecise.
</para>
<para>
The function returns a value greater than <literal>0</literal> if the
specified condition is met, <literal>0</literal> if a timeout occurred,
or <literal>-1</literal> if an error occurred. The error can be
retrieved by checking the <literal>errno(3)</literal> value. In the
event both <parameter>forRead</parameter>
and <parameter>forWrite</parameter> are zero, the function immediately
returns a timeout indication.
</para>
<para>
<function>PQsocketPoll</function> is implemented using either
<function>poll(2)</function> or <function>select(2)</function>,
depending on platform. See <literal>POLLIN</literal>
and <literal>POLLOUT</literal> from <function>poll(2)</function>,
@@ -1814,42 +1814,43 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname
option was introduced in <productname>PostgreSQL</productname> version
17.
</para>
<variablelist>
<varlistentry>
<term><literal>postgres</literal></term>
<listitem>
<para>
perform <productname>PostgreSQL</productname> protocol
negotiation. This is the default if the option is not provided.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>direct</literal></term>
<listitem>
<para>
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
+ connection. This is only allowed with
+ <literal>sslmode=require</literal> or higher, because the weaker
+ settings could lead to unintended fallback to
plaintext authentication when the server does not support direct
SSL handshake.
</para>
</listitem>
</varlistentry>
</variablelist>
</listitem>
</varlistentry>
<varlistentry id="libpq-connect-sslcompression" xreflabel="sslcompression">
<term><literal>sslcompression</literal></term>
<listitem>
<para>
If set to 1, data sent over SSL connections will be compressed. If
set to 0, compression will be disabled. The default is 0. This
parameter is ignored if a connection without SSL is made.
</para>
<para>
SSL compression is nowadays considered insecure and its use is no
@@ -9539,41 +9540,41 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*)
<para>
Certificate Revocation List (CRL) entries are also checked
if the file <filename>~/.postgresql/root.crl</filename> exists
(<filename>%APPDATA%\postgresql\root.crl</filename> on Microsoft
Windows).
</para>
<para>
The location of the root certificate file and the CRL can be changed by
setting
the connection parameters <literal>sslrootcert</literal> and <literal>sslcrl</literal>
or the environment variables <envar>PGSSLROOTCERT</envar> and <envar>PGSSLCRL</envar>.
<literal>sslcrldir</literal> or the environment variable <envar>PGSSLCRLDIR</envar>
can also be used to specify a directory containing CRL files.
</para>
<note>
<para>
For backwards compatibility with earlier versions of PostgreSQL, if a
root CA file exists, the behavior of
- <literal>sslmode</literal>=<literal>require</literal> will be the same
+ <literal>sslmode=require</literal> will be the same
as that of <literal>verify-ca</literal>, meaning the server certificate
is validated against the CA. Relying on this behavior is discouraged,
and applications that need certificate validation should always use
<literal>verify-ca</literal> or <literal>verify-full</literal>.
</para>
</note>
</sect2>
<sect2 id="libpq-ssl-clientcert">
<title>Client Certificates</title>
<para>
If the server attempts to verify the identity of the
client by requesting the client's leaf certificate,
<application>libpq</application> will send the certificate(s) stored in
file <filename>~/.postgresql/postgresql.crt</filename> in the user's home
directory. The certificates must chain to the root certificate trusted
by the server. A matching
private key file <filename>~/.postgresql/postgresql.key</filename> must also
be present.
diff --git a/doc/src/sgml/protocol.sgml b/doc/src/sgml/protocol.sgml
index 1b27d0a5479..659e77bcf2d 100644
--- a/doc/src/sgml/protocol.sgml
+++ b/doc/src/sgml/protocol.sgml
@@ -3230,41 +3230,41 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
and above, and it allows streaming of large in-progress transactions.
</para>
<para>
Version <literal>3</literal> is supported only for server version 15
and above, and it allows streaming of two-phase commits.
</para>
<para>
Version <literal>4</literal> is supported only for server version 16
and above, and it allows streams of large in-progress transactions to
be applied in parallel.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
publication_names
</term>
<listitem>
<para>
- 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.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
binary
</term>
<listitem>
<para>
Boolean option to use binary transfer mode. Binary mode is faster
than the text mode but slightly less robust.
</para>
</listitem>
</varlistentry>
<varlistentry>
@@ -3295,45 +3295,45 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
</varlistentry>
<varlistentry>
<term>
two_phase
</term>
<listitem>
<para>
Boolean option to enable two-phase transactions. Minimum protocol
version 3 is required to turn it on.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
origin
</term>
<listitem>
<para>
- 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.
+ Option to send changes by their origin. Possible values are
+ <literal>none</literal> to only send the changes that have no origin
+ associated, or <literal>any</literal> to send the changes regardless of
+ their origin. This can be used to avoid loops (infinite replication of
+ the same data) among replication nodes.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</sect2>
<sect2 id="protocol-logical-messages">
<title>Logical Replication Protocol Messages</title>
<para>
The individual protocol messages are discussed in the following
subsections. Individual messages are described in
<xref linkend="protocol-logicalrep-message-formats"/>.
</para>
<para>
All top-level protocol messages begin with a message type byte.
While represented in code as a character, this is a signed byte with no
diff --git a/doc/src/sgml/ref/alter_table.sgml b/doc/src/sgml/ref/alter_table.sgml
index 1a49f321cf7..3867a826e5f 100644
--- a/doc/src/sgml/ref/alter_table.sgml
+++ b/doc/src/sgml/ref/alter_table.sgml
@@ -1104,42 +1104,42 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
table and <literal>ACCESS EXCLUSIVE</literal> on the partition,
and the detach process completes. A <literal>CHECK</literal> constraint
that duplicates the partition constraint is added to the partition.
<literal>CONCURRENTLY</literal> cannot be run in a transaction block and
is not allowed if the partitioned table contains a default partition.
</para>
<para>
If <literal>FINALIZE</literal> is specified, a previous
<literal>DETACH CONCURRENTLY</literal> invocation that was canceled or
interrupted is completed.
At most one partition in a partitioned table can be pending detach at
a time.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>
- All the forms of ALTER TABLE that act on a single table, except
- <literal>RENAME</literal>, <literal>SET SCHEMA</literal>,
+ All the forms of <command>ALTER TABLE</command> that act on a single table,
+ except <literal>RENAME</literal>, <literal>SET SCHEMA</literal>,
<literal>ATTACH PARTITION</literal>, and
<literal>DETACH PARTITION</literal> can be combined into
a list of multiple alterations to be applied together. For example, it
is possible to add several columns and/or alter the type of several
columns in a single command. This is particularly useful with large
tables, since only one pass over the table need be made.
</para>
<para>
You must own the table to use <command>ALTER TABLE</command>.
To change the schema or tablespace of a table, you must also have
<literal>CREATE</literal> privilege on the new schema or tablespace.
To add the table as a new child of a parent table, you must own the parent
table as well. Also, to attach a table as a new partition of the table,
you must own the table being attached.
To alter the owner, you must be able to <literal>SET ROLE</literal> to the
new owning role, and that role must have <literal>CREATE</literal>
privilege on the table's schema.
(These restrictions enforce that altering the owner
doesn't do anything you couldn't do by dropping and recreating the table.
diff --git a/doc/src/sgml/ref/copy.sgml b/doc/src/sgml/ref/copy.sgml
index 1518af8a045..9ec9b85b3f5 100644
--- a/doc/src/sgml/ref/copy.sgml
+++ b/doc/src/sgml/ref/copy.sgml
@@ -410,41 +410,41 @@ COPY { <replaceable class="parameter">table_name</replaceable> [ ( <replaceable
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>ENCODING</literal></term>
<listitem>
<para>
Specifies that the file is encoded in the <replaceable
class="parameter">encoding_name</replaceable>. If this option is
omitted, the current client encoding is used. See the Notes below
for more details.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>LOG_VERBOSITY</literal></term>
<listitem>
<para>
- Specify the amount of messages emitted by a <command>COPY</command>
+ Specifies the amount of messages emitted by a <command>COPY</command>
command: <literal>default</literal> or <literal>verbose</literal>. If
<literal>verbose</literal> is specified, additional messages are emitted
during processing.
</para>
<para>
This is currently used in <command>COPY FROM</command> command when
<literal>ON_ERROR</literal> option is set to <literal>ignore</literal>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>WHERE</literal></term>
<listitem>
<para>
The optional <literal>WHERE</literal> clause has the general form
<synopsis>
WHERE <replaceable class="parameter">condition</replaceable>
</synopsis>
where <replaceable class="parameter">condition</replaceable> is
diff --git a/doc/src/sgml/ref/create_subscription.sgml b/doc/src/sgml/ref/create_subscription.sgml
index 740b7d94210..674ed23a02a 100644
--- a/doc/src/sgml/ref/create_subscription.sgml
+++ b/doc/src/sgml/ref/create_subscription.sgml
@@ -112,42 +112,42 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
<varlistentry id="sql-createsubscription-params-with-connect">
<term><literal>connect</literal> (<type>boolean</type>)</term>
<listitem>
<para>
Specifies whether the <command>CREATE SUBSCRIPTION</command>
command should connect to the publisher at all. The default
is <literal>true</literal>. Setting this to
<literal>false</literal> will force the values of
<literal>create_slot</literal>, <literal>enabled</literal> and
<literal>copy_data</literal> to <literal>false</literal>.
(You cannot combine setting <literal>connect</literal>
to <literal>false</literal> with
setting <literal>create_slot</literal>, <literal>enabled</literal>,
or <literal>copy_data</literal> to <literal>true</literal>.)
</para>
<para>
Since no connection is made when this option is
<literal>false</literal>, no tables are subscribed. To initiate
replication, you must manually create the replication slot, enable
- the failover if required, enable the subscription, and refresh the
- subscription. See
+ the <literal>failover</literal> if required, enable the subscription,
+ and refresh the subscription. See
<xref linkend="logical-replication-subscription-examples-deferred-slot"/>
for examples.
</para>
</listitem>
</varlistentry>
<varlistentry id="sql-createsubscription-params-with-create-slot">
<term><literal>create_slot</literal> (<type>boolean</type>)</term>
<listitem>
<para>
Specifies whether the command should create the replication slot on
the publisher. The default is <literal>true</literal>.
</para>
<para>
If set to <literal>false</literal>, you are responsible for
creating the publisher's slot in some other way. See
<xref linkend="logical-replication-subscription-examples-deferred-slot"/>
for examples.
</para>
</listitem>
@@ -168,41 +168,41 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
<term><literal>slot_name</literal> (<type>string</type>)</term>
<listitem>
<para>
Name of the publisher's replication slot to use. The default is
to use the name of the subscription for the slot name.
</para>
<para>
Setting <literal>slot_name</literal> to <literal>NONE</literal>
means there will be no replication slot associated with the
subscription. Such subscriptions must also have both
<literal>enabled</literal> and <literal>create_slot</literal> set to
<literal>false</literal>. Use this when you will be creating the
replication slot later manually. See
<xref linkend="logical-replication-subscription-examples-deferred-slot"/>
for examples.
</para>
<para>
When setting <literal>slot_name</literal> to a valid name and
- <literal>create_slot</literal> to false, the
+ <literal>create_slot</literal> to <literal>false</literal>, the
<literal>failover</literal> property value of the named slot may
differ from the counterpart <literal>failover</literal> parameter
specified in the subscription. Always ensure the slot property
<literal>failover</literal> matches the counterpart parameter of the
subscription and vice versa. Otherwise, the slot on the publisher may
behave differently from what these subscription options say: for
example, the slot on the publisher could either be synced to the
standbys even when the subscription's <literal>failover</literal>
option is disabled or could be disabled for sync even when the
subscription's <literal>failover</literal> option is enabled.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>
The following parameters control the subscription's replication
behavior after it has been created:
@@ -457,47 +457,47 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
</para>
<para>
Creating a subscription that connects to the same database cluster (for
example, to replicate between databases in the same cluster or to replicate
within the same database) will only succeed if the replication slot is not
created as part of the same command. Otherwise, the <command>CREATE
SUBSCRIPTION</command> call will hang. To make this work, create the
replication slot separately (using the
function <function>pg_create_logical_replication_slot</function> with the
plugin name <literal>pgoutput</literal>) and create the subscription using
the parameter <literal>create_slot = false</literal>. See
<xref linkend="logical-replication-subscription-examples-deferred-slot"/>
for examples. This is an implementation restriction that might be lifted in a
future release.
</para>
<para>
If any table in the publication has a <literal>WHERE</literal> clause, rows
for which the <replaceable class="parameter">expression</replaceable>
- 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 <literal>WHERE</literal> clauses, a row will be published if any
- of the expressions (referring to that publish operation) are satisfied. In
- the case of different <literal>WHERE</literal> clauses, if one of the
- publications has no <literal>WHERE</literal> clause (referring to that
- publish operation) or the publication is declared as
+ evaluates to <literal>false</literal> or <literal>NULL</literal> will not be
+ published. If the subscription has several publications in which the same
+ table has been published wit different <literal>WHERE</literal> clauses, a
+ row will be published if an of the expressions (referring to that publish
+ operation) are satisfied. I the case of different <literal>WHERE</literal>
+ clauses, if one of the publications has no <literal>WHERE</literal> clause
+ (referring to that publish operation) or the publication is declared as
<link linkend="sql-createpublication-params-for-all-tables"><literal>FOR ALL TABLES</literal></link>
or <link linkend="sql-createpublication-params-for-tables-in-schema"><literal>FOR TABLES IN SCHEMA</literal></link>,
rows are always published regardless of the definition of the other
expressions. If the subscriber is a <productname>PostgreSQL</productname>
version before 15, then any row filtering is ignored during the initial data
synchronization phase. For this case, the user might want to consider
deleting any initially copied data that would be incompatible with
subsequent filtering. Because initial data synchronization does not take
into account the publication
<link linkend="sql-createpublication-params-with-publish"><literal>publish</literal></link>
parameter when copying existing table data, some rows may be copied that
would not be replicated using DML. See
<xref linkend="logical-replication-subscription-examples"/> for examples.
</para>
<para>
Subscriptions having several publications in which the same table has been
published with different column lists are not supported.
</para>
diff --git a/doc/src/sgml/ref/create_table.sgml b/doc/src/sgml/ref/create_table.sgml
index f19306e7760..975b2a1992b 100644
--- a/doc/src/sgml/ref/create_table.sgml
+++ b/doc/src/sgml/ref/create_table.sgml
@@ -2313,41 +2313,41 @@ CREATE TABLE cities_partdef
</refsect2>
<refsect2>
<title>Constraint Naming</title>
<para>
The SQL standard says that table and domain constraints must have names
that are unique across the schema containing the table or domain.
<productname>PostgreSQL</productname> is laxer: it only requires
constraint names to be unique across the constraints attached to a
particular table or domain. However, this extra freedom does not exist
for index-based constraints (<literal>UNIQUE</literal>,
<literal>PRIMARY KEY</literal>, and <literal>EXCLUDE</literal>
constraints), because the associated index is named the same as the
constraint, and index names must be unique across all relations within
the same schema.
</para>
<para>
Currently, <productname>PostgreSQL</productname> does not record names
- for not-null constraints at all, so they are not
+ for <literal>NOT NULL</literal> constraints at all, so they are not
subject to the uniqueness restriction. This might change in a future
release.
</para>
</refsect2>
<refsect2>
<title>Inheritance</title>
<para>
Multiple inheritance via the <literal>INHERITS</literal> clause is
a <productname>PostgreSQL</productname> language extension.
SQL:1999 and later define single inheritance using a
different syntax and different semantics. SQL:1999-style
inheritance is not yet supported by
<productname>PostgreSQL</productname>.
</para>
</refsect2>
<refsect2>
<title>Zero-Column Tables</title>
diff --git a/doc/src/sgml/ref/merge.sgml b/doc/src/sgml/ref/merge.sgml
index 97b34b9fcaf..aa83a500b43 100644
--- a/doc/src/sgml/ref/merge.sgml
+++ b/doc/src/sgml/ref/merge.sgml
@@ -246,43 +246,44 @@ DELETE
<para>
<replaceable class="parameter">join_condition</replaceable> is
an expression resulting in a value of type
<type>boolean</type> (similar to a <literal>WHERE</literal>
clause) that specifies which rows in the
<replaceable class="parameter">data_source</replaceable>
match rows in the target table.
</para>
<warning>
<para>
Only columns from the target table
that attempt to match <replaceable class="parameter">data_source</replaceable>
rows should appear in <replaceable class="parameter">join_condition</replaceable>.
<replaceable class="parameter">join_condition</replaceable> subexpressions that
only reference the target table's
columns can affect which action is taken, often in surprising ways.
</para>
<para>
If both <literal>WHEN NOT MATCHED BY SOURCE</literal> and
<literal>WHEN NOT MATCHED [BY TARGET]</literal> clauses are specified,
- the <command>MERGE</command> command will perform a <literal>FULL</literal>
- join between <replaceable class="parameter">data_source</replaceable>
- and the target table. For this to work, at least one
+ the <command>MERGE</command> command will perform a
+ <literal>FULL JOIN</literal> between
+ <replaceable class="parameter">data_source</replaceable> and the target
+ table. For this to work, at least one
<replaceable class="parameter">join_condition</replaceable> subexpression
must use an operator that can support a hash join, or all of the
subexpressions must use operators that can support a merge join.
</para>
</warning>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="parameter">when_clause</replaceable></term>
<listitem>
<para>
At least one <literal>WHEN</literal> clause is required.
</para>
<para>
The <literal>WHEN</literal> clause may specify <literal>WHEN MATCHED</literal>,
<literal>WHEN NOT MATCHED BY SOURCE</literal>, or
<literal>WHEN NOT MATCHED [BY TARGET]</literal>.
Note that the <acronym>SQL</acronym> standard only defines
<literal>WHEN MATCHED</literal> and <literal>WHEN NOT MATCHED</literal>
diff --git a/doc/src/sgml/ref/pg_basebackup.sgml b/doc/src/sgml/ref/pg_basebackup.sgml
index 82d0c8e0088..e3e83b2ddc8 100644
--- a/doc/src/sgml/ref/pg_basebackup.sgml
+++ b/doc/src/sgml/ref/pg_basebackup.sgml
@@ -228,43 +228,43 @@ PostgreSQL documentation
<term><option>-R</option></term>
<term><option>--write-recovery-conf</option></term>
<listitem>
<para>
Creates a
<link linkend="file-standby-signal"><filename>standby.signal</filename></link>
<indexterm><primary><filename>standby.signal</filename></primary><secondary>pg_basebackup --write-recovery-conf</secondary></indexterm>
file and appends
connection settings to the <filename>postgresql.auto.conf</filename>
file in the target directory (or within the base archive file when
using tar format). This eases setting up a standby server using the
results of the backup.
</para>
<para>
The <filename>postgresql.auto.conf</filename> file will record the connection
settings and, if specified, the replication slot
that <application>pg_basebackup</application> is using, so that
streaming replication and <link linkend="logicaldecoding-replication-slots-synchronization">
logical replication slot synchronization</link> will use the same
- settings later on. The dbname will be recorded only if the dbname was
- specified explicitly in the connection string or <link linkend="libpq-envars">
- environment variable</link>.
+ settings later on. <literal>dbname</literal> will be recorded only
+ if it was specified explicitly in the connection string or
+ <link linkend="libpq-envars">environment variable</link>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-t <replaceable class="parameter">target</replaceable></option></term>
<term><option>--target=<replaceable class="parameter">target</replaceable></option></term>
<listitem>
<para>
Instructs the server where to place the base backup. The default target
is <literal>client</literal>, which specifies that the backup should
be sent to the machine where <application>pg_basebackup</application>
is running. If the target is instead set to
<literal>server:/some/path</literal>, the backup will be stored on
the machine where the server is running in the
<literal>/some/path</literal> directory. Storing a backup on the
server requires superuser privileges or having privileges of the
<literal>pg_write_server_files</literal> role. If the target is set to
diff --git a/doc/src/sgml/ref/pgupgrade.sgml b/doc/src/sgml/ref/pgupgrade.sgml
index 9877f2f01c6..77019bab8fc 100644
--- a/doc/src/sgml/ref/pgupgrade.sgml
+++ b/doc/src/sgml/ref/pgupgrade.sgml
@@ -50,42 +50,43 @@ PostgreSQL documentation
change the layout of the system tables, but the internal data storage
format rarely changes. <application>pg_upgrade</application> uses this fact
to perform rapid upgrades by creating new system tables and simply
reusing the old user data files. If a future major release ever
changes the data storage format in a way that makes the old data
format unreadable, <application>pg_upgrade</application> will not be usable
for such upgrades. (The community will attempt to avoid such
situations.)
</para>
<para>
<application>pg_upgrade</application> does its best to
make sure the old and new clusters are binary-compatible, e.g., by
checking for compatible compile-time settings, including 32/64-bit
binaries. It is important that
any external modules are also binary compatible, though this cannot
be checked by <application>pg_upgrade</application>.
</para>
<para>
- pg_upgrade supports upgrades from 9.2.X and later to the current
- major release of <productname>PostgreSQL</productname>, including snapshot and beta releases.
+ <application>pg_upgrade</application> supports upgrades from 9.2.X and later
+ to the current major release of <productname>PostgreSQL</productname>,
+ including snapshot and beta releases.
</para>
</refsect1>
<refsect1>
<title>Options</title>
<para>
<application>pg_upgrade</application> accepts the following command-line arguments:
<variablelist>
<varlistentry>
<term><option>-b</option> <replaceable>bindir</replaceable></term>
<term><option>--old-bindir=</option><replaceable>bindir</replaceable></term>
<listitem><para>the old PostgreSQL executable directory;
environment variable <envar>PGBINOLD</envar></para></listitem>
</varlistentry>
<varlistentry>
<term><option>-B</option> <replaceable>bindir</replaceable></term>
diff --git a/doc/src/sgml/sepgsql.sgml b/doc/src/sgml/sepgsql.sgml
index 1b848f1977c..954b461c32a 100644
--- a/doc/src/sgml/sepgsql.sgml
+++ b/doc/src/sgml/sepgsql.sgml
@@ -70,41 +70,41 @@
versions).
</para>
<para>
The <command>sestatus</command> command allows you to check the status of
<productname>SELinux</productname>. A typical display is:
<screen>
$ sestatus
SELinux status: enabled
SELinuxfs mount: /selinux
Current mode: enforcing
Mode from config file: enforcing
Policy version: 24
Policy from config file: targeted
</screen>
If <productname>SELinux</productname> is disabled or not installed, you must set
that product up first before installing this module.
</para>
<para>
- To build this module specify <xref
+ To build this module, specify <xref
linkend="configure-option-with-sepgsql"/> (when using <link
linkend="install-make">make and autoconf</link> ) or <xref
linkend="configure-with-sepgsql-meson"/> (when using <link
linkend="install-meson">meson</link>).
Be sure that the <filename>libselinux-devel</filename> RPM is installed at
build time.
</para>
<para>
To use this module, you must include <literal>sepgsql</literal>
in the <xref linkend="guc-shared-preload-libraries"/> parameter in
<filename>postgresql.conf</filename>. The module will not function correctly
if loaded in any other manner. Once the module is loaded, you
should execute <filename>sepgsql.sql</filename> in each database.
This will install functions needed for security label management, and
assign initial security labels.
</para>
<para>
diff --git a/doc/src/sgml/syntax.sgml b/doc/src/sgml/syntax.sgml
index 4dfbbd08626..916189a7d68 100644
--- a/doc/src/sgml/syntax.sgml
+++ b/doc/src/sgml/syntax.sgml
@@ -2479,41 +2479,41 @@ SELECT getf1(ROW(1,2.5,'this is a test')::mytable);
-------
1
(1 row)
SELECT getf1(CAST(ROW(11,'this is a test',2.5) AS myrowtype));
getf1
-------
11
(1 row)
</programlisting>
</para>
<para>
Row constructors can be used to build composite values to be stored
in a composite-type table column, or to be passed to a function that
accepts a composite parameter. Also, it is possible to test rows
using the standard comparison operators as described in <xref
linkend="functions-comparison"/>, to compare one row against another
as described in <xref linkend="functions-comparisons"/>, and to
use them in connection with subqueries, as discussed in <xref
- linkend="functions-subquery"/>,
+ linkend="functions-subquery"/>.
</para>
</sect2>
<sect2 id="syntax-express-eval">
<title>Expression Evaluation Rules</title>
<indexterm>
<primary>expression</primary>
<secondary>order of evaluation</secondary>
</indexterm>
<para>
The order of evaluation of subexpressions is not defined. In
particular, the inputs of an operator or function are not necessarily
evaluated left-to-right or in any other fixed order.
</para>
<para>
Furthermore, if the result of an expression can be determined by
diff --git a/doc/src/sgml/system-views.sgml b/doc/src/sgml/system-views.sgml
index 8c18bea902f..db63d094ff2 100644
--- a/doc/src/sgml/system-views.sgml
+++ b/doc/src/sgml/system-views.sgml
@@ -2531,41 +2531,41 @@ SELECT * FROM pg_locks pl LEFT JOIN pg_prepared_xacts ppx
The time since the slot has become inactive.
<literal>NULL</literal> if the slot is currently being used.
Note that for slots on the standby that are being synced from a
primary server (whose <structfield>synced</structfield> field is
<literal>true</literal>), the
<structfield>inactive_since</structfield> indicates the last
synchronization (see
<xref linkend="logicaldecoding-replication-slots-synchronization"/>)
time.
</para></entry>
</row>
<row>
<entry role="catalog_table_entry"><para role="column_definition">
<structfield>conflicting</structfield> <type>bool</type>
</para>
<para>
True if this logical slot conflicted with recovery (and so is now
invalidated). When this column is true, check
<structfield>invalidation_reason</structfield> column for the conflict
- reason. Always NULL for physical slots.
+ reason. Always <literal>NULL</literal> for physical slots.
</para></entry>
</row>
<row>
<entry role="catalog_table_entry"><para role="column_definition">
<structfield>invalidation_reason</structfield> <type>text</type>
</para>
<para>
The reason for the slot's invalidation. It is set for both logical and
physical slots. <literal>NULL</literal> if the slot is not invalidated.
Possible values are:
<itemizedlist spacing="compact">
<listitem>
<para>
<literal>wal_removed</literal> means that the required WAL has been
removed.
</para>
</listitem>
<listitem>
<para>
@@ -3890,41 +3890,41 @@ SELECT * FROM pg_locks pl LEFT JOIN pg_prepared_xacts ppx
<row>
<entry role="catalog_table_entry"><para role="column_definition">
<structfield>elem_count_histogram</structfield> <type>float4[]</type>
</para>
<para>
A histogram of the counts of distinct non-null element values within the
values of the column, followed by the average number of distinct
non-null elements. (Null for scalar types.)
</para></entry>
</row>
<row>
<entry role="catalog_table_entry"><para role="column_definition">
<structfield>range_length_histogram</structfield> <type>anyarray</type>
</para>
<para>
A histogram of the lengths of non-empty and non-null range values of a
range type column. (Null for non-range types.)
</para>
<para>
- This histogram is calculated using the <literal>subtype_diff</literal>
+ This histogram is calculated using the <function>subtype_diff</function>
range function regardless of whether range bounds are inclusive.
</para></entry>
</row>
<row>
<entry role="catalog_table_entry"><para role="column_definition">
<structfield>range_empty_frac</structfield> <type>float4</type>
</para>
<para>
Fraction of column entries whose values are empty ranges.
(Null for non-range types.)
</para></entry>
</row>
<row>
<entry role="catalog_table_entry"><para role="column_definition">
<structfield>range_bounds_histogram</structfield> <type>anyarray</type>
</para>
<para>
A histogram of lower and upper bounds of non-empty and non-null range
diff --git a/doc/src/sgml/trigger.sgml b/doc/src/sgml/trigger.sgml
index 31626536a2e..f998e03acd3 100644
--- a/doc/src/sgml/trigger.sgml
+++ b/doc/src/sgml/trigger.sgml
@@ -340,44 +340,44 @@
<literal>AFTER</literal>, the <literal>BEFORE</literal> case is more efficient, since
the information about
the operation doesn't have to be saved until end of statement.
</para>
<para>
If a trigger function executes SQL commands then these
commands might fire triggers again. This is known as cascading
triggers. There is no direct limitation on the number of cascade
levels. It is possible for cascades to cause a recursive invocation
of the same trigger; for example, an <command>INSERT</command>
trigger might execute a command that inserts an additional row
into the same table, causing the <command>INSERT</command> trigger
to be fired again. It is the trigger programmer's responsibility
to avoid infinite recursion in such scenarios.
</para>
<para>
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.
- 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
+ ordinary SQL <command>UPDATE</command> or <command>DELETE</command> 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
be to break referential integrity. It is the trigger programmer's
responsibility to avoid that.
</para>
<para>
<indexterm>
<primary>trigger</primary>
<secondary>arguments for trigger functions</secondary>
</indexterm>
When a trigger is being defined, arguments can be specified for
it. The purpose of including arguments in the
trigger definition is to allow different triggers with similar
requirements to call the same function. As an example, there
could be a generalized trigger function that takes as its
arguments two column names and puts the current user in one and
the current time stamp in the other. Properly written, this
trigger function would be independent of the specific table it is
triggering on. So the same function could be used for
<command>INSERT</command> events on any table with suitable
columns, to automatically track creation of records in a
diff --git a/doc/src/sgml/user-manag.sgml b/doc/src/sgml/user-manag.sgml
index 07a16247d76..9cf65ec749c 100644
--- a/doc/src/sgml/user-manag.sgml
+++ b/doc/src/sgml/user-manag.sgml
@@ -390,41 +390,41 @@ CREATE ROLE <replaceable>name</replaceable>;
<link linkend="sql-revoke"><command>REVOKE</command></link> commands:
<synopsis>
GRANT <replaceable>group_role</replaceable> TO <replaceable>role1</replaceable>, ... ;
REVOKE <replaceable>group_role</replaceable> FROM <replaceable>role1</replaceable>, ... ;
</synopsis>
You can grant membership to other group roles, too (since there isn't
really any distinction between group roles and non-group roles). The
database will not let you set up circular membership loops. Also,
it is not permitted to grant membership in a role to
<literal>PUBLIC</literal>.
</para>
<para>
The members of a group role can use the privileges of the role in two
ways. First, member roles that have been granted membership with the
<literal>SET</literal> option can do
<link linkend="sql-set-role"><command>SET ROLE</command></link> to
temporarily <quote>become</quote> 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
<literal>INHERIT</literal> option automatically have use of the
privileges of those directly or indirectly a member of, though the
chain stops at memberships lacking the inherit option. As an example,
suppose we have done:
<programlisting>
CREATE ROLE joe LOGIN;
CREATE ROLE admin;
CREATE ROLE wheel;
CREATE ROLE island;
GRANT admin TO joe WITH INHERIT TRUE;
GRANT wheel TO admin WITH INHERIT FALSE;
GRANT island TO joe WITH INHERIT TRUE, SET FALSE;
</programlisting>
Immediately after connecting as role <literal>joe</literal>, a database
session will have use of privileges granted directly to <literal>joe</literal>
plus any privileges granted to <literal>admin</literal> and
<literal>island</literal>, because <literal>joe</literal>
<quote>inherits</quote> those privileges. However, privileges
granted to <literal>wheel</literal> are not available, because even though
diff --git a/doc/src/sgml/wal.sgml b/doc/src/sgml/wal.sgml
index d5df65bc693..2eb282ab000 100644
--- a/doc/src/sgml/wal.sgml
+++ b/doc/src/sgml/wal.sgml
@@ -662,45 +662,45 @@
the second.
A restartpoint is triggered by schedule when a checkpoint record is reached
if at least <xref linkend="guc-checkpoint-timeout"/> seconds have passed since
the last performed restartpoint or when the previous attempt to perform
the restartpoint has failed. In the last case, the next restartpoint
will be scheduled in 15 seconds.
A restartpoint is triggered by request due to similar reasons like checkpoint
but mostly if WAL size is about to exceed <xref linkend="guc-max-wal-size"/>
However, because of limitations on when a restartpoint can be performed,
<varname>max_wal_size</varname> is often exceeded during recovery,
by up to one checkpoint cycle's worth of WAL.
(<varname>max_wal_size</varname> is never a hard limit anyway, so you should
always leave plenty of headroom to avoid running out of disk space.)
The <structfield>restartpoints_done</structfield> counter in the
<link linkend="monitoring-pg-stat-checkpointer-view"><structname>pg_stat_checkpointer</structname></link>
view counts the restartpoints that have really been performed.
</para>
<para>
In some cases, when the WAL size on the primary increases quickly,
- for instance during massive INSERT,
+ for instance during massive <command>INSERT</command>,
the <structfield>restartpoints_req</structfield> 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.
Only the <structfield>restartpoints_done</structfield>
counter among the restartpoint-related ones indicates that noticeable system
resources have been spent.
</para>
<para>
There are two commonly used internal <acronym>WAL</acronym> functions:
<function>XLogInsertRecord</function> and <function>XLogFlush</function>.
<function>XLogInsertRecord</function> is used to place a new record into
the <acronym>WAL</acronym> buffers in shared memory. If there is no
space for the new record, <function>XLogInsertRecord</function> will have
to write (move to kernel cache) a few filled <acronym>WAL</acronym>
buffers. This is undesirable because <function>XLogInsertRecord</function>
is used on every database low level modification (for example, row
insertion) at a time when an exclusive lock is held on affected
data pages, so the operation needs to be as fast as possible. What
is worse, writing <acronym>WAL</acronym> buffers might also force the
^ permalink raw reply [nested|flat] 23+ messages in thread
* Re: Documentation improvement patch
2024-09-05 09:33 Documentation improvement patch Oleg Sibiryakov <o.sibiryakov@postgrespro.ru>
2024-09-06 13:20 ` Re: Documentation improvement patch Daniel Gustafsson <daniel@yesql.se>
2024-09-10 11:46 ` Re: Documentation improvement patch Oleg Sibiryakov <o.sibiryakov@postgrespro.ru>
2024-09-10 13:02 ` Re: Documentation improvement patch Daniel Gustafsson <daniel@yesql.se>
2024-09-11 09:53 ` Re: Documentation improvement patch Peter Eisentraut <peter@eisentraut.org>
2024-09-13 10:50 ` Re: Documentation improvement patch Oleg Sibiryakov <o.sibiryakov@postgrespro.ru>
@ 2024-10-01 08:04 ` Oleg Sibiryakov <o.sibiryakov@postgrespro.ru>
2024-10-01 08:59 ` Re: Documentation improvement patch Daniel Gustafsson <daniel@yesql.se>
0 siblings, 1 reply; 23+ messages in thread
From: Oleg Sibiryakov @ 2024-10-01 08:04 UTC (permalink / raw)
To: pgsql-docs@lists.postgresql.org
Dear all,
Here is a kind reminder of a small documentation improvement patch,
which we started discussing a month ago.
I removed all the controversial points touched upon in this thread.
Please, take a look once again at your convenience.
The patch shall be applied to the master branch this time.
--
Regards,
Oleg Sibiryakov
Technical Writer
Postgres Professional, The Russian Postgres Company
https://postgrespro.ru
On 13.09.2024 13:50, Oleg Sibiryakov wrote:
> Here is a patch without the builtin/built-in corrections (find attached).
>
> But I still believe the issue should be discussed further.
> We actually have two options: it is either a spelling mistake (since
> built-in should written with a hyphen), or we miss the <literal> tag
> (since it is actually also a value).
>
> So I do think we cannot really leave it as is.
>
Attachments:
[text/x-patch] doc-improvements_v2.patch (61.2K, ../../f4c5d7da-55e4-4111-a457-c23d7f13c4c0@postgrespro.ru/2-doc-improvements_v2.patch)
download | inline diff:
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
@@ -8024,41 +8024,41 @@ SCRAM-SHA-256$<replaceable><iteration count></replaceable>:<replaceable>&l
for authentication
</para></entry>
</row>
<row>
<entry role="catalog_table_entry"><para role="column_definition">
<structfield>subrunasowner</structfield> <type>bool</type>
</para>
<para>
If true, the subscription will be run with the permissions
of the subscription owner
</para></entry>
</row>
<row>
<entry role="catalog_table_entry"><para role="column_definition">
<structfield>subfailover</structfield> <type>bool</type>
</para>
<para>
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
</para></entry>
</row>
<row>
<entry role="catalog_table_entry"><para role="column_definition">
<structfield>subconninfo</structfield> <type>text</type>
</para>
<para>
Connection string to the upstream database
</para></entry>
</row>
<row>
<entry role="catalog_table_entry"><para role="column_definition">
<structfield>subslotname</structfield> <type>name</type>
</para>
<para>
Name of the replication slot in the upstream database (also used
for the local replication origin name);
diff --git a/doc/src/sgml/charset.sgml b/doc/src/sgml/charset.sgml
index 834cb30c85a..a76e9579a14 100644
--- a/doc/src/sgml/charset.sgml
+++ b/doc/src/sgml/charset.sgml
@@ -365,59 +365,59 @@ initdb --locale-provider=icu --icu-locale=en
Regardless of the locale provider, the operating system is still used to
provide some locale-aware behavior, such as messages (see <xref
linkend="guc-lc-messages"/>).
</para>
<para>
The available locale providers are listed below:
</para>
<variablelist>
<varlistentry>
<term><literal>builtin</literal></term>
<listitem>
<para>
The <literal>builtin</literal> provider uses built-in operations. Only
the <literal>C</literal> and <literal>C.UTF-8</literal> locales are
supported for this provider.
</para>
<para>
The <literal>C</literal> locale behavior is identical to the
- <literal>C</literal> locale in the libc provider. When using this
- locale, the behavior may depend on the database encoding.
+ <literal>C</literal> locale in the <literal>libc</literal> provider. When
+ using this locale, the behavior may depend on the database encoding.
</para>
<para>
The <literal>C.UTF-8</literal> locale is available only for when the
database encoding is <literal>UTF-8</literal>, and the behavior is
based on Unicode. The collation uses the code point values only. The
regular expression character classes are based on the "POSIX
Compatible" semantics, and the case mapping is the "simple" variant.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>icu</literal></term>
<listitem>
<para>
The <literal>icu</literal> provider uses the external
- ICU<indexterm><primary>ICU</primary></indexterm>
+ <indexterm><primary>ICU</primary></indexterm>
library. <productname>PostgreSQL</productname> must have been
configured with support.
</para>
<para>
ICU provides collation and character classification behavior that is
independent of the operating system and database encoding, which is
preferable if you expect to transition to other platforms without any
change in results. <literal>LC_COLLATE</literal> and
<literal>LC_CTYPE</literal> can be set independently of the ICU
locale.
</para>
<note>
<para>
For the ICU provider, results may depend on the version of the ICU
library used, as it is updated to reflect changes in natural language
over time.
</para>
</note>
</listitem>
</varlistentry>
@@ -845,76 +845,77 @@ SELECT * FROM test1 ORDER BY a || b COLLATE "fr_FR";
separate <quote>collate</quote> and <quote>ctype</quote> settings, so
they are always the same. Also, ICU collations are independent of the
encoding, so there is always only one ICU collation of a given name in
a database.
</para>
<sect3 id="collation-managing-standard">
<title>Standard Collations</title>
<para>
On all platforms, the following collations are supported:
<variablelist>
<varlistentry>
<term><literal>unicode</literal></term>
<listitem>
<para>
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
- different version of ICU. (This collation has the same behavior as
+ collation, and behavior may change if
+ <productname>PostgreSQL</productname> is built with a different version
+ of ICU. (This collation has the same behavior as
the ICU root locale; see <xref
linkend="collation-managing-predefined-icu-und-x-icu"/>.)
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>ucs_basic</literal></term>
<listitem>
<para>
This SQL standard collation sorts using the Unicode code point values
rather than natural language order, and only the ASCII letters
<quote><literal>A</literal></quote> through
<quote><literal>Z</literal></quote> are treated as letters. The
behavior is efficient and stable across all versions. Only available
for encoding <literal>UTF8</literal>. (This collation has the same
behavior as the libc locale specification <literal>C</literal> in
<literal>UTF8</literal> encoding.)
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>pg_c_utf8</literal></term>
<listitem>
<para>
This collation sorts by Unicode code point values rather than natural
language order. For the functions <function>lower</function>,
<function>initcap</function>, and <function>upper</function>, it uses
Unicode simple case mapping. For pattern matching (including regular
expressions), it uses the POSIX Compatible variant of Unicode <ulink
url="https://www.unicode.org/reports/tr18/#Compatibility_Properties">Compatibility
Properties</ulink>. Behavior is efficient and stable within a
- <productname>Postgres</productname> major version. This collation is
+ <productname>PostgreSQL</productname> major version. This collation is
only available for encoding <literal>UTF8</literal>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>C</literal> (equivalent to <literal>POSIX</literal>)</term>
<listitem>
<para>
The <literal>C</literal> and <literal>POSIX</literal> collations are
based on <quote>traditional C</quote> behavior. They sort by byte
values rather than natural language order, and only the ASCII letters
<quote><literal>A</literal></quote> through
<quote><literal>Z</literal></quote> are treated as letters. The
behavior is efficient and stable across all versions for a given
database encoding, but behavior may vary between different database
encodings.
</para>
</listitem>
</varlistentry>
diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml
index 08173ecb5c4..247cf506651 100644
--- a/doc/src/sgml/config.sgml
+++ b/doc/src/sgml/config.sgml
@@ -691,43 +691,44 @@ include_dir 'conf.d'
</para>
</listitem>
</varlistentry>
<varlistentry id="guc-max-connections" xreflabel="max_connections">
<term><varname>max_connections</varname> (<type>integer</type>)
<indexterm>
<primary><varname>max_connections</varname> configuration parameter</primary>
</indexterm>
</term>
<listitem>
<para>
Determines the maximum number of concurrent connections to the
database server. The default is typically 100 connections, but
might be less if your kernel settings will not support it (as
determined during <application>initdb</application>). This parameter can
only be set at server start.
</para>
<para>
- PostgreSQL sizes certain resources based directly on the value of
- <varname>max_connections</varname>. Increasing its value leads to
- higher allocation of those resources, including shared memory.
+ <productname>PostgreSQL</productname> sizes certain resources based
+ directly on the value of <varname>max_connections</varname>. Increasing
+ its value leads to higher allocation of those resources, including
+ shared memory.
</para>
<para>
When running a standby server, you must set this parameter to the
same or higher value than on the primary server. Otherwise, queries
will not be allowed in the standby server.
</para>
</listitem>
</varlistentry>
<varlistentry id="guc-reserved-connections" xreflabel="reserved_connections">
<term><varname>reserved_connections</varname> (<type>integer</type>)
<indexterm>
<primary><varname>reserved_connections</varname> configuration parameter</primary>
</indexterm>
</term>
<listitem>
<para>
Determines the number of connection <quote>slots</quote> that are
reserved for connections by roles with privileges of the
@@ -10821,41 +10822,41 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir'
<literal>off</literal>, an error is returned if the <command>ALTER
SYSTEM</command> command is executed. This parameter can only be set in
the <filename>postgresql.conf</filename> file or on the server command
line. The default value is <literal>on</literal>.
</para>
<para>
Note that this setting must not be regarded as a security feature. It
only disables the <literal>ALTER SYSTEM</literal> command. It does not
prevent a superuser from changing the configuration using other SQL
commands. A superuser has many ways of executing shell commands at
the operating system level, and can therefore modify
<literal>postgresql.auto.conf</literal> regardless of the value of
this setting.
</para>
<para>
Turning this setting off is intended for environments where the
configuration of <productname>PostgreSQL</productname> is managed by
some external tool.
- In such environments, a well intentioned superuser might
+ In such environments, a well-intentioned superuser might
<emphasis>mistakenly</emphasis> use <command>ALTER SYSTEM</command>
to change the configuration instead of using the external tool.
This might result in unintended behavior, such as the external tool
overwriting the change at some later point in time when it updates the
configuration.
Setting this parameter to <literal>off</literal> can
help avoid such mistakes.
</para>
<para>
This parameter only controls the use of <command>ALTER SYSTEM</command>.
The settings stored in <filename>postgresql.auto.conf</filename>
take effect even if <literal>allow_alter_system</literal> is set to
<literal>off</literal>.
</para>
</listitem>
</varlistentry>
</variablelist>
</sect2>
diff --git a/doc/src/sgml/ddl.sgml b/doc/src/sgml/ddl.sgml
index 8ab0ddb112f..d46c8423f5b 100644
--- a/doc/src/sgml/ddl.sgml
+++ b/doc/src/sgml/ddl.sgml
@@ -296,41 +296,41 @@ INSERT INTO people (id, name, address) VALUE (<emphasis>DEFAULT</emphasis>, 'C',
value.
</para>
<para>
The clauses <literal>ALWAYS</literal> and <literal>BY DEFAULT</literal> in
the column definition determine how explicitly user-specified values are
handled in <command>INSERT</command> and <command>UPDATE</command>
commands. In an <command>INSERT</command> command, if
<literal>ALWAYS</literal> is selected, a user-specified value is only
accepted if the <command>INSERT</command> statement specifies
<literal>OVERRIDING SYSTEM VALUE</literal>. If <literal>BY
DEFAULT</literal> is selected, then the user-specified value takes
precedence. Thus, using <literal>BY DEFAULT</literal> results in a
behavior more similar to default values, where the default value can be
overridden by an explicit value, whereas <literal>ALWAYS</literal> provides
some more protection against accidentally inserting an explicit value.
</para>
<para>
The data type of an identity column must be one of the data types supported
- by sequences. (See <xref linkend="sql-createsequence"/>.) The properties
+ by sequences (see <xref linkend="sql-createsequence"/>). The properties
of the associated sequence may be specified when creating an identity
column (see <xref linkend="sql-createtable"/>) or changed afterwards (see
<xref linkend="sql-altertable"/>).
</para>
<para>
An identity column is automatically marked as <literal>NOT NULL</literal>.
An identity column, however, does not guarantee uniqueness. (A sequence
normally returns unique values, but a sequence could be reset, or values
could be inserted manually into the identity column, as discussed above.)
Uniqueness would need to be enforced using a <literal>PRIMARY KEY</literal>
or <literal>UNIQUE</literal> constraint.
</para>
<para>
In table inheritance hierarchies, identity columns and their properties in
a child table are independent of those in its parent tables. A child table
does not inherit identity columns or their properties automatically from
the parent. During <command>INSERT</command> or <command>UPDATE</command>,
a column is treated as an identity column if that column is an identity
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
@@ -21420,41 +21420,41 @@ SELECT NULLIF(value, '(none)') ...
</para>
<para>
Description
</para>
<para>
Example(s)
</para></entry>
</row>
</thead>
<tbody>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>lower</primary>
</indexterm>
<function>lower</function> ( <type>anymultirange</type> )
<returnvalue>anyelement</returnvalue>
</para>
<para>
Extracts the lower bound of the multirange (<literal>NULL</literal> if the
- multirange is empty has no lower bound).
+ multirange is empty or has no lower bound).
</para>
<para>
<literal>lower('{[1.1,2.2)}'::nummultirange)</literal>
<returnvalue>1.1</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>upper</primary>
</indexterm>
<function>upper</function> ( <type>anymultirange</type> )
<returnvalue>anyelement</returnvalue>
</para>
<para>
Extracts the upper bound of the multirange (<literal>NULL</literal> if the
multirange is empty or has no upper bound).
</para>
<para>
diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml
index 4a727d44997..ca19eaa6839 100644
--- a/doc/src/sgml/libpq.sgml
+++ b/doc/src/sgml/libpq.sgml
@@ -528,43 +528,43 @@ int PQsocketPoll(int sock, int forRead, int forWrite,
pg_usec_time_t end_time);
</synopsis>
</para>
<para>
This function performs polling of a file descriptor, optionally with
a timeout.
If <parameter>forRead</parameter> is nonzero, the
function will terminate when the socket is ready for
reading. If <parameter>forWrite</parameter> is nonzero,
the function will terminate when the
socket is ready for writing.
</para>
<para>
The timeout is specified by <parameter>end_time</parameter>, which
is the time to stop waiting expressed as a number of microseconds since
the Unix epoch (that is, <type>time_t</type> times 1 million).
Timeout is infinite if <parameter>end_time</parameter>
is <literal>-1</literal>. Timeout is immediate (no blocking) if
- end_time is <literal>0</literal> (or indeed, any time before now).
- Timeout values can be calculated conveniently by adding the desired
- number of microseconds to the result of
+ <parameter>end_time</parameter> is <literal>0</literal> (or indeed, any
+ time before now). Timeout values can be calculated conveniently by adding
+ the desired number of microseconds to the result of
<xref linkend="libpq-PQgetCurrentTimeUSec"/>.
Note that the underlying system calls may have less than microsecond
precision, so that the actual delay may be imprecise.
</para>
<para>
The function returns a value greater than <literal>0</literal> if the
specified condition is met, <literal>0</literal> if a timeout occurred,
or <literal>-1</literal> if an error occurred. The error can be
retrieved by checking the <literal>errno(3)</literal> value. In the
event both <parameter>forRead</parameter>
and <parameter>forWrite</parameter> are zero, the function immediately
returns a timeout indication.
</para>
<para>
<function>PQsocketPoll</function> is implemented using either
<function>poll(2)</function> or <function>select(2)</function>,
depending on platform. See <literal>POLLIN</literal>
and <literal>POLLOUT</literal> from <function>poll(2)</function>,
@@ -1814,42 +1814,43 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname
option was introduced in <productname>PostgreSQL</productname> version
17.
</para>
<variablelist>
<varlistentry>
<term><literal>postgres</literal></term>
<listitem>
<para>
perform <productname>PostgreSQL</productname> protocol
negotiation. This is the default if the option is not provided.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>direct</literal></term>
<listitem>
<para>
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
+ connection. This is only allowed with
+ <literal>sslmode=require</literal> or higher, because the weaker
+ settings could lead to unintended fallback to
plaintext authentication when the server does not support direct
SSL handshake.
</para>
</listitem>
</varlistentry>
</variablelist>
</listitem>
</varlistentry>
<varlistentry id="libpq-connect-sslcompression" xreflabel="sslcompression">
<term><literal>sslcompression</literal></term>
<listitem>
<para>
If set to 1, data sent over SSL connections will be compressed. If
set to 0, compression will be disabled. The default is 0. This
parameter is ignored if a connection without SSL is made.
</para>
<para>
SSL compression is nowadays considered insecure and its use is no
@@ -9564,41 +9565,41 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*)
<para>
Certificate Revocation List (CRL) entries are also checked
if the file <filename>~/.postgresql/root.crl</filename> exists
(<filename>%APPDATA%\postgresql\root.crl</filename> on Microsoft
Windows).
</para>
<para>
The location of the root certificate file and the CRL can be changed by
setting
the connection parameters <literal>sslrootcert</literal> and <literal>sslcrl</literal>
or the environment variables <envar>PGSSLROOTCERT</envar> and <envar>PGSSLCRL</envar>.
<literal>sslcrldir</literal> or the environment variable <envar>PGSSLCRLDIR</envar>
can also be used to specify a directory containing CRL files.
</para>
<note>
<para>
For backwards compatibility with earlier versions of PostgreSQL, if a
root CA file exists, the behavior of
- <literal>sslmode</literal>=<literal>require</literal> will be the same
+ <literal>sslmode=require</literal> will be the same
as that of <literal>verify-ca</literal>, meaning the server certificate
is validated against the CA. Relying on this behavior is discouraged,
and applications that need certificate validation should always use
<literal>verify-ca</literal> or <literal>verify-full</literal>.
</para>
</note>
</sect2>
<sect2 id="libpq-ssl-clientcert">
<title>Client Certificates</title>
<para>
If the server attempts to verify the identity of the
client by requesting the client's leaf certificate,
<application>libpq</application> will send the certificate(s) stored in
file <filename>~/.postgresql/postgresql.crt</filename> in the user's home
directory. The certificates must chain to the root certificate trusted
by the server. A matching
private key file <filename>~/.postgresql/postgresql.key</filename> must also
be present.
diff --git a/doc/src/sgml/protocol.sgml b/doc/src/sgml/protocol.sgml
index 2d2481bb8b8..a63c8988ee5 100644
--- a/doc/src/sgml/protocol.sgml
+++ b/doc/src/sgml/protocol.sgml
@@ -3248,41 +3248,41 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
and above, and it allows streaming of large in-progress transactions.
</para>
<para>
Version <literal>3</literal> is supported only for server version 15
and above, and it allows streaming of two-phase commits.
</para>
<para>
Version <literal>4</literal> is supported only for server version 16
and above, and it allows streams of large in-progress transactions to
be applied in parallel.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
publication_names
</term>
<listitem>
<para>
- 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.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
binary
</term>
<listitem>
<para>
Boolean option to use binary transfer mode. Binary mode is faster
than the text mode but slightly less robust.
</para>
</listitem>
</varlistentry>
<varlistentry>
@@ -3313,45 +3313,45 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
</varlistentry>
<varlistentry>
<term>
two_phase
</term>
<listitem>
<para>
Boolean option to enable two-phase transactions. Minimum protocol
version 3 is required to turn it on.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
origin
</term>
<listitem>
<para>
- 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.
+ Option to send changes by their origin. Possible values are
+ <literal>none</literal> to only send the changes that have no origin
+ associated, or <literal>any</literal> to send the changes regardless of
+ their origin. This can be used to avoid loops (infinite replication of
+ the same data) among replication nodes.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</sect2>
<sect2 id="protocol-logical-messages">
<title>Logical Replication Protocol Messages</title>
<para>
The individual protocol messages are discussed in the following
subsections. Individual messages are described in
<xref linkend="protocol-logicalrep-message-formats"/>.
</para>
<para>
All top-level protocol messages begin with a message type byte.
While represented in code as a character, this is a signed byte with no
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
@@ -1106,42 +1106,42 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
table and <literal>ACCESS EXCLUSIVE</literal> on the partition,
and the detach process completes. A <literal>CHECK</literal> constraint
that duplicates the partition constraint is added to the partition.
<literal>CONCURRENTLY</literal> cannot be run in a transaction block and
is not allowed if the partitioned table contains a default partition.
</para>
<para>
If <literal>FINALIZE</literal> is specified, a previous
<literal>DETACH CONCURRENTLY</literal> invocation that was canceled or
interrupted is completed.
At most one partition in a partitioned table can be pending detach at
a time.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>
- All the forms of ALTER TABLE that act on a single table, except
- <literal>RENAME</literal>, <literal>SET SCHEMA</literal>,
+ All the forms of <command>ALTER TABLE</command> that act on a single table,
+ except <literal>RENAME</literal>, <literal>SET SCHEMA</literal>,
<literal>ATTACH PARTITION</literal>, and
<literal>DETACH PARTITION</literal> can be combined into
a list of multiple alterations to be applied together. For example, it
is possible to add several columns and/or alter the type of several
columns in a single command. This is particularly useful with large
tables, since only one pass over the table need be made.
</para>
<para>
You must own the table to use <command>ALTER TABLE</command>.
To change the schema or tablespace of a table, you must also have
<literal>CREATE</literal> privilege on the new schema or tablespace.
To add the table as a new child of a parent table, you must own the parent
table as well. Also, to attach a table as a new partition of the table,
you must own the table being attached.
To alter the owner, you must be able to <literal>SET ROLE</literal> to the
new owning role, and that role must have <literal>CREATE</literal>
privilege on the table's schema.
(These restrictions enforce that altering the owner
doesn't do anything you couldn't do by dropping and recreating the table.
diff --git a/doc/src/sgml/ref/copy.sgml b/doc/src/sgml/ref/copy.sgml
index fdbd20bc50b..c208b7c9e3a 100644
--- a/doc/src/sgml/ref/copy.sgml
+++ b/doc/src/sgml/ref/copy.sgml
@@ -410,41 +410,41 @@ COPY { <replaceable class="parameter">table_name</replaceable> [ ( <replaceable
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>ENCODING</literal></term>
<listitem>
<para>
Specifies that the file is encoded in the <replaceable
class="parameter">encoding_name</replaceable>. If this option is
omitted, the current client encoding is used. See the Notes below
for more details.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>LOG_VERBOSITY</literal></term>
<listitem>
<para>
- Specify the amount of messages emitted by a <command>COPY</command>
+ Specifies the amount of messages emitted by a <command>COPY</command>
command: <literal>default</literal> or <literal>verbose</literal>. If
<literal>verbose</literal> is specified, additional messages are emitted
during processing.
</para>
<para>
This is currently used in <command>COPY FROM</command> command when
<literal>ON_ERROR</literal> option is set to <literal>ignore</literal>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>WHERE</literal></term>
<listitem>
<para>
The optional <literal>WHERE</literal> clause has the general form
<synopsis>
WHERE <replaceable class="parameter">condition</replaceable>
</synopsis>
where <replaceable class="parameter">condition</replaceable> is
diff --git a/doc/src/sgml/ref/create_subscription.sgml b/doc/src/sgml/ref/create_subscription.sgml
index 740b7d94210..674ed23a02a 100644
--- a/doc/src/sgml/ref/create_subscription.sgml
+++ b/doc/src/sgml/ref/create_subscription.sgml
@@ -112,42 +112,42 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
<varlistentry id="sql-createsubscription-params-with-connect">
<term><literal>connect</literal> (<type>boolean</type>)</term>
<listitem>
<para>
Specifies whether the <command>CREATE SUBSCRIPTION</command>
command should connect to the publisher at all. The default
is <literal>true</literal>. Setting this to
<literal>false</literal> will force the values of
<literal>create_slot</literal>, <literal>enabled</literal> and
<literal>copy_data</literal> to <literal>false</literal>.
(You cannot combine setting <literal>connect</literal>
to <literal>false</literal> with
setting <literal>create_slot</literal>, <literal>enabled</literal>,
or <literal>copy_data</literal> to <literal>true</literal>.)
</para>
<para>
Since no connection is made when this option is
<literal>false</literal>, no tables are subscribed. To initiate
replication, you must manually create the replication slot, enable
- the failover if required, enable the subscription, and refresh the
- subscription. See
+ the <literal>failover</literal> if required, enable the subscription,
+ and refresh the subscription. See
<xref linkend="logical-replication-subscription-examples-deferred-slot"/>
for examples.
</para>
</listitem>
</varlistentry>
<varlistentry id="sql-createsubscription-params-with-create-slot">
<term><literal>create_slot</literal> (<type>boolean</type>)</term>
<listitem>
<para>
Specifies whether the command should create the replication slot on
the publisher. The default is <literal>true</literal>.
</para>
<para>
If set to <literal>false</literal>, you are responsible for
creating the publisher's slot in some other way. See
<xref linkend="logical-replication-subscription-examples-deferred-slot"/>
for examples.
</para>
</listitem>
@@ -168,41 +168,41 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
<term><literal>slot_name</literal> (<type>string</type>)</term>
<listitem>
<para>
Name of the publisher's replication slot to use. The default is
to use the name of the subscription for the slot name.
</para>
<para>
Setting <literal>slot_name</literal> to <literal>NONE</literal>
means there will be no replication slot associated with the
subscription. Such subscriptions must also have both
<literal>enabled</literal> and <literal>create_slot</literal> set to
<literal>false</literal>. Use this when you will be creating the
replication slot later manually. See
<xref linkend="logical-replication-subscription-examples-deferred-slot"/>
for examples.
</para>
<para>
When setting <literal>slot_name</literal> to a valid name and
- <literal>create_slot</literal> to false, the
+ <literal>create_slot</literal> to <literal>false</literal>, the
<literal>failover</literal> property value of the named slot may
differ from the counterpart <literal>failover</literal> parameter
specified in the subscription. Always ensure the slot property
<literal>failover</literal> matches the counterpart parameter of the
subscription and vice versa. Otherwise, the slot on the publisher may
behave differently from what these subscription options say: for
example, the slot on the publisher could either be synced to the
standbys even when the subscription's <literal>failover</literal>
option is disabled or could be disabled for sync even when the
subscription's <literal>failover</literal> option is enabled.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>
The following parameters control the subscription's replication
behavior after it has been created:
@@ -457,47 +457,47 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
</para>
<para>
Creating a subscription that connects to the same database cluster (for
example, to replicate between databases in the same cluster or to replicate
within the same database) will only succeed if the replication slot is not
created as part of the same command. Otherwise, the <command>CREATE
SUBSCRIPTION</command> call will hang. To make this work, create the
replication slot separately (using the
function <function>pg_create_logical_replication_slot</function> with the
plugin name <literal>pgoutput</literal>) and create the subscription using
the parameter <literal>create_slot = false</literal>. See
<xref linkend="logical-replication-subscription-examples-deferred-slot"/>
for examples. This is an implementation restriction that might be lifted in a
future release.
</para>
<para>
If any table in the publication has a <literal>WHERE</literal> clause, rows
for which the <replaceable class="parameter">expression</replaceable>
- 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 <literal>WHERE</literal> clauses, a row will be published if any
- of the expressions (referring to that publish operation) are satisfied. In
- the case of different <literal>WHERE</literal> clauses, if one of the
- publications has no <literal>WHERE</literal> clause (referring to that
- publish operation) or the publication is declared as
+ evaluates to <literal>false</literal> or <literal>NULL</literal> will not be
+ published. If the subscription has several publications in which the same
+ table has been published wit different <literal>WHERE</literal> clauses, a
+ row will be published if an of the expressions (referring to that publish
+ operation) are satisfied. I the case of different <literal>WHERE</literal>
+ clauses, if one of the publications has no <literal>WHERE</literal> clause
+ (referring to that publish operation) or the publication is declared as
<link linkend="sql-createpublication-params-for-all-tables"><literal>FOR ALL TABLES</literal></link>
or <link linkend="sql-createpublication-params-for-tables-in-schema"><literal>FOR TABLES IN SCHEMA</literal></link>,
rows are always published regardless of the definition of the other
expressions. If the subscriber is a <productname>PostgreSQL</productname>
version before 15, then any row filtering is ignored during the initial data
synchronization phase. For this case, the user might want to consider
deleting any initially copied data that would be incompatible with
subsequent filtering. Because initial data synchronization does not take
into account the publication
<link linkend="sql-createpublication-params-with-publish"><literal>publish</literal></link>
parameter when copying existing table data, some rows may be copied that
would not be replicated using DML. See
<xref linkend="logical-replication-subscription-examples"/> for examples.
</para>
<para>
Subscriptions having several publications in which the same table has been
published with different column lists are not supported.
</para>
diff --git a/doc/src/sgml/ref/create_table.sgml b/doc/src/sgml/ref/create_table.sgml
index c1855b8d827..3403c4ab94e 100644
--- a/doc/src/sgml/ref/create_table.sgml
+++ b/doc/src/sgml/ref/create_table.sgml
@@ -2380,41 +2380,41 @@ CREATE TABLE cities_partdef
</refsect2>
<refsect2>
<title>Constraint Naming</title>
<para>
The SQL standard says that table and domain constraints must have names
that are unique across the schema containing the table or domain.
<productname>PostgreSQL</productname> is laxer: it only requires
constraint names to be unique across the constraints attached to a
particular table or domain. However, this extra freedom does not exist
for index-based constraints (<literal>UNIQUE</literal>,
<literal>PRIMARY KEY</literal>, and <literal>EXCLUDE</literal>
constraints), because the associated index is named the same as the
constraint, and index names must be unique across all relations within
the same schema.
</para>
<para>
Currently, <productname>PostgreSQL</productname> does not record names
- for not-null constraints at all, so they are not
+ for <literal>NOT NULL</literal> constraints at all, so they are not
subject to the uniqueness restriction. This might change in a future
release.
</para>
</refsect2>
<refsect2>
<title>Inheritance</title>
<para>
Multiple inheritance via the <literal>INHERITS</literal> clause is
a <productname>PostgreSQL</productname> language extension.
SQL:1999 and later define single inheritance using a
different syntax and different semantics. SQL:1999-style
inheritance is not yet supported by
<productname>PostgreSQL</productname>.
</para>
</refsect2>
<refsect2>
<title>Zero-Column Tables</title>
diff --git a/doc/src/sgml/ref/merge.sgml b/doc/src/sgml/ref/merge.sgml
index 97b34b9fcaf..aa83a500b43 100644
--- a/doc/src/sgml/ref/merge.sgml
+++ b/doc/src/sgml/ref/merge.sgml
@@ -246,43 +246,44 @@ DELETE
<para>
<replaceable class="parameter">join_condition</replaceable> is
an expression resulting in a value of type
<type>boolean</type> (similar to a <literal>WHERE</literal>
clause) that specifies which rows in the
<replaceable class="parameter">data_source</replaceable>
match rows in the target table.
</para>
<warning>
<para>
Only columns from the target table
that attempt to match <replaceable class="parameter">data_source</replaceable>
rows should appear in <replaceable class="parameter">join_condition</replaceable>.
<replaceable class="parameter">join_condition</replaceable> subexpressions that
only reference the target table's
columns can affect which action is taken, often in surprising ways.
</para>
<para>
If both <literal>WHEN NOT MATCHED BY SOURCE</literal> and
<literal>WHEN NOT MATCHED [BY TARGET]</literal> clauses are specified,
- the <command>MERGE</command> command will perform a <literal>FULL</literal>
- join between <replaceable class="parameter">data_source</replaceable>
- and the target table. For this to work, at least one
+ the <command>MERGE</command> command will perform a
+ <literal>FULL JOIN</literal> between
+ <replaceable class="parameter">data_source</replaceable> and the target
+ table. For this to work, at least one
<replaceable class="parameter">join_condition</replaceable> subexpression
must use an operator that can support a hash join, or all of the
subexpressions must use operators that can support a merge join.
</para>
</warning>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="parameter">when_clause</replaceable></term>
<listitem>
<para>
At least one <literal>WHEN</literal> clause is required.
</para>
<para>
The <literal>WHEN</literal> clause may specify <literal>WHEN MATCHED</literal>,
<literal>WHEN NOT MATCHED BY SOURCE</literal>, or
<literal>WHEN NOT MATCHED [BY TARGET]</literal>.
Note that the <acronym>SQL</acronym> standard only defines
<literal>WHEN MATCHED</literal> and <literal>WHEN NOT MATCHED</literal>
diff --git a/doc/src/sgml/ref/pg_basebackup.sgml b/doc/src/sgml/ref/pg_basebackup.sgml
index 4f99340c1dd..079edefb741 100644
--- a/doc/src/sgml/ref/pg_basebackup.sgml
+++ b/doc/src/sgml/ref/pg_basebackup.sgml
@@ -228,43 +228,43 @@ PostgreSQL documentation
<term><option>-R</option></term>
<term><option>--write-recovery-conf</option></term>
<listitem>
<para>
Creates a
<link linkend="file-standby-signal"><filename>standby.signal</filename></link>
<indexterm><primary><filename>standby.signal</filename></primary><secondary>pg_basebackup --write-recovery-conf</secondary></indexterm>
file and appends
connection settings to the <filename>postgresql.auto.conf</filename>
file in the target directory (or within the base archive file when
using tar format). This eases setting up a standby server using the
results of the backup.
</para>
<para>
The <filename>postgresql.auto.conf</filename> file will record the connection
settings and, if specified, the replication slot
that <application>pg_basebackup</application> is using, so that
streaming replication and <link linkend="logicaldecoding-replication-slots-synchronization">
logical replication slot synchronization</link> will use the same
- settings later on. The dbname will be recorded only if the dbname was
- specified explicitly in the connection string or <link linkend="libpq-envars">
- environment variable</link>.
+ settings later on. <literal>dbname</literal> will be recorded only
+ if it was specified explicitly in the connection string or
+ <link linkend="libpq-envars">environment variable</link>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-t <replaceable class="parameter">target</replaceable></option></term>
<term><option>--target=<replaceable class="parameter">target</replaceable></option></term>
<listitem>
<para>
Instructs the server where to place the base backup. The default target
is <literal>client</literal>, which specifies that the backup should
be sent to the machine where <application>pg_basebackup</application>
is running. If the target is instead set to
<literal>server:/some/path</literal>, the backup will be stored on
the machine where the server is running in the
<literal>/some/path</literal> directory. Storing a backup on the
server requires superuser privileges or having privileges of the
<literal>pg_write_server_files</literal> role. If the target is set to
diff --git a/doc/src/sgml/ref/pgupgrade.sgml b/doc/src/sgml/ref/pgupgrade.sgml
index 41d5566a442..98b32e8ce3f 100644
--- a/doc/src/sgml/ref/pgupgrade.sgml
+++ b/doc/src/sgml/ref/pgupgrade.sgml
@@ -50,42 +50,43 @@ PostgreSQL documentation
change the layout of the system tables, but the internal data storage
format rarely changes. <application>pg_upgrade</application> uses this fact
to perform rapid upgrades by creating new system tables and simply
reusing the old user data files. If a future major release ever
changes the data storage format in a way that makes the old data
format unreadable, <application>pg_upgrade</application> will not be usable
for such upgrades. (The community will attempt to avoid such
situations.)
</para>
<para>
<application>pg_upgrade</application> does its best to
make sure the old and new clusters are binary-compatible, e.g., by
checking for compatible compile-time settings, including 32/64-bit
binaries. It is important that
any external modules are also binary compatible, though this cannot
be checked by <application>pg_upgrade</application>.
</para>
<para>
- pg_upgrade supports upgrades from 9.2.X and later to the current
- major release of <productname>PostgreSQL</productname>, including snapshot and beta releases.
+ <application>pg_upgrade</application> supports upgrades from 9.2.X and later
+ to the current major release of <productname>PostgreSQL</productname>,
+ including snapshot and beta releases.
</para>
</refsect1>
<refsect1>
<title>Options</title>
<para>
<application>pg_upgrade</application> accepts the following command-line arguments:
<variablelist>
<varlistentry>
<term><option>-b</option> <replaceable>bindir</replaceable></term>
<term><option>--old-bindir=</option><replaceable>bindir</replaceable></term>
<listitem><para>the old PostgreSQL executable directory;
environment variable <envar>PGBINOLD</envar></para></listitem>
</varlistentry>
<varlistentry>
<term><option>-B</option> <replaceable>bindir</replaceable></term>
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
@@ -70,41 +70,41 @@
versions).
</para>
<para>
The <command>sestatus</command> command allows you to check the status of
<productname>SELinux</productname>. A typical display is:
<screen>
$ sestatus
SELinux status: enabled
SELinuxfs mount: /selinux
Current mode: enforcing
Mode from config file: enforcing
Policy version: 24
Policy from config file: targeted
</screen>
If <productname>SELinux</productname> is disabled or not installed, you must set
that product up first before installing this module.
</para>
<para>
- To build this module specify <xref
+ To build this module, specify <xref
linkend="configure-option-with-sepgsql"/> (when using <link
linkend="install-make">make and autoconf</link> ) or <xref
linkend="configure-with-sepgsql-meson"/> (when using <link
linkend="install-meson">meson</link>).
Be sure that the <filename>libselinux-devel</filename> RPM is installed at
build time.
</para>
<para>
To use this module, you must include <literal>sepgsql</literal>
in the <xref linkend="guc-shared-preload-libraries"/> parameter in
<filename>postgresql.conf</filename>. The module will not function correctly
if loaded in any other manner. Once the module is loaded, you
should execute <filename>sepgsql.sql</filename> in each database.
This will install functions needed for security label management, and
assign initial security labels.
</para>
<para>
diff --git a/doc/src/sgml/syntax.sgml b/doc/src/sgml/syntax.sgml
index 4dfbbd08626..916189a7d68 100644
--- a/doc/src/sgml/syntax.sgml
+++ b/doc/src/sgml/syntax.sgml
@@ -2479,41 +2479,41 @@ SELECT getf1(ROW(1,2.5,'this is a test')::mytable);
-------
1
(1 row)
SELECT getf1(CAST(ROW(11,'this is a test',2.5) AS myrowtype));
getf1
-------
11
(1 row)
</programlisting>
</para>
<para>
Row constructors can be used to build composite values to be stored
in a composite-type table column, or to be passed to a function that
accepts a composite parameter. Also, it is possible to test rows
using the standard comparison operators as described in <xref
linkend="functions-comparison"/>, to compare one row against another
as described in <xref linkend="functions-comparisons"/>, and to
use them in connection with subqueries, as discussed in <xref
- linkend="functions-subquery"/>,
+ linkend="functions-subquery"/>.
</para>
</sect2>
<sect2 id="syntax-express-eval">
<title>Expression Evaluation Rules</title>
<indexterm>
<primary>expression</primary>
<secondary>order of evaluation</secondary>
</indexterm>
<para>
The order of evaluation of subexpressions is not defined. In
particular, the inputs of an operator or function are not necessarily
evaluated left-to-right or in any other fixed order.
</para>
<para>
Furthermore, if the result of an expression can be determined by
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
@@ -2569,41 +2569,41 @@ SELECT * FROM pg_locks pl LEFT JOIN pg_prepared_xacts ppx
The time since the slot has become inactive.
<literal>NULL</literal> if the slot is currently being used.
Note that for slots on the standby that are being synced from a
primary server (whose <structfield>synced</structfield> field is
<literal>true</literal>), the
<structfield>inactive_since</structfield> indicates the last
synchronization (see
<xref linkend="logicaldecoding-replication-slots-synchronization"/>)
time.
</para></entry>
</row>
<row>
<entry role="catalog_table_entry"><para role="column_definition">
<structfield>conflicting</structfield> <type>bool</type>
</para>
<para>
True if this logical slot conflicted with recovery (and so is now
invalidated). When this column is true, check
<structfield>invalidation_reason</structfield> column for the conflict
- reason. Always NULL for physical slots.
+ reason. Always <literal>NULL</literal> for physical slots.
</para></entry>
</row>
<row>
<entry role="catalog_table_entry"><para role="column_definition">
<structfield>invalidation_reason</structfield> <type>text</type>
</para>
<para>
The reason for the slot's invalidation. It is set for both logical and
physical slots. <literal>NULL</literal> if the slot is not invalidated.
Possible values are:
<itemizedlist spacing="compact">
<listitem>
<para>
<literal>wal_removed</literal> means that the required WAL has been
removed.
</para>
</listitem>
<listitem>
<para>
@@ -3928,41 +3928,41 @@ SELECT * FROM pg_locks pl LEFT JOIN pg_prepared_xacts ppx
<row>
<entry role="catalog_table_entry"><para role="column_definition">
<structfield>elem_count_histogram</structfield> <type>float4[]</type>
</para>
<para>
A histogram of the counts of distinct non-null element values within the
values of the column, followed by the average number of distinct
non-null elements. (Null for scalar types.)
</para></entry>
</row>
<row>
<entry role="catalog_table_entry"><para role="column_definition">
<structfield>range_length_histogram</structfield> <type>anyarray</type>
</para>
<para>
A histogram of the lengths of non-empty and non-null range values of a
range type column. (Null for non-range types.)
</para>
<para>
- This histogram is calculated using the <literal>subtype_diff</literal>
+ This histogram is calculated using the <function>subtype_diff</function>
range function regardless of whether range bounds are inclusive.
</para></entry>
</row>
<row>
<entry role="catalog_table_entry"><para role="column_definition">
<structfield>range_empty_frac</structfield> <type>float4</type>
</para>
<para>
Fraction of column entries whose values are empty ranges.
(Null for non-range types.)
</para></entry>
</row>
<row>
<entry role="catalog_table_entry"><para role="column_definition">
<structfield>range_bounds_histogram</structfield> <type>anyarray</type>
</para>
<para>
A histogram of lower and upper bounds of non-empty and non-null range
diff --git a/doc/src/sgml/trigger.sgml b/doc/src/sgml/trigger.sgml
index 49382d07fa8..64090d5ec0d 100644
--- a/doc/src/sgml/trigger.sgml
+++ b/doc/src/sgml/trigger.sgml
@@ -340,44 +340,44 @@
<literal>AFTER</literal>, the <literal>BEFORE</literal> case is more efficient, since
the information about
the operation doesn't have to be saved until end of statement.
</para>
<para>
If a trigger function executes SQL commands then these
commands might fire triggers again. This is known as cascading
triggers. There is no direct limitation on the number of cascade
levels. It is possible for cascades to cause a recursive invocation
of the same trigger; for example, an <command>INSERT</command>
trigger might execute a command that inserts an additional row
into the same table, causing the <command>INSERT</command> trigger
to be fired again. It is the trigger programmer's responsibility
to avoid infinite recursion in such scenarios.
</para>
<para>
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.
- 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
+ ordinary SQL <command>UPDATE</command> or <command>DELETE</command> 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
be to break referential integrity. It is the trigger programmer's
responsibility to avoid that.
</para>
<para>
<indexterm>
<primary>trigger</primary>
<secondary>arguments for trigger functions</secondary>
</indexterm>
When a trigger is being defined, arguments can be specified for
it. The purpose of including arguments in the
trigger definition is to allow different triggers with similar
requirements to call the same function. As an example, there
could be a generalized trigger function that takes as its
arguments two column names and puts the current user in one and
the current time stamp in the other. Properly written, this
trigger function would be independent of the specific table it is
triggering on. So the same function could be used for
<command>INSERT</command> events on any table with suitable
columns, to automatically track creation of records in a
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
@@ -390,41 +390,41 @@ CREATE ROLE <replaceable>name</replaceable>;
<link linkend="sql-revoke"><command>REVOKE</command></link> commands:
<synopsis>
GRANT <replaceable>group_role</replaceable> TO <replaceable>role1</replaceable>, ... ;
REVOKE <replaceable>group_role</replaceable> FROM <replaceable>role1</replaceable>, ... ;
</synopsis>
You can grant membership to other group roles, too (since there isn't
really any distinction between group roles and non-group roles). The
database will not let you set up circular membership loops. Also,
it is not permitted to grant membership in a role to
<literal>PUBLIC</literal>.
</para>
<para>
The members of a group role can use the privileges of the role in two
ways. First, member roles that have been granted membership with the
<literal>SET</literal> option can do
<link linkend="sql-set-role"><command>SET ROLE</command></link> to
temporarily <quote>become</quote> 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
<literal>INHERIT</literal> option automatically have use of the
privileges of those directly or indirectly a member of, though the
chain stops at memberships lacking the inherit option. As an example,
suppose we have done:
<programlisting>
CREATE ROLE joe LOGIN;
CREATE ROLE admin;
CREATE ROLE wheel;
CREATE ROLE island;
GRANT admin TO joe WITH INHERIT TRUE;
GRANT wheel TO admin WITH INHERIT FALSE;
GRANT island TO joe WITH INHERIT TRUE, SET FALSE;
</programlisting>
Immediately after connecting as role <literal>joe</literal>, a database
session will have use of privileges granted directly to <literal>joe</literal>
plus any privileges granted to <literal>admin</literal> and
<literal>island</literal>, because <literal>joe</literal>
<quote>inherits</quote> those privileges. However, privileges
granted to <literal>wheel</literal> are not available, because even though
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
@@ -662,45 +662,45 @@
the second.
A restartpoint is triggered by schedule when a checkpoint record is reached
if at least <xref linkend="guc-checkpoint-timeout"/> seconds have passed since
the last performed restartpoint or when the previous attempt to perform
the restartpoint has failed. In the last case, the next restartpoint
will be scheduled in 15 seconds.
A restartpoint is triggered by request due to similar reasons like checkpoint
but mostly if WAL size is about to exceed <xref linkend="guc-max-wal-size"/>
However, because of limitations on when a restartpoint can be performed,
<varname>max_wal_size</varname> is often exceeded during recovery,
by up to one checkpoint cycle's worth of WAL.
(<varname>max_wal_size</varname> is never a hard limit anyway, so you should
always leave plenty of headroom to avoid running out of disk space.)
The <structfield>restartpoints_done</structfield> counter in the
<link linkend="monitoring-pg-stat-checkpointer-view"><structname>pg_stat_checkpointer</structname></link>
view counts the restartpoints that have really been performed.
</para>
<para>
In some cases, when the WAL size on the primary increases quickly,
- for instance during massive INSERT,
+ for instance during massive <command>INSERT</command>,
the <structfield>restartpoints_req</structfield> 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.
Only the <structfield>restartpoints_done</structfield>
counter among the restartpoint-related ones indicates that noticeable system
resources have been spent.
</para>
<para>
There are two commonly used internal <acronym>WAL</acronym> functions:
<function>XLogInsertRecord</function> and <function>XLogFlush</function>.
<function>XLogInsertRecord</function> is used to place a new record into
the <acronym>WAL</acronym> buffers in shared memory. If there is no
space for the new record, <function>XLogInsertRecord</function> will have
to write (move to kernel cache) a few filled <acronym>WAL</acronym>
buffers. This is undesirable because <function>XLogInsertRecord</function>
is used on every database low level modification (for example, row
insertion) at a time when an exclusive lock is held on affected
data pages, so the operation needs to be as fast as possible. What
is worse, writing <acronym>WAL</acronym> buffers might also force the
^ permalink raw reply [nested|flat] 23+ messages in thread
* Re: Documentation improvement patch
2024-09-05 09:33 Documentation improvement patch Oleg Sibiryakov <o.sibiryakov@postgrespro.ru>
2024-09-06 13:20 ` Re: Documentation improvement patch Daniel Gustafsson <daniel@yesql.se>
2024-09-10 11:46 ` Re: Documentation improvement patch Oleg Sibiryakov <o.sibiryakov@postgrespro.ru>
2024-09-10 13:02 ` Re: Documentation improvement patch Daniel Gustafsson <daniel@yesql.se>
2024-09-11 09:53 ` Re: Documentation improvement patch Peter Eisentraut <peter@eisentraut.org>
2024-09-13 10:50 ` Re: Documentation improvement patch Oleg Sibiryakov <o.sibiryakov@postgrespro.ru>
2024-10-01 08:04 ` Re: Documentation improvement patch Oleg Sibiryakov <o.sibiryakov@postgrespro.ru>
@ 2024-10-01 08:59 ` Daniel Gustafsson <daniel@yesql.se>
2024-10-02 08:09 ` Re: Documentation improvement patch Oleg Sibiryakov <o.sibiryakov@postgrespro.ru>
0 siblings, 1 reply; 23+ messages in thread
From: Daniel Gustafsson @ 2024-10-01 08:59 UTC (permalink / raw)
To: Oleg Sibiryakov <o.sibiryakov@postgrespro.ru>; +Cc: pgsql-docs@lists.postgresql.org
> On 1 Oct 2024, at 10:04, Oleg Sibiryakov <o.sibiryakov@postgrespro.ru> wrote:
> Here is a kind reminder of a small documentation improvement patch, which we started discussing a month ago.
>
> I removed all the controversial points touched upon in this thread. Please, take a look once again at your convenience.
In general, when submitting a docs patch it's better to not reflow the
paragraphs when a modified line becomes too long. Reading a 4 line diff where
only one thing changed in the first becomes harder than reading a single line
diff where the line is long. The committer can ensure the lines are reflowed
prior to a commit, or it can be left as the final revision of a patch
submission once all changes are discussed-
A few comments on this version of the patch:
- ICU<indexterm><primary>ICU</primary></indexterm>
+ <indexterm><primary>ICU</primary></indexterm>
I don't think removing the name of the library changing the sentence from "The
icu provider uses the external ICU library" to "The icu provider uses the
external library" is an improvement.
- by sequences. (See <xref linkend="sql-createsequence"/>.) The properties
+ by sequences (see <xref linkend="sql-createsequence"/>). The properties
This is a common construction in our docs, if it's considered to be a bad
practice the case should be argued (separately) for removing all of them
instead.
- Comma separated list of publication names for which to subscribe
+ Comma-separated list of publication names for which to subscribe
There are two more cases of "comma separated" (config.sgml and copy.sgml),
should they be changed too?
- the failover if required, enable the subscription, and refresh the
- subscription. See
+ the <literal>failover</literal> if required, enable the subscription,
+ and refresh the subscription. See
This refers to the act of failing over, not the property value failover, and
should not be in <literal>.
- for not-null constraints at all, so they are not
+ for <literal>NOT NULL</literal> constraints at all, so they are not
I'm still not convinced that this change makes the documentation more readable.
- the <command>MERGE</command> command will perform a <literal>FULL</literal>
- join between <replaceable class="parameter">data_source</replaceable>
- and the target table. For this to work, at least one
+ the <command>MERGE</command> command will perform a
+ <literal>FULL JOIN</literal> between
+ <replaceable class="parameter">data_source</replaceable> and the target
+ table. For this to work, at least one
This paragraph discuss various join types, keeping it lowercase "join" matches
the remainder of the paragraph and makes it more readable IMHO. It's not
discussing syntax the user is expected to type so need to make it so.
--
Daniel Gustafsson
^ permalink raw reply [nested|flat] 23+ messages in thread
* Re: Documentation improvement patch
2024-09-05 09:33 Documentation improvement patch Oleg Sibiryakov <o.sibiryakov@postgrespro.ru>
2024-09-06 13:20 ` Re: Documentation improvement patch Daniel Gustafsson <daniel@yesql.se>
2024-09-10 11:46 ` Re: Documentation improvement patch Oleg Sibiryakov <o.sibiryakov@postgrespro.ru>
2024-09-10 13:02 ` Re: Documentation improvement patch Daniel Gustafsson <daniel@yesql.se>
2024-09-11 09:53 ` Re: Documentation improvement patch Peter Eisentraut <peter@eisentraut.org>
2024-09-13 10:50 ` Re: Documentation improvement patch Oleg Sibiryakov <o.sibiryakov@postgrespro.ru>
2024-10-01 08:04 ` Re: Documentation improvement patch Oleg Sibiryakov <o.sibiryakov@postgrespro.ru>
2024-10-01 08:59 ` Re: Documentation improvement patch Daniel Gustafsson <daniel@yesql.se>
@ 2024-10-02 08:09 ` Oleg Sibiryakov <o.sibiryakov@postgrespro.ru>
2024-10-02 12:58 ` Re: Documentation improvement patch Daniel Gustafsson <daniel@yesql.se>
0 siblings, 1 reply; 23+ messages in thread
From: Oleg Sibiryakov @ 2024-10-02 08:09 UTC (permalink / raw)
To: Daniel Gustafsson <daniel@yesql.se>; +Cc: pgsql-docs@lists.postgresql.org
Thank you for your kind feedback! I will take due note of the comments
in the next documentation patches as well.
I have made all the changes as per your feedback and also corrected
paragraph reflow.
The third version of the patch is attached for your consideration.
--
Oleg Sibiryakov
On 01.10.2024 11:59, Daniel Gustafsson wrote:
>> On 1 Oct 2024, at 10:04, Oleg Sibiryakov <o.sibiryakov@postgrespro.ru> wrote:
>> Here is a kind reminder of a small documentation improvement patch, which we started discussing a month ago.
>>
>> I removed all the controversial points touched upon in this thread. Please, take a look once again at your convenience.
> In general, when submitting a docs patch it's better to not reflow the
> paragraphs when a modified line becomes too long. Reading a 4 line diff where
> only one thing changed in the first becomes harder than reading a single line
> diff where the line is long. The committer can ensure the lines are reflowed
> prior to a commit, or it can be left as the final revision of a patch
> submission once all changes are discussed-
>
> A few comments on this version of the patch:
>
>
> - ICU<indexterm><primary>ICU</primary></indexterm>
> + <indexterm><primary>ICU</primary></indexterm>
>
> I don't think removing the name of the library changing the sentence from "The
> icu provider uses the external ICU library" to "The icu provider uses the
> external library" is an improvement.
>
>
> - by sequences. (See <xref linkend="sql-createsequence"/>.) The properties
> + by sequences (see <xref linkend="sql-createsequence"/>). The properties
>
> This is a common construction in our docs, if it's considered to be a bad
> practice the case should be argued (separately) for removing all of them
> instead.
>
>
> - Comma separated list of publication names for which to subscribe
> + Comma-separated list of publication names for which to subscribe
>
> There are two more cases of "comma separated" (config.sgml and copy.sgml),
> should they be changed too?
>
>
> - the failover if required, enable the subscription, and refresh the
> - subscription. See
> + the <literal>failover</literal> if required, enable the subscription,
> + and refresh the subscription. See
>
> This refers to the act of failing over, not the property value failover, and
> should not be in <literal>.
>
>
> - for not-null constraints at all, so they are not
> + for <literal>NOT NULL</literal> constraints at all, so they are not
>
> I'm still not convinced that this change makes the documentation more readable.
>
>
> - the <command>MERGE</command> command will perform a <literal>FULL</literal>
> - join between <replaceable class="parameter">data_source</replaceable>
> - and the target table. For this to work, at least one
> + the <command>MERGE</command> command will perform a
> + <literal>FULL JOIN</literal> between
> + <replaceable class="parameter">data_source</replaceable> and the target
> + table. For this to work, at least one
>
> This paragraph discuss various join types, keeping it lowercase "join" matches
> the remainder of the paragraph and makes it more readable IMHO. It's not
> discussing syntax the user is expected to type so need to make it so.
>
> --
> Daniel Gustafsson
>
Attachments:
[text/x-patch] doc-improvements_v3.patch (53.2K, ../../3f595f00-9fbe-4062-b450-34bcf5c11ce0@postgrespro.ru/2-doc-improvements_v3.patch)
download | inline diff:
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
@@ -8024,41 +8024,41 @@ SCRAM-SHA-256$<replaceable><iteration count></replaceable>:<replaceable>&l
for authentication
</para></entry>
</row>
<row>
<entry role="catalog_table_entry"><para role="column_definition">
<structfield>subrunasowner</structfield> <type>bool</type>
</para>
<para>
If true, the subscription will be run with the permissions
of the subscription owner
</para></entry>
</row>
<row>
<entry role="catalog_table_entry"><para role="column_definition">
<structfield>subfailover</structfield> <type>bool</type>
</para>
<para>
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
</para></entry>
</row>
<row>
<entry role="catalog_table_entry"><para role="column_definition">
<structfield>subconninfo</structfield> <type>text</type>
</para>
<para>
Connection string to the upstream database
</para></entry>
</row>
<row>
<entry role="catalog_table_entry"><para role="column_definition">
<structfield>subslotname</structfield> <type>name</type>
</para>
<para>
Name of the replication slot in the upstream database (also used
for the local replication origin name);
diff --git a/doc/src/sgml/charset.sgml b/doc/src/sgml/charset.sgml
index 834cb30c85a..dbbf7fc3726 100644
--- a/doc/src/sgml/charset.sgml
+++ b/doc/src/sgml/charset.sgml
@@ -365,41 +365,41 @@ initdb --locale-provider=icu --icu-locale=en
Regardless of the locale provider, the operating system is still used to
provide some locale-aware behavior, such as messages (see <xref
linkend="guc-lc-messages"/>).
</para>
<para>
The available locale providers are listed below:
</para>
<variablelist>
<varlistentry>
<term><literal>builtin</literal></term>
<listitem>
<para>
The <literal>builtin</literal> provider uses built-in operations. Only
the <literal>C</literal> and <literal>C.UTF-8</literal> locales are
supported for this provider.
</para>
<para>
The <literal>C</literal> locale behavior is identical to the
- <literal>C</literal> locale in the libc provider. When using this
+ <literal>C</literal> locale in the <literal>libc</literal> provider. When using this
locale, the behavior may depend on the database encoding.
</para>
<para>
The <literal>C.UTF-8</literal> locale is available only for when the
database encoding is <literal>UTF-8</literal>, and the behavior is
based on Unicode. The collation uses the code point values only. The
regular expression character classes are based on the "POSIX
Compatible" semantics, and the case mapping is the "simple" variant.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>icu</literal></term>
<listitem>
<para>
The <literal>icu</literal> provider uses the external
ICU<indexterm><primary>ICU</primary></indexterm>
library. <productname>PostgreSQL</productname> must have been
configured with support.
@@ -845,76 +845,76 @@ SELECT * FROM test1 ORDER BY a || b COLLATE "fr_FR";
separate <quote>collate</quote> and <quote>ctype</quote> settings, so
they are always the same. Also, ICU collations are independent of the
encoding, so there is always only one ICU collation of a given name in
a database.
</para>
<sect3 id="collation-managing-standard">
<title>Standard Collations</title>
<para>
On all platforms, the following collations are supported:
<variablelist>
<varlistentry>
<term><literal>unicode</literal></term>
<listitem>
<para>
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 <productname>PostgreSQL</productname> is built with a
different version of ICU. (This collation has the same behavior as
the ICU root locale; see <xref
linkend="collation-managing-predefined-icu-und-x-icu"/>.)
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>ucs_basic</literal></term>
<listitem>
<para>
This SQL standard collation sorts using the Unicode code point values
rather than natural language order, and only the ASCII letters
<quote><literal>A</literal></quote> through
<quote><literal>Z</literal></quote> are treated as letters. The
behavior is efficient and stable across all versions. Only available
for encoding <literal>UTF8</literal>. (This collation has the same
behavior as the libc locale specification <literal>C</literal> in
<literal>UTF8</literal> encoding.)
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>pg_c_utf8</literal></term>
<listitem>
<para>
This collation sorts by Unicode code point values rather than natural
language order. For the functions <function>lower</function>,
<function>initcap</function>, and <function>upper</function>, it uses
Unicode simple case mapping. For pattern matching (including regular
expressions), it uses the POSIX Compatible variant of Unicode <ulink
url="https://www.unicode.org/reports/tr18/#Compatibility_Properties">Compatibility
Properties</ulink>. Behavior is efficient and stable within a
- <productname>Postgres</productname> major version. This collation is
+ <productname>PostgreSQL</productname> major version. This collation is
only available for encoding <literal>UTF8</literal>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>C</literal> (equivalent to <literal>POSIX</literal>)</term>
<listitem>
<para>
The <literal>C</literal> and <literal>POSIX</literal> collations are
based on <quote>traditional C</quote> behavior. They sort by byte
values rather than natural language order, and only the ASCII letters
<quote><literal>A</literal></quote> through
<quote><literal>Z</literal></quote> are treated as letters. The
behavior is efficient and stable across all versions for a given
database encoding, but behavior may vary between different database
encodings.
</para>
</listitem>
</varlistentry>
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
@@ -691,41 +691,41 @@ include_dir 'conf.d'
</para>
</listitem>
</varlistentry>
<varlistentry id="guc-max-connections" xreflabel="max_connections">
<term><varname>max_connections</varname> (<type>integer</type>)
<indexterm>
<primary><varname>max_connections</varname> configuration parameter</primary>
</indexterm>
</term>
<listitem>
<para>
Determines the maximum number of concurrent connections to the
database server. The default is typically 100 connections, but
might be less if your kernel settings will not support it (as
determined during <application>initdb</application>). This parameter can
only be set at server start.
</para>
<para>
- PostgreSQL sizes certain resources based directly on the value of
+ <productname>PostgreSQL</productname> sizes certain resources based directly on the value of
<varname>max_connections</varname>. Increasing its value leads to
higher allocation of those resources, including shared memory.
</para>
<para>
When running a standby server, you must set this parameter to the
same or higher value than on the primary server. Otherwise, queries
will not be allowed in the standby server.
</para>
</listitem>
</varlistentry>
<varlistentry id="guc-reserved-connections" xreflabel="reserved_connections">
<term><varname>reserved_connections</varname> (<type>integer</type>)
<indexterm>
<primary><varname>reserved_connections</varname> configuration parameter</primary>
</indexterm>
</term>
<listitem>
<para>
@@ -6405,41 +6405,41 @@ SELECT * FROM parent WHERE key = 2400;
<indexterm>
<primary><varname>log_destination</varname> configuration parameter</primary>
</indexterm>
</term>
<listitem>
<para>
<productname>PostgreSQL</productname> supports several methods
for logging server messages, including
<systemitem>stderr</systemitem>, <systemitem>csvlog</systemitem>,
<systemitem>jsonlog</systemitem>, and
<systemitem>syslog</systemitem>. On Windows,
<systemitem>eventlog</systemitem> is also supported. Set this
parameter to a list of desired log destinations separated by
commas. The default is to log to <systemitem>stderr</systemitem>
only.
This parameter can only be set in the <filename>postgresql.conf</filename>
file or on the server command line.
</para>
<para>
If <systemitem>csvlog</systemitem> is included in <varname>log_destination</varname>,
- log entries are output in <quote>comma separated
+ log entries are output in <quote>comma-separated
value</quote> (<acronym>CSV</acronym>) format, which is convenient for
loading logs into programs.
See <xref linkend="runtime-config-logging-csvlog"/> for details.
<xref linkend="guc-logging-collector"/> must be enabled to generate
CSV-format log output.
</para>
<para>
If <systemitem>jsonlog</systemitem> is included in
<varname>log_destination</varname>, log entries are output in
<acronym>JSON</acronym> format, which is convenient for loading logs
into programs.
See <xref linkend="runtime-config-logging-jsonlog"/> for details.
<xref linkend="guc-logging-collector"/> must be enabled to generate
JSON-format log output.
</para>
<para>
When either <systemitem>stderr</systemitem>,
<systemitem>csvlog</systemitem> or <systemitem>jsonlog</systemitem> are
included, the file <filename>current_logfiles</filename> is created to
record the location of the log file(s) currently in use by the logging
@@ -10821,41 +10821,41 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir'
<literal>off</literal>, an error is returned if the <command>ALTER
SYSTEM</command> command is executed. This parameter can only be set in
the <filename>postgresql.conf</filename> file or on the server command
line. The default value is <literal>on</literal>.
</para>
<para>
Note that this setting must not be regarded as a security feature. It
only disables the <literal>ALTER SYSTEM</literal> command. It does not
prevent a superuser from changing the configuration using other SQL
commands. A superuser has many ways of executing shell commands at
the operating system level, and can therefore modify
<literal>postgresql.auto.conf</literal> regardless of the value of
this setting.
</para>
<para>
Turning this setting off is intended for environments where the
configuration of <productname>PostgreSQL</productname> is managed by
some external tool.
- In such environments, a well intentioned superuser might
+ In such environments, a well-intentioned superuser might
<emphasis>mistakenly</emphasis> use <command>ALTER SYSTEM</command>
to change the configuration instead of using the external tool.
This might result in unintended behavior, such as the external tool
overwriting the change at some later point in time when it updates the
configuration.
Setting this parameter to <literal>off</literal> can
help avoid such mistakes.
</para>
<para>
This parameter only controls the use of <command>ALTER SYSTEM</command>.
The settings stored in <filename>postgresql.auto.conf</filename>
take effect even if <literal>allow_alter_system</literal> is set to
<literal>off</literal>.
</para>
</listitem>
</varlistentry>
</variablelist>
</sect2>
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
@@ -21420,41 +21420,41 @@ SELECT NULLIF(value, '(none)') ...
</para>
<para>
Description
</para>
<para>
Example(s)
</para></entry>
</row>
</thead>
<tbody>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>lower</primary>
</indexterm>
<function>lower</function> ( <type>anymultirange</type> )
<returnvalue>anyelement</returnvalue>
</para>
<para>
Extracts the lower bound of the multirange (<literal>NULL</literal> if the
- multirange is empty has no lower bound).
+ multirange is empty or has no lower bound).
</para>
<para>
<literal>lower('{[1.1,2.2)}'::nummultirange)</literal>
<returnvalue>1.1</returnvalue>
</para></entry>
</row>
<row>
<entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>upper</primary>
</indexterm>
<function>upper</function> ( <type>anymultirange</type> )
<returnvalue>anyelement</returnvalue>
</para>
<para>
Extracts the upper bound of the multirange (<literal>NULL</literal> if the
multirange is empty or has no upper bound).
</para>
<para>
diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml
index 4a727d44997..ac6647aec55 100644
--- a/doc/src/sgml/libpq.sgml
+++ b/doc/src/sgml/libpq.sgml
@@ -528,41 +528,41 @@ int PQsocketPoll(int sock, int forRead, int forWrite,
pg_usec_time_t end_time);
</synopsis>
</para>
<para>
This function performs polling of a file descriptor, optionally with
a timeout.
If <parameter>forRead</parameter> is nonzero, the
function will terminate when the socket is ready for
reading. If <parameter>forWrite</parameter> is nonzero,
the function will terminate when the
socket is ready for writing.
</para>
<para>
The timeout is specified by <parameter>end_time</parameter>, which
is the time to stop waiting expressed as a number of microseconds since
the Unix epoch (that is, <type>time_t</type> times 1 million).
Timeout is infinite if <parameter>end_time</parameter>
is <literal>-1</literal>. Timeout is immediate (no blocking) if
- end_time is <literal>0</literal> (or indeed, any time before now).
+ <parameter>end_time</parameter> is <literal>0</literal> (or indeed, any time before now).
Timeout values can be calculated conveniently by adding the desired
number of microseconds to the result of
<xref linkend="libpq-PQgetCurrentTimeUSec"/>.
Note that the underlying system calls may have less than microsecond
precision, so that the actual delay may be imprecise.
</para>
<para>
The function returns a value greater than <literal>0</literal> if the
specified condition is met, <literal>0</literal> if a timeout occurred,
or <literal>-1</literal> if an error occurred. The error can be
retrieved by checking the <literal>errno(3)</literal> value. In the
event both <parameter>forRead</parameter>
and <parameter>forWrite</parameter> are zero, the function immediately
returns a timeout indication.
</para>
<para>
<function>PQsocketPoll</function> is implemented using either
<function>poll(2)</function> or <function>select(2)</function>,
@@ -1814,41 +1814,41 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname
option was introduced in <productname>PostgreSQL</productname> version
17.
</para>
<variablelist>
<varlistentry>
<term><literal>postgres</literal></term>
<listitem>
<para>
perform <productname>PostgreSQL</productname> protocol
negotiation. This is the default if the option is not provided.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>direct</literal></term>
<listitem>
<para>
start SSL handshake directly after establishing the TCP/IP
- connection. This is only allowed with sslmode=require or higher,
+ connection. This is only allowed with <literal>sslmode=require</literal> or higher,
because the weaker settings could lead to unintended fallback to
plaintext authentication when the server does not support direct
SSL handshake.
</para>
</listitem>
</varlistentry>
</variablelist>
</listitem>
</varlistentry>
<varlistentry id="libpq-connect-sslcompression" xreflabel="sslcompression">
<term><literal>sslcompression</literal></term>
<listitem>
<para>
If set to 1, data sent over SSL connections will be compressed. If
set to 0, compression will be disabled. The default is 0. This
parameter is ignored if a connection without SSL is made.
</para>
<para>
@@ -9564,41 +9564,41 @@ ldap://ldap.acme.com/cn=dbserver,cn=hosts?pgconnectinfo?base?(objectclass=*)
<para>
Certificate Revocation List (CRL) entries are also checked
if the file <filename>~/.postgresql/root.crl</filename> exists
(<filename>%APPDATA%\postgresql\root.crl</filename> on Microsoft
Windows).
</para>
<para>
The location of the root certificate file and the CRL can be changed by
setting
the connection parameters <literal>sslrootcert</literal> and <literal>sslcrl</literal>
or the environment variables <envar>PGSSLROOTCERT</envar> and <envar>PGSSLCRL</envar>.
<literal>sslcrldir</literal> or the environment variable <envar>PGSSLCRLDIR</envar>
can also be used to specify a directory containing CRL files.
</para>
<note>
<para>
For backwards compatibility with earlier versions of PostgreSQL, if a
root CA file exists, the behavior of
- <literal>sslmode</literal>=<literal>require</literal> will be the same
+ <literal>sslmode=require</literal> will be the same
as that of <literal>verify-ca</literal>, meaning the server certificate
is validated against the CA. Relying on this behavior is discouraged,
and applications that need certificate validation should always use
<literal>verify-ca</literal> or <literal>verify-full</literal>.
</para>
</note>
</sect2>
<sect2 id="libpq-ssl-clientcert">
<title>Client Certificates</title>
<para>
If the server attempts to verify the identity of the
client by requesting the client's leaf certificate,
<application>libpq</application> will send the certificate(s) stored in
file <filename>~/.postgresql/postgresql.crt</filename> in the user's home
directory. The certificates must chain to the root certificate trusted
by the server. A matching
private key file <filename>~/.postgresql/postgresql.key</filename> must also
be present.
diff --git a/doc/src/sgml/protocol.sgml b/doc/src/sgml/protocol.sgml
index 2d2481bb8b8..95aad54ca62 100644
--- a/doc/src/sgml/protocol.sgml
+++ b/doc/src/sgml/protocol.sgml
@@ -3248,41 +3248,41 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
and above, and it allows streaming of large in-progress transactions.
</para>
<para>
Version <literal>3</literal> is supported only for server version 15
and above, and it allows streaming of two-phase commits.
</para>
<para>
Version <literal>4</literal> is supported only for server version 16
and above, and it allows streams of large in-progress transactions to
be applied in parallel.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
publication_names
</term>
<listitem>
<para>
- 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.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
binary
</term>
<listitem>
<para>
Boolean option to use binary transfer mode. Binary mode is faster
than the text mode but slightly less robust.
</para>
</listitem>
</varlistentry>
<varlistentry>
@@ -3313,42 +3313,42 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
</varlistentry>
<varlistentry>
<term>
two_phase
</term>
<listitem>
<para>
Boolean option to enable two-phase transactions. Minimum protocol
version 3 is required to turn it on.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
origin
</term>
<listitem>
<para>
- 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 <literal>none</literal>
+ to only send the changes that have no origin associated, or <literal>any</literal>
to send the changes regardless of their origin. This can be used
to avoid loops (infinite replication of the same data) among
replication nodes.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</sect2>
<sect2 id="protocol-logical-messages">
<title>Logical Replication Protocol Messages</title>
<para>
The individual protocol messages are discussed in the following
subsections. Individual messages are described in
<xref linkend="protocol-logicalrep-message-formats"/>.
</para>
diff --git a/doc/src/sgml/ref/alter_table.sgml b/doc/src/sgml/ref/alter_table.sgml
index 925f1084e00..d8da99e44fb 100644
--- a/doc/src/sgml/ref/alter_table.sgml
+++ b/doc/src/sgml/ref/alter_table.sgml
@@ -1106,41 +1106,41 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
table and <literal>ACCESS EXCLUSIVE</literal> on the partition,
and the detach process completes. A <literal>CHECK</literal> constraint
that duplicates the partition constraint is added to the partition.
<literal>CONCURRENTLY</literal> cannot be run in a transaction block and
is not allowed if the partitioned table contains a default partition.
</para>
<para>
If <literal>FINALIZE</literal> is specified, a previous
<literal>DETACH CONCURRENTLY</literal> invocation that was canceled or
interrupted is completed.
At most one partition in a partitioned table can be pending detach at
a time.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>
- All the forms of ALTER TABLE that act on a single table, except
+ All the forms of <command>ALTER TABLE</command> that act on a single table, except
<literal>RENAME</literal>, <literal>SET SCHEMA</literal>,
<literal>ATTACH PARTITION</literal>, and
<literal>DETACH PARTITION</literal> can be combined into
a list of multiple alterations to be applied together. For example, it
is possible to add several columns and/or alter the type of several
columns in a single command. This is particularly useful with large
tables, since only one pass over the table need be made.
</para>
<para>
You must own the table to use <command>ALTER TABLE</command>.
To change the schema or tablespace of a table, you must also have
<literal>CREATE</literal> privilege on the new schema or tablespace.
To add the table as a new child of a parent table, you must own the parent
table as well. Also, to attach a table as a new partition of the table,
you must own the table being attached.
To alter the owner, you must be able to <literal>SET ROLE</literal> to the
new owning role, and that role must have <literal>CREATE</literal>
privilege on the table's schema.
(These restrictions enforce that altering the owner
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
@@ -410,41 +410,41 @@ COPY { <replaceable class="parameter">table_name</replaceable> [ ( <replaceable
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>ENCODING</literal></term>
<listitem>
<para>
Specifies that the file is encoded in the <replaceable
class="parameter">encoding_name</replaceable>. If this option is
omitted, the current client encoding is used. See the Notes below
for more details.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>LOG_VERBOSITY</literal></term>
<listitem>
<para>
- Specify the amount of messages emitted by a <command>COPY</command>
+ Specifies the amount of messages emitted by a <command>COPY</command>
command: <literal>default</literal> or <literal>verbose</literal>. If
<literal>verbose</literal> is specified, additional messages are emitted
during processing.
</para>
<para>
This is currently used in <command>COPY FROM</command> command when
<literal>ON_ERROR</literal> option is set to <literal>ignore</literal>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>WHERE</literal></term>
<listitem>
<para>
The optional <literal>WHERE</literal> clause has the general form
<synopsis>
WHERE <replaceable class="parameter">condition</replaceable>
</synopsis>
where <replaceable class="parameter">condition</replaceable> is
@@ -762,41 +762,41 @@ COPY <replaceable class="parameter">count</replaceable>
<para>
<command>COPY TO</command> will terminate each row with a Unix-style
newline (<quote><literal>\n</literal></quote>). Servers running on Microsoft Windows instead
output carriage return/newline (<quote><literal>\r\n</literal></quote>), but only for
<command>COPY</command> to a server file; for consistency across platforms,
<command>COPY TO STDOUT</command> always sends <quote><literal>\n</literal></quote>
regardless of server platform.
<command>COPY FROM</command> can handle lines ending with newlines,
carriage returns, or carriage return/newlines. To reduce the risk of
error due to un-backslashed newlines or carriage returns that were
meant as data, <command>COPY FROM</command> will complain if the line
endings in the input are not all alike.
</para>
</refsect2>
<refsect2>
<title>CSV Format</title>
<para>
- This format option is used for importing and exporting the Comma
+ This format option is used for importing and exporting the Comma-
Separated Value (<literal>CSV</literal>) file format used by many other
programs, such as spreadsheets. Instead of the escaping rules used by
<productname>PostgreSQL</productname>'s standard text format, it
produces and recognizes the common <literal>CSV</literal> escaping mechanism.
</para>
<para>
The values in each record are separated by the <literal>DELIMITER</literal>
character. If the value contains the delimiter character, the
<literal>QUOTE</literal> character, the <literal>NULL</literal> string, a carriage
return, or line feed character, then the whole value is prefixed and
suffixed by the <literal>QUOTE</literal> character, and any occurrence
within the value of a <literal>QUOTE</literal> character or the
<literal>ESCAPE</literal> character is preceded by the escape character.
You can also use <literal>FORCE_QUOTE</literal> to force quotes when outputting
non-<literal>NULL</literal> values in specific columns.
</para>
<para>
The <literal>CSV</literal> format has no standard way to distinguish a
diff --git a/doc/src/sgml/ref/create_subscription.sgml b/doc/src/sgml/ref/create_subscription.sgml
index 740b7d94210..cd73105839a 100644
--- a/doc/src/sgml/ref/create_subscription.sgml
+++ b/doc/src/sgml/ref/create_subscription.sgml
@@ -168,41 +168,41 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
<term><literal>slot_name</literal> (<type>string</type>)</term>
<listitem>
<para>
Name of the publisher's replication slot to use. The default is
to use the name of the subscription for the slot name.
</para>
<para>
Setting <literal>slot_name</literal> to <literal>NONE</literal>
means there will be no replication slot associated with the
subscription. Such subscriptions must also have both
<literal>enabled</literal> and <literal>create_slot</literal> set to
<literal>false</literal>. Use this when you will be creating the
replication slot later manually. See
<xref linkend="logical-replication-subscription-examples-deferred-slot"/>
for examples.
</para>
<para>
When setting <literal>slot_name</literal> to a valid name and
- <literal>create_slot</literal> to false, the
+ <literal>create_slot</literal> to <literal>false</literal>, the
<literal>failover</literal> property value of the named slot may
differ from the counterpart <literal>failover</literal> parameter
specified in the subscription. Always ensure the slot property
<literal>failover</literal> matches the counterpart parameter of the
subscription and vice versa. Otherwise, the slot on the publisher may
behave differently from what these subscription options say: for
example, the slot on the publisher could either be synced to the
standbys even when the subscription's <literal>failover</literal>
option is disabled or could be disabled for sync even when the
subscription's <literal>failover</literal> option is enabled.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>
The following parameters control the subscription's replication
behavior after it has been created:
@@ -457,41 +457,41 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
</para>
<para>
Creating a subscription that connects to the same database cluster (for
example, to replicate between databases in the same cluster or to replicate
within the same database) will only succeed if the replication slot is not
created as part of the same command. Otherwise, the <command>CREATE
SUBSCRIPTION</command> call will hang. To make this work, create the
replication slot separately (using the
function <function>pg_create_logical_replication_slot</function> with the
plugin name <literal>pgoutput</literal>) and create the subscription using
the parameter <literal>create_slot = false</literal>. See
<xref linkend="logical-replication-subscription-examples-deferred-slot"/>
for examples. This is an implementation restriction that might be lifted in a
future release.
</para>
<para>
If any table in the publication has a <literal>WHERE</literal> clause, rows
for which the <replaceable class="parameter">expression</replaceable>
- evaluates to false or null will not be published. If the subscription has
+ evaluates to <literal>false</literal> or <literal>NULL</literal> will not be published. If the subscription has
several publications in which the same table has been published with
different <literal>WHERE</literal> clauses, a row will be published if any
of the expressions (referring to that publish operation) are satisfied. In
the case of different <literal>WHERE</literal> clauses, if one of the
publications has no <literal>WHERE</literal> clause (referring to that
publish operation) or the publication is declared as
<link linkend="sql-createpublication-params-for-all-tables"><literal>FOR ALL TABLES</literal></link>
or <link linkend="sql-createpublication-params-for-tables-in-schema"><literal>FOR TABLES IN SCHEMA</literal></link>,
rows are always published regardless of the definition of the other
expressions. If the subscriber is a <productname>PostgreSQL</productname>
version before 15, then any row filtering is ignored during the initial data
synchronization phase. For this case, the user might want to consider
deleting any initially copied data that would be incompatible with
subsequent filtering. Because initial data synchronization does not take
into account the publication
<link linkend="sql-createpublication-params-with-publish"><literal>publish</literal></link>
parameter when copying existing table data, some rows may be copied that
would not be replicated using DML. See
<xref linkend="logical-replication-subscription-examples"/> for examples.
</para>
diff --git a/doc/src/sgml/ref/pg_basebackup.sgml b/doc/src/sgml/ref/pg_basebackup.sgml
index 4f99340c1dd..d96d93dc394 100644
--- a/doc/src/sgml/ref/pg_basebackup.sgml
+++ b/doc/src/sgml/ref/pg_basebackup.sgml
@@ -228,41 +228,41 @@ PostgreSQL documentation
<term><option>-R</option></term>
<term><option>--write-recovery-conf</option></term>
<listitem>
<para>
Creates a
<link linkend="file-standby-signal"><filename>standby.signal</filename></link>
<indexterm><primary><filename>standby.signal</filename></primary><secondary>pg_basebackup --write-recovery-conf</secondary></indexterm>
file and appends
connection settings to the <filename>postgresql.auto.conf</filename>
file in the target directory (or within the base archive file when
using tar format). This eases setting up a standby server using the
results of the backup.
</para>
<para>
The <filename>postgresql.auto.conf</filename> file will record the connection
settings and, if specified, the replication slot
that <application>pg_basebackup</application> is using, so that
streaming replication and <link linkend="logicaldecoding-replication-slots-synchronization">
logical replication slot synchronization</link> will use the same
- settings later on. The dbname will be recorded only if the dbname was
+ settings later on. The database name will be recorded only if it was
specified explicitly in the connection string or <link linkend="libpq-envars">
environment variable</link>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-t <replaceable class="parameter">target</replaceable></option></term>
<term><option>--target=<replaceable class="parameter">target</replaceable></option></term>
<listitem>
<para>
Instructs the server where to place the base backup. The default target
is <literal>client</literal>, which specifies that the backup should
be sent to the machine where <application>pg_basebackup</application>
is running. If the target is instead set to
<literal>server:/some/path</literal>, the backup will be stored on
the machine where the server is running in the
<literal>/some/path</literal> directory. Storing a backup on the
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
@@ -50,41 +50,41 @@ PostgreSQL documentation
change the layout of the system tables, but the internal data storage
format rarely changes. <application>pg_upgrade</application> uses this fact
to perform rapid upgrades by creating new system tables and simply
reusing the old user data files. If a future major release ever
changes the data storage format in a way that makes the old data
format unreadable, <application>pg_upgrade</application> will not be usable
for such upgrades. (The community will attempt to avoid such
situations.)
</para>
<para>
<application>pg_upgrade</application> does its best to
make sure the old and new clusters are binary-compatible, e.g., by
checking for compatible compile-time settings, including 32/64-bit
binaries. It is important that
any external modules are also binary compatible, though this cannot
be checked by <application>pg_upgrade</application>.
</para>
<para>
- pg_upgrade supports upgrades from 9.2.X and later to the current
+ <application>pg_upgrade</application> supports upgrades from 9.2.X and later to the current
major release of <productname>PostgreSQL</productname>, including snapshot and beta releases.
</para>
</refsect1>
<refsect1>
<title>Options</title>
<para>
<application>pg_upgrade</application> accepts the following command-line arguments:
<variablelist>
<varlistentry>
<term><option>-b</option> <replaceable>bindir</replaceable></term>
<term><option>--old-bindir=</option><replaceable>bindir</replaceable></term>
<listitem><para>the old PostgreSQL executable directory;
environment variable <envar>PGBINOLD</envar></para></listitem>
</varlistentry>
<varlistentry>
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
@@ -70,41 +70,41 @@
versions).
</para>
<para>
The <command>sestatus</command> command allows you to check the status of
<productname>SELinux</productname>. A typical display is:
<screen>
$ sestatus
SELinux status: enabled
SELinuxfs mount: /selinux
Current mode: enforcing
Mode from config file: enforcing
Policy version: 24
Policy from config file: targeted
</screen>
If <productname>SELinux</productname> is disabled or not installed, you must set
that product up first before installing this module.
</para>
<para>
- To build this module specify <xref
+ To build this module, specify <xref
linkend="configure-option-with-sepgsql"/> (when using <link
linkend="install-make">make and autoconf</link> ) or <xref
linkend="configure-with-sepgsql-meson"/> (when using <link
linkend="install-meson">meson</link>).
Be sure that the <filename>libselinux-devel</filename> RPM is installed at
build time.
</para>
<para>
To use this module, you must include <literal>sepgsql</literal>
in the <xref linkend="guc-shared-preload-libraries"/> parameter in
<filename>postgresql.conf</filename>. The module will not function correctly
if loaded in any other manner. Once the module is loaded, you
should execute <filename>sepgsql.sql</filename> in each database.
This will install functions needed for security label management, and
assign initial security labels.
</para>
<para>
diff --git a/doc/src/sgml/syntax.sgml b/doc/src/sgml/syntax.sgml
index 4dfbbd08626..916189a7d68 100644
--- a/doc/src/sgml/syntax.sgml
+++ b/doc/src/sgml/syntax.sgml
@@ -2479,41 +2479,41 @@ SELECT getf1(ROW(1,2.5,'this is a test')::mytable);
-------
1
(1 row)
SELECT getf1(CAST(ROW(11,'this is a test',2.5) AS myrowtype));
getf1
-------
11
(1 row)
</programlisting>
</para>
<para>
Row constructors can be used to build composite values to be stored
in a composite-type table column, or to be passed to a function that
accepts a composite parameter. Also, it is possible to test rows
using the standard comparison operators as described in <xref
linkend="functions-comparison"/>, to compare one row against another
as described in <xref linkend="functions-comparisons"/>, and to
use them in connection with subqueries, as discussed in <xref
- linkend="functions-subquery"/>,
+ linkend="functions-subquery"/>.
</para>
</sect2>
<sect2 id="syntax-express-eval">
<title>Expression Evaluation Rules</title>
<indexterm>
<primary>expression</primary>
<secondary>order of evaluation</secondary>
</indexterm>
<para>
The order of evaluation of subexpressions is not defined. In
particular, the inputs of an operator or function are not necessarily
evaluated left-to-right or in any other fixed order.
</para>
<para>
Furthermore, if the result of an expression can be determined by
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
@@ -2569,41 +2569,41 @@ SELECT * FROM pg_locks pl LEFT JOIN pg_prepared_xacts ppx
The time since the slot has become inactive.
<literal>NULL</literal> if the slot is currently being used.
Note that for slots on the standby that are being synced from a
primary server (whose <structfield>synced</structfield> field is
<literal>true</literal>), the
<structfield>inactive_since</structfield> indicates the last
synchronization (see
<xref linkend="logicaldecoding-replication-slots-synchronization"/>)
time.
</para></entry>
</row>
<row>
<entry role="catalog_table_entry"><para role="column_definition">
<structfield>conflicting</structfield> <type>bool</type>
</para>
<para>
True if this logical slot conflicted with recovery (and so is now
invalidated). When this column is true, check
<structfield>invalidation_reason</structfield> column for the conflict
- reason. Always NULL for physical slots.
+ reason. Always <literal>NULL</literal> for physical slots.
</para></entry>
</row>
<row>
<entry role="catalog_table_entry"><para role="column_definition">
<structfield>invalidation_reason</structfield> <type>text</type>
</para>
<para>
The reason for the slot's invalidation. It is set for both logical and
physical slots. <literal>NULL</literal> if the slot is not invalidated.
Possible values are:
<itemizedlist spacing="compact">
<listitem>
<para>
<literal>wal_removed</literal> means that the required WAL has been
removed.
</para>
</listitem>
<listitem>
<para>
@@ -3928,41 +3928,41 @@ SELECT * FROM pg_locks pl LEFT JOIN pg_prepared_xacts ppx
<row>
<entry role="catalog_table_entry"><para role="column_definition">
<structfield>elem_count_histogram</structfield> <type>float4[]</type>
</para>
<para>
A histogram of the counts of distinct non-null element values within the
values of the column, followed by the average number of distinct
non-null elements. (Null for scalar types.)
</para></entry>
</row>
<row>
<entry role="catalog_table_entry"><para role="column_definition">
<structfield>range_length_histogram</structfield> <type>anyarray</type>
</para>
<para>
A histogram of the lengths of non-empty and non-null range values of a
range type column. (Null for non-range types.)
</para>
<para>
- This histogram is calculated using the <literal>subtype_diff</literal>
+ This histogram is calculated using the <function>subtype_diff</function>
range function regardless of whether range bounds are inclusive.
</para></entry>
</row>
<row>
<entry role="catalog_table_entry"><para role="column_definition">
<structfield>range_empty_frac</structfield> <type>float4</type>
</para>
<para>
Fraction of column entries whose values are empty ranges.
(Null for non-range types.)
</para></entry>
</row>
<row>
<entry role="catalog_table_entry"><para role="column_definition">
<structfield>range_bounds_histogram</structfield> <type>anyarray</type>
</para>
<para>
A histogram of lower and upper bounds of non-empty and non-null range
diff --git a/doc/src/sgml/trigger.sgml b/doc/src/sgml/trigger.sgml
index 49382d07fa8..9202dddd2e8 100644
--- a/doc/src/sgml/trigger.sgml
+++ b/doc/src/sgml/trigger.sgml
@@ -340,41 +340,41 @@
<literal>AFTER</literal>, the <literal>BEFORE</literal> case is more efficient, since
the information about
the operation doesn't have to be saved until end of statement.
</para>
<para>
If a trigger function executes SQL commands then these
commands might fire triggers again. This is known as cascading
triggers. There is no direct limitation on the number of cascade
levels. It is possible for cascades to cause a recursive invocation
of the same trigger; for example, an <command>INSERT</command>
trigger might execute a command that inserts an additional row
into the same table, causing the <command>INSERT</command> trigger
to be fired again. It is the trigger programmer's responsibility
to avoid infinite recursion in such scenarios.
</para>
<para>
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 <command>UPDATE</command> or <command>DELETE</command> 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
be to break referential integrity. It is the trigger programmer's
responsibility to avoid that.
</para>
<para>
<indexterm>
<primary>trigger</primary>
<secondary>arguments for trigger functions</secondary>
</indexterm>
When a trigger is being defined, arguments can be specified for
it. The purpose of including arguments in the
trigger definition is to allow different triggers with similar
requirements to call the same function. As an example, there
could be a generalized trigger function that takes as its
arguments two column names and puts the current user in one and
the current time stamp in the other. Properly written, this
trigger function would be independent of the specific table it is
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
@@ -390,41 +390,41 @@ CREATE ROLE <replaceable>name</replaceable>;
<link linkend="sql-revoke"><command>REVOKE</command></link> commands:
<synopsis>
GRANT <replaceable>group_role</replaceable> TO <replaceable>role1</replaceable>, ... ;
REVOKE <replaceable>group_role</replaceable> FROM <replaceable>role1</replaceable>, ... ;
</synopsis>
You can grant membership to other group roles, too (since there isn't
really any distinction between group roles and non-group roles). The
database will not let you set up circular membership loops. Also,
it is not permitted to grant membership in a role to
<literal>PUBLIC</literal>.
</para>
<para>
The members of a group role can use the privileges of the role in two
ways. First, member roles that have been granted membership with the
<literal>SET</literal> option can do
<link linkend="sql-set-role"><command>SET ROLE</command></link> to
temporarily <quote>become</quote> 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
<literal>INHERIT</literal> option automatically have use of the
privileges of those directly or indirectly a member of, though the
chain stops at memberships lacking the inherit option. As an example,
suppose we have done:
<programlisting>
CREATE ROLE joe LOGIN;
CREATE ROLE admin;
CREATE ROLE wheel;
CREATE ROLE island;
GRANT admin TO joe WITH INHERIT TRUE;
GRANT wheel TO admin WITH INHERIT FALSE;
GRANT island TO joe WITH INHERIT TRUE, SET FALSE;
</programlisting>
Immediately after connecting as role <literal>joe</literal>, a database
session will have use of privileges granted directly to <literal>joe</literal>
plus any privileges granted to <literal>admin</literal> and
<literal>island</literal>, because <literal>joe</literal>
<quote>inherits</quote> those privileges. However, privileges
granted to <literal>wheel</literal> are not available, because even though
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
@@ -662,45 +662,45 @@
the second.
A restartpoint is triggered by schedule when a checkpoint record is reached
if at least <xref linkend="guc-checkpoint-timeout"/> seconds have passed since
the last performed restartpoint or when the previous attempt to perform
the restartpoint has failed. In the last case, the next restartpoint
will be scheduled in 15 seconds.
A restartpoint is triggered by request due to similar reasons like checkpoint
but mostly if WAL size is about to exceed <xref linkend="guc-max-wal-size"/>
However, because of limitations on when a restartpoint can be performed,
<varname>max_wal_size</varname> is often exceeded during recovery,
by up to one checkpoint cycle's worth of WAL.
(<varname>max_wal_size</varname> is never a hard limit anyway, so you should
always leave plenty of headroom to avoid running out of disk space.)
The <structfield>restartpoints_done</structfield> counter in the
<link linkend="monitoring-pg-stat-checkpointer-view"><structname>pg_stat_checkpointer</structname></link>
view counts the restartpoints that have really been performed.
</para>
<para>
In some cases, when the WAL size on the primary increases quickly,
- for instance during massive INSERT,
+ for instance during massive <command>INSERT</command>,
the <structfield>restartpoints_req</structfield> 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.
Only the <structfield>restartpoints_done</structfield>
counter among the restartpoint-related ones indicates that noticeable system
resources have been spent.
</para>
<para>
There are two commonly used internal <acronym>WAL</acronym> functions:
<function>XLogInsertRecord</function> and <function>XLogFlush</function>.
<function>XLogInsertRecord</function> is used to place a new record into
the <acronym>WAL</acronym> buffers in shared memory. If there is no
space for the new record, <function>XLogInsertRecord</function> will have
to write (move to kernel cache) a few filled <acronym>WAL</acronym>
buffers. This is undesirable because <function>XLogInsertRecord</function>
is used on every database low level modification (for example, row
insertion) at a time when an exclusive lock is held on affected
data pages, so the operation needs to be as fast as possible. What
is worse, writing <acronym>WAL</acronym> buffers might also force the
^ permalink raw reply [nested|flat] 23+ messages in thread
* Re: Documentation improvement patch
2024-09-05 09:33 Documentation improvement patch Oleg Sibiryakov <o.sibiryakov@postgrespro.ru>
2024-09-06 13:20 ` Re: Documentation improvement patch Daniel Gustafsson <daniel@yesql.se>
2024-09-10 11:46 ` Re: Documentation improvement patch Oleg Sibiryakov <o.sibiryakov@postgrespro.ru>
2024-09-10 13:02 ` Re: Documentation improvement patch Daniel Gustafsson <daniel@yesql.se>
2024-09-11 09:53 ` Re: Documentation improvement patch Peter Eisentraut <peter@eisentraut.org>
2024-09-13 10:50 ` Re: Documentation improvement patch Oleg Sibiryakov <o.sibiryakov@postgrespro.ru>
2024-10-01 08:04 ` Re: Documentation improvement patch Oleg Sibiryakov <o.sibiryakov@postgrespro.ru>
2024-10-01 08:59 ` Re: Documentation improvement patch Daniel Gustafsson <daniel@yesql.se>
2024-10-02 08:09 ` Re: Documentation improvement patch Oleg Sibiryakov <o.sibiryakov@postgrespro.ru>
@ 2024-10-02 12:58 ` Daniel Gustafsson <daniel@yesql.se>
2024-10-07 08:54 ` Re: Documentation improvement patch Oleg Sibiryakov <o.sibiryakov@postgrespro.ru>
0 siblings, 1 reply; 23+ messages in thread
From: Daniel Gustafsson @ 2024-10-02 12:58 UTC (permalink / raw)
To: Oleg Sibiryakov <o.sibiryakov@postgrespro.ru>; +Cc: pgsql-docs@lists.postgresql.org
> On 2 Oct 2024, at 10:09, Oleg Sibiryakov <o.sibiryakov@postgrespro.ru> wrote:
>
> Thank you for your kind feedback! I will take due note of the comments in the next documentation patches as well.
>
> I have made all the changes as per your feedback and also corrected paragraph reflow.
>
> The third version of the patch is attached for your consideration.
Thanks, I have gone over and applied most of these changes. I did leave out a
few (like the libc one) where the current page had multiple different versions.
--
Daniel Gustafsson
^ permalink raw reply [nested|flat] 23+ messages in thread
* Re: Documentation improvement patch
2024-09-05 09:33 Documentation improvement patch Oleg Sibiryakov <o.sibiryakov@postgrespro.ru>
2024-09-06 13:20 ` Re: Documentation improvement patch Daniel Gustafsson <daniel@yesql.se>
2024-09-10 11:46 ` Re: Documentation improvement patch Oleg Sibiryakov <o.sibiryakov@postgrespro.ru>
2024-09-10 13:02 ` Re: Documentation improvement patch Daniel Gustafsson <daniel@yesql.se>
2024-09-11 09:53 ` Re: Documentation improvement patch Peter Eisentraut <peter@eisentraut.org>
2024-09-13 10:50 ` Re: Documentation improvement patch Oleg Sibiryakov <o.sibiryakov@postgrespro.ru>
2024-10-01 08:04 ` Re: Documentation improvement patch Oleg Sibiryakov <o.sibiryakov@postgrespro.ru>
2024-10-01 08:59 ` Re: Documentation improvement patch Daniel Gustafsson <daniel@yesql.se>
2024-10-02 08:09 ` Re: Documentation improvement patch Oleg Sibiryakov <o.sibiryakov@postgrespro.ru>
2024-10-02 12:58 ` Re: Documentation improvement patch Daniel Gustafsson <daniel@yesql.se>
@ 2024-10-07 08:54 ` Oleg Sibiryakov <o.sibiryakov@postgrespro.ru>
0 siblings, 0 replies; 23+ messages in thread
From: Oleg Sibiryakov @ 2024-10-07 08:54 UTC (permalink / raw)
To: Daniel Gustafsson <daniel@yesql.se>; +Cc: pgsql-docs@lists.postgresql.org
Thank you, Daniel.
--
Oleg Sibiryakov
On 02.10.2024 15:58, Daniel Gustafsson wrote:
>> On 2 Oct 2024, at 10:09, Oleg Sibiryakov <o.sibiryakov@postgrespro.ru> wrote:
>>
>> Thank you for your kind feedback! I will take due note of the comments in the next documentation patches as well.
>>
>> I have made all the changes as per your feedback and also corrected paragraph reflow.
>>
>> The third version of the patch is attached for your consideration.
> Thanks, I have gone over and applied most of these changes. I did leave out a
> few (like the libc one) where the current page had multiple different versions.
>
> --
> Daniel Gustafsson
>
>
>
^ permalink raw reply [nested|flat] 23+ messages in thread
* Documentation improvement patch
@ 2025-09-10 07:54 Oleg <o.sibiryakov@postgrespro.ru>
2025-10-10 06:38 ` Re: Documentation improvement patch Oleg <o.sibiryakov@postgrespro.ru>
2025-10-10 07:15 ` Re: Documentation improvement patch Daniel Gustafsson <daniel@yesql.se>
0 siblings, 2 replies; 23+ messages in thread
From: Oleg @ 2025-09-10 07:54 UTC (permalink / raw)
To: pgsql-docs@lists.postgresql.org
Dear all,
I have prepared a patch containing some minor inconsistencies in the
documentation. Please, take a look.
I will be looking forward to your feedback.
The patch shall be applied to the REL_18_STABLE branch.
--
Regards,
Oleg Sibiryakov
Technical Writer
Postgres Professional, The Russian Postgres Company
https://postgrespro.ru
Attachments:
[text/x-patch] doc_improvements_postgresql-18.patch (9.2K, ../../e62bedb5-c26f-4d37-b4ed-ce9b55f1e980@postgrespro.ru/3-doc_improvements_postgresql-18.patch)
download | inline diff:
diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml
index d1e103ed779..e589a8d6884 100644
--- a/doc/src/sgml/config.sgml
+++ b/doc/src/sgml/config.sgml
@@ -1234,7 +1234,7 @@ include_dir 'conf.d'
</term>
<listitem>
<para>
- The library/libraries to use for validating OAuth connection tokens. If
+ Sets the library/libraries to use for validating OAuth connection tokens. If
only one validator library is provided, it will be used by default for
any OAuth connections; otherwise, all
<link linkend="auth-oauth"><literal>oauth</literal> HBA entries</link>
@@ -1400,7 +1400,7 @@ include_dir 'conf.d'
<para>
Specifies a list of cipher suites that are allowed by connections using
<acronym>TLS</acronym> version 1.3. Multiple cipher suites can be
- specified by using a colon separated list. If left blank, the default
+ specified by using a colon-separated list. If left blank, the default
set of cipher suites in <productname>OpenSSL</productname> will be used.
</para>
@@ -2432,7 +2432,7 @@ include_dir 'conf.d'
</term>
<listitem>
<para>
- Sets the maximum number of open files each server subprocess is
+ Sets the maximum number of files each server subprocess is
allowed to open simultaneously; files already opened in the
postmaster are not counted toward this limit. The default is one
thousand files.
diff --git a/doc/src/sgml/postgres-fdw.sgml b/doc/src/sgml/postgres-fdw.sgml
index 781a01067f7..9b032fbf675 100644
--- a/doc/src/sgml/postgres-fdw.sgml
+++ b/doc/src/sgml/postgres-fdw.sgml
@@ -1226,7 +1226,7 @@ postgres=# SELECT postgres_fdw_disconnect_all();
<term><literal>PostgresFdwCleanupResult</literal></term>
<listitem>
<para>
- Waiting for transaction abort on remote server.
+ Waiting for transaction abort on a remote server.
</para>
</listitem>
</varlistentry>
diff --git a/doc/src/sgml/postgres.sgml b/doc/src/sgml/postgres.sgml
index af476c82fcc..2101442c90f 100644
--- a/doc/src/sgml/postgres.sgml
+++ b/doc/src/sgml/postgres.sgml
@@ -49,7 +49,7 @@ break is not needed in a wider output rendering.
</para>
<para>
- After you have successfully completed this tutorial you will want to
+ After you have successfully completed this tutorial, you will want to
read the <xref linkend="sql"/> section to gain a better understanding
of the SQL language, or <xref linkend="client-interfaces"/> for
information about developing applications with
diff --git a/doc/src/sgml/protocol.sgml b/doc/src/sgml/protocol.sgml
index d336ee38f58..80eadfc0e1a 100644
--- a/doc/src/sgml/protocol.sgml
+++ b/doc/src/sgml/protocol.sgml
@@ -1636,7 +1636,7 @@ SELCT 1/0;<!-- this typo is intentional -->
<para>
Likewise the server expects the client to not begin
the <acronym>SSL</acronym> negotiation until it receives the server's
- single byte response to the <acronym>SSL</acronym> request. If the
+ single-byte response to the <acronym>SSL</acronym> request. If the
client begins the <acronym>SSL</acronym> negotiation immediately without
waiting for the server response to be received it can reduce connection
latency by one round-trip. However this comes at the cost of not being
@@ -2394,7 +2394,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
</term>
<listitem>
<para>
- Change the definition of a replication slot.
+ Changes the definition of a replication slot.
See <xref linkend="streaming-replication-slots"/> for more about
replication slots. This command is currently only supported for logical
replication slots.
diff --git a/doc/src/sgml/ref/pg_recvlogical.sgml b/doc/src/sgml/ref/pg_recvlogical.sgml
index 263ebdeeab4..2a0de0cfb63 100644
--- a/doc/src/sgml/ref/pg_recvlogical.sgml
+++ b/doc/src/sgml/ref/pg_recvlogical.sgml
@@ -84,7 +84,7 @@ PostgreSQL documentation
</para>
<para>
- The <option>--slot</option> and <option>--dbname</option> are required
+ The <option>--slot</option> and <option>--dbname</option> options are required
for this action.
</para>
@@ -104,7 +104,7 @@ PostgreSQL documentation
</para>
<para>
- The <option>--slot</option> is required for this action.
+ The <option>--slot</option> option is required for this action.
</para>
</listitem>
</varlistentry>
@@ -121,8 +121,8 @@ PostgreSQL documentation
</para>
<para>
- The <option>--slot</option> and <option>--dbname</option>,
- <option>--file</option> are required for this action.
+ The <option>--slot</option>, <option>--dbname</option>, and
+ <option>--file</option> options are required for this action.
</para>
<para>
diff --git a/doc/src/sgml/ref/pgbench.sgml b/doc/src/sgml/ref/pgbench.sgml
index ab252d9fc74..e2b2a0ea26f 100644
--- a/doc/src/sgml/ref/pgbench.sgml
+++ b/doc/src/sgml/ref/pgbench.sgml
@@ -2826,7 +2826,7 @@ statement latencies in milliseconds, failures and retries:
start a connection to the database server / the socket for connecting
the client to the database server has become invalid). In such cases
all clients of this thread stop while other threads continue to work.
- However, <option>--exit-on-abort</option> is specified, all of the
+ However, if <option>--exit-on-abort</option> is specified, all of the
threads stop immediately in this case.
</para>
</listitem>
diff --git a/doc/src/sgml/regress.sgml b/doc/src/sgml/regress.sgml
index 8838fe7f022..8b014d657b3 100644
--- a/doc/src/sgml/regress.sgml
+++ b/doc/src/sgml/regress.sgml
@@ -366,7 +366,7 @@ make check-world PG_TEST_EXTRA='kerberos ldap ssl load_balance libpq_encryption'
<listitem>
<para>
Runs the test suite under <filename>src/test/modules/xid_wraparound</filename>.
- Not enabled by default because it is resource intensive.
+ Not enabled by default because it is resource-intensive.
</para>
</listitem>
</varlistentry>
diff --git a/doc/src/sgml/system-views.sgml b/doc/src/sgml/system-views.sgml
index d5ce93dd893..9229e0fa601 100644
--- a/doc/src/sgml/system-views.sgml
+++ b/doc/src/sgml/system-views.sgml
@@ -53,7 +53,7 @@
<tbody>
<row>
<entry><link linkend="view-pg-aios"><structname>pg_aios</structname></link></entry>
- <entry>In-use asynchronous IO handles</entry>
+ <entry>in-use asynchronous IO handles</entry>
</row>
<row>
diff --git a/doc/src/sgml/user-manag.sgml b/doc/src/sgml/user-manag.sgml
index ed18704a9c2..169f787fdd1 100644
--- a/doc/src/sgml/user-manag.sgml
+++ b/doc/src/sgml/user-manag.sgml
@@ -747,17 +747,17 @@ GRANT pg_signal_backend TO admin_user;
<para>
<literal>pg_read_server_files</literal> allows reading files from any
location the database can access on the server using
- <command>COPY</command> and other file-access functions.
+ the <command>COPY</command> command and file-access functions.
</para>
<para>
<literal>pg_write_server_files</literal> allows writing to files in any
location the database can access on the server using
- <command>COPY</command> and other file-access functions.
+ the <command>COPY</command> command and file-access functions.
</para>
<para>
<literal>pg_execute_server_program</literal> allows executing programs
on the database server as the user the database runs as using
- <command>COPY</command> and other functions which allow executing a
+ the <command>COPY</command> command and functions, which allow executing a
server-side program.
</para>
</listitem>
diff --git a/doc/src/sgml/xfunc.sgml b/doc/src/sgml/xfunc.sgml
index 2d81afce8cb..1418de07398 100644
--- a/doc/src/sgml/xfunc.sgml
+++ b/doc/src/sgml/xfunc.sgml
@@ -2400,7 +2400,7 @@ PG_FUNCTION_INFO_V1(funcname);
To call another version-1 function, you can use
<function>DirectFunctionCall<replaceable>n</replaceable>(func,
arg1, ..., argn)</function>. This is particularly useful when you want
- to call functions defined in the standard internal library, by using an
+ to call functions defined in the standard internal function library by using an
interface similar to their SQL signature.
</para>
@@ -3947,7 +3947,7 @@ extern bool InjectionPointDetach(const char *name);
</para>
<para>
- Enabling injections points requires
+ Enabling injection points requires
<option>--enable-injection-points</option> with
<command>configure</command> or <option>-Dinjection_points=true</option>
with <application>Meson</application>.
@@ -3964,7 +3964,7 @@ extern bool InjectionPointDetach(const char *name);
</para>
<para>
- First, define a <literal>PgStat_KindInfo</literal> that includes all
+ First, define <literal>PgStat_KindInfo</literal> that includes all
the information related to the custom type registered. For example:
<programlisting>
static const PgStat_KindInfo custom_stats = {
^ permalink raw reply [nested|flat] 23+ messages in thread
* Re: Documentation improvement patch
2025-09-10 07:54 Documentation improvement patch Oleg <o.sibiryakov@postgrespro.ru>
@ 2025-10-10 06:38 ` Oleg <o.sibiryakov@postgrespro.ru>
1 sibling, 0 replies; 23+ messages in thread
From: Oleg @ 2025-10-10 06:38 UTC (permalink / raw)
To: pgsql-docs@lists.postgresql.org
Dear PostgreSQL Community,
This is a kind reminder regarding my documentation patch submitted a
month ago.
I am still very interested in contributing these improvements and would
be grateful for a review when time permits.
The patch can be also applied to the master branch.
Thank you for your consideration.
--
Regards,
Oleg Sibiryakov
Technical Writer
Postgres Professional, The Russian Postgres Company
https://postgrespro.ru
On 10.09.2025 10:54, Oleg wrote:
>
> Dear all,
>
> I have prepared a patch containing some minor inconsistencies in the
> documentation. Please, take a look.
>
> I will be looking forward to your feedback.
>
> The patch shall be applied to the REL_18_STABLE branch.
>
> --
> Regards,
> Oleg Sibiryakov
> Technical Writer
> Postgres Professional, The Russian Postgres Company
> https://postgrespro.ru
>
^ permalink raw reply [nested|flat] 23+ messages in thread
* Re: Documentation improvement patch
2025-09-10 07:54 Documentation improvement patch Oleg <o.sibiryakov@postgrespro.ru>
@ 2025-10-10 07:15 ` Daniel Gustafsson <daniel@yesql.se>
2025-10-13 10:51 ` Re: Documentation improvement patch Oleg <o.sibiryakov@postgrespro.ru>
1 sibling, 1 reply; 23+ messages in thread
From: Daniel Gustafsson @ 2025-10-10 07:15 UTC (permalink / raw)
To: Oleg <o.sibiryakov@postgrespro.ru>; +Cc: pgsql-docs@lists.postgresql.org
> On 10 Sep 2025, at 09:54, Oleg <o.sibiryakov@postgrespro.ru> wrote:
>
> Dear all,
> I have prepared a patch containing some minor inconsistencies in the documentation. Please, take a look.
> I will be looking forward to your feedback.
Thanks for the patch, while most of these are obvious improvements I have a few
comments on some:
- Change the definition of a replication slot.
+ Changes the definition of a replication slot.
Reading this page it seems we are mixing tense in many places, some say "Change
the" and "Read some" and elsewhere we use "Drops the". Maybe a more holistic
approach would be better for this page to improve consistency?
- Not enabled by default because it is resource intensive.
+ Not enabled by default because it is resource-intensive.
We use both spellings in multiple places, shouldn't all be changed?
- <command>COPY</command> and other file-access functions.
+ the <command>COPY</command> command and file-access functions.
...
- <command>COPY</command> and other file-access functions.
+ the <command>COPY</command> command and file-access functions.
...
- <command>COPY</command> and other functions which allow executing a
+ the <command>COPY</command> command and functions, which allow executing a
I'm not sure about these, I think we use COPY without the the "the COPY
command" decoration in many places so I think it's more consistent like this.
- to call functions defined in the standard internal library, by using an
+ to call functions defined in the standard internal function library by using an
interface similar to their SQL signature.
Isn't it a bit redundant to say "internal function library" when we are already
talking about function definitions?
> The patch shall be applied to the REL_18_STABLE branch.
As you mentioned downthread, this is also for master. Our workflow is to
always apply to master and backpatch from there.
--
Daniel Gustafsson
^ permalink raw reply [nested|flat] 23+ messages in thread
* Re: Documentation improvement patch
2025-09-10 07:54 Documentation improvement patch Oleg <o.sibiryakov@postgrespro.ru>
2025-10-10 07:15 ` Re: Documentation improvement patch Daniel Gustafsson <daniel@yesql.se>
@ 2025-10-13 10:51 ` Oleg <o.sibiryakov@postgrespro.ru>
2025-10-22 02:41 ` Re: Documentation improvement patch Oleg <o.sibiryakov@postgrespro.ru>
2025-10-22 08:02 ` Re: Documentation improvement patch Daniel Gustafsson <daniel@yesql.se>
0 siblings, 2 replies; 23+ messages in thread
From: Oleg @ 2025-10-13 10:51 UTC (permalink / raw)
To: Daniel Gustafsson <daniel@yesql.se>; +Cc: pgsql-docs@lists.postgresql.org
Thank you for your feedback, Daniel.
My thoughts are below:
/- Change the definition of a replication slot. + Changes the definition
of a replication slot. Reading this page it seems we are mixing tense in
many places, some say "Change the" and "Read some" and elsewhere we use
"Drops the". Maybe a more holistic approach would be better for this
page to improve consistency? /I agree, let's add "s" in all cases for the sake of consistency.
/- Not enabled by default because it is resource intensive. + Not
enabled by default because it is resource-intensive. We use both
spellings in multiple places, shouldn't all be changed?/
Agreed, changing all instances to "resource-intensive".
/- <command>COPY</command> and other file-access functions. + the
<command>COPY</command> command and file-access functions. ... -
<command>COPY</command> and other file-access functions. + the
<command>COPY</command> command and file-access functions. ... -
<command>COPY</command> and other functions which allow executing a +
the <command>COPY</command> command and functions, which allow executing
a I'm not sure about these, I think we use COPY without the the "the
COPY command" decoration in many places so I think it's more consistent
like this. /I actually think we should add the decoration here because "<command>COPY</command> and other file-access functions"
sounds a bit confusing since COPY is not a file-access function and we seem to put it in the list. Even though I
agree that everybody knows COPY is a command, not a function.
/- to call functions defined in the standard internal library, by using
an + to call functions defined in the standard internal function library
by using an interface similar to their SQL signature. Isn't it a bit
redundant to say "internal function library" when we are already talking
about function definitions?/
I agree that it may seem redundant, I added "function" here for the sake of consistency with lines 1829/1830 (if applied to the master branch)
where the documentation mentions "standard internal*function* library".
Please, let me know what you think of the last two points for me to send the updated patch.
--
Oleg Sibiryakov
On 10.10.2025 10:15, Daniel Gustafsson wrote:
>> On 10 Sep 2025, at 09:54, Oleg<o.sibiryakov@postgrespro.ru> wrote:
>>
>> Dear all,
>> I have prepared a patch containing some minor inconsistencies in the documentation. Please, take a look.
>> I will be looking forward to your feedback.
> Thanks for the patch, while most of these are obvious improvements I have a few
> comments on some:
>
>
> - Change the definition of a replication slot.
> + Changes the definition of a replication slot.
> Reading this page it seems we are mixing tense in many places, some say "Change
> the" and "Read some" and elsewhere we use "Drops the". Maybe a more holistic
> approach would be better for this page to improve consistency?
>
>
> - Not enabled by default because it is resource intensive.
> + Not enabled by default because it is resource-intensive.
> We use both spellings in multiple places, shouldn't all be changed?
>
>
> - <command>COPY</command> and other file-access functions.
> + the <command>COPY</command> command and file-access functions.
> ...
> - <command>COPY</command> and other file-access functions.
> + the <command>COPY</command> command and file-access functions.
> ...
> - <command>COPY</command> and other functions which allow executing a
> + the <command>COPY</command> command and functions, which allow executing a
> I'm not sure about these, I think we use COPY without the the "the COPY
> command" decoration in many places so I think it's more consistent like this.
>
>
> - to call functions defined in the standard internal library, by using an
> + to call functions defined in the standard internal function library by using an
> interface similar to their SQL signature.
> Isn't it a bit redundant to say "internal function library" when we are already
> talking about function definitions?
>
>> The patch shall be applied to the REL_18_STABLE branch.
> As you mentioned downthread, this is also for master. Our workflow is to
> always apply to master and backpatch from there.
>
> --
> Daniel Gustafsson
>
>
>
^ permalink raw reply [nested|flat] 23+ messages in thread
* Re: Documentation improvement patch
2025-09-10 07:54 Documentation improvement patch Oleg <o.sibiryakov@postgrespro.ru>
2025-10-10 07:15 ` Re: Documentation improvement patch Daniel Gustafsson <daniel@yesql.se>
2025-10-13 10:51 ` Re: Documentation improvement patch Oleg <o.sibiryakov@postgrespro.ru>
@ 2025-10-22 02:41 ` Oleg <o.sibiryakov@postgrespro.ru>
1 sibling, 0 replies; 23+ messages in thread
From: Oleg @ 2025-10-22 02:41 UTC (permalink / raw)
To: Daniel Gustafsson <daniel@yesql.se>; +Cc: pgsql-docs@lists.postgresql.org
Dear Daniel,
Could you please provide your feedback on the last two points?
Once I have it, I will send the updated patch immediately to finalize
the improvements.
Thank you,
Oleg
On 13.10.2025 13:51, Oleg wrote:
> Thank you for your feedback, Daniel.
> My thoughts are below:
> /- Change the definition of a replication slot. + Changes the
> definition of a replication slot. Reading this page it seems we are
> mixing tense in many places, some say "Change the" and "Read some" and
> elsewhere we use "Drops the". Maybe a more holistic approach would be
> better for this page to improve consistency? /I agree, let's add "s" in all cases for the sake of consistency.
>
> /- Not enabled by default because it is resource intensive. + Not
> enabled by default because it is resource-intensive. We use both
> spellings in multiple places, shouldn't all be changed?/
>
> Agreed, changing all instances to "resource-intensive".
>
> /- <command>COPY</command> and other file-access functions. + the
> <command>COPY</command> command and file-access functions. ... -
> <command>COPY</command> and other file-access functions. + the
> <command>COPY</command> command and file-access functions. ... -
> <command>COPY</command> and other functions which allow executing a +
> the <command>COPY</command> command and functions, which allow
> executing a I'm not sure about these, I think we use COPY without the
> the "the COPY command" decoration in many places so I think it's more
> consistent like this. /I actually think we should add the decoration here because "<command>COPY</command> and other file-access functions"
> sounds a bit confusing since COPY is not a file-access function and we seem to put it in the list. Even though I
> agree that everybody knows COPY is a command, not a function.
>
> /- to call functions defined in the standard internal library, by
> using an + to call functions defined in the standard internal function
> library by using an interface similar to their SQL signature. Isn't it
> a bit redundant to say "internal function library" when we are already
> talking about function definitions?/
>
> I agree that it may seem redundant, I added "function" here for the sake of consistency with lines 1829/1830 (if applied to the master branch)
> where the documentation mentions "standard internal*function* library".
>
> Please, let me know what you think of the last two points for me to send the updated patch.
>
> --
> Oleg Sibiryakov
> On 10.10.2025 10:15, Daniel Gustafsson wrote:
>>> On 10 Sep 2025, at 09:54, Oleg<o.sibiryakov@postgrespro.ru> wrote:
>>>
>>> Dear all,
>>> I have prepared a patch containing some minor inconsistencies in the documentation. Please, take a look.
>>> I will be looking forward to your feedback.
>> Thanks for the patch, while most of these are obvious improvements I have a few
>> comments on some:
>>
>>
>> - Change the definition of a replication slot.
>> + Changes the definition of a replication slot.
>> Reading this page it seems we are mixing tense in many places, some say "Change
>> the" and "Read some" and elsewhere we use "Drops the". Maybe a more holistic
>> approach would be better for this page to improve consistency?
>>
>>
>> - Not enabled by default because it is resource intensive.
>> + Not enabled by default because it is resource-intensive.
>> We use both spellings in multiple places, shouldn't all be changed?
>>
>>
>> - <command>COPY</command> and other file-access functions.
>> + the <command>COPY</command> command and file-access functions.
>> ...
>> - <command>COPY</command> and other file-access functions.
>> + the <command>COPY</command> command and file-access functions.
>> ...
>> - <command>COPY</command> and other functions which allow executing a
>> + the <command>COPY</command> command and functions, which allow executing a
>> I'm not sure about these, I think we use COPY without the the "the COPY
>> command" decoration in many places so I think it's more consistent like this.
>>
>>
>> - to call functions defined in the standard internal library, by using an
>> + to call functions defined in the standard internal function library by using an
>> interface similar to their SQL signature.
>> Isn't it a bit redundant to say "internal function library" when we are already
>> talking about function definitions?
>>
>>> The patch shall be applied to the REL_18_STABLE branch.
>> As you mentioned downthread, this is also for master. Our workflow is to
>> always apply to master and backpatch from there.
>>
>> --
>> Daniel Gustafsson
>>
>>
>>
^ permalink raw reply [nested|flat] 23+ messages in thread
* Re: Documentation improvement patch
2025-09-10 07:54 Documentation improvement patch Oleg <o.sibiryakov@postgrespro.ru>
2025-10-10 07:15 ` Re: Documentation improvement patch Daniel Gustafsson <daniel@yesql.se>
2025-10-13 10:51 ` Re: Documentation improvement patch Oleg <o.sibiryakov@postgrespro.ru>
@ 2025-10-22 08:02 ` Daniel Gustafsson <daniel@yesql.se>
2025-10-25 19:01 ` Re: Documentation improvement patch Oleg <o.sibiryakov@postgrespro.ru>
1 sibling, 1 reply; 23+ messages in thread
From: Daniel Gustafsson @ 2025-10-22 08:02 UTC (permalink / raw)
To: Oleg <o.sibiryakov@postgrespro.ru>; +Cc: pgsql-docs@lists.postgresql.org
> On 13 Oct 2025, at 12:51, Oleg <o.sibiryakov@postgrespro.ru> wrote:
> - <command>COPY</command> and other functions which allow executing a
> + the <command>COPY</command> command and functions, which allow executing a
> I'm not sure about these, I think we use COPY without the the "the COPY
> command" decoration in many places so I think it's more consistent like this.
>
> I actually think we should add the decoration here because "<command>COPY</command> and other file-access functions"
> sounds a bit confusing since COPY is not a file-access function and we seem to put it in the list. Even though I
> agree that everybody knows COPY is a command, not a function.
We refer to SQL commands by just their names all over the documentation without
saying "an EXPLAIN command" etc, and I think this falls in that same category.
> - to call functions defined in the standard internal library, by using an
> + to call functions defined in the standard internal function library by using an
> interface similar to their SQL signature.
> Isn't it a bit redundant to say "internal function library" when we are already
> talking about function definitions?
>
> I agree that it may seem redundant, I added "function" here for the sake of consistency with lines 1829/1830 (if applied to the master branch)
> where the documentation mentions "standard internal function library".
I hadn't seen that, but with that in mind I agree that being consistent is good
so I'll withdraw that comment.
--
Daniel Gustafsson
^ permalink raw reply [nested|flat] 23+ messages in thread
* Re: Documentation improvement patch
2025-09-10 07:54 Documentation improvement patch Oleg <o.sibiryakov@postgrespro.ru>
2025-10-10 07:15 ` Re: Documentation improvement patch Daniel Gustafsson <daniel@yesql.se>
2025-10-13 10:51 ` Re: Documentation improvement patch Oleg <o.sibiryakov@postgrespro.ru>
2025-10-22 08:02 ` Re: Documentation improvement patch Daniel Gustafsson <daniel@yesql.se>
@ 2025-10-25 19:01 ` Oleg <o.sibiryakov@postgrespro.ru>
2025-10-30 10:15 ` Re: Documentation improvement patch Peter Eisentraut <peter@eisentraut.org>
0 siblings, 1 reply; 23+ messages in thread
From: Oleg @ 2025-10-25 19:01 UTC (permalink / raw)
To: Daniel Gustafsson <daniel@yesql.se>; +Cc: pgsql-docs@lists.postgresql.org
Dear Daniel,
Thank you for your prompt feedback.
Attached, please find the updated documentation patch, which
incorporates your suggestions from both the first and second rounds of
review.
--
Oleg Sibiryakov
On 22.10.2025 11:02, Daniel Gustafsson wrote:
>> On 13 Oct 2025, at 12:51, Oleg<o.sibiryakov@postgrespro.ru> wrote:
>> - <command>COPY</command> and other functions which allow executing a
>> + the <command>COPY</command> command and functions, which allow executing a
>> I'm not sure about these, I think we use COPY without the the "the COPY
>> command" decoration in many places so I think it's more consistent like this.
>>
>> I actually think we should add the decoration here because "<command>COPY</command> and other file-access functions"
>> sounds a bit confusing since COPY is not a file-access function and we seem to put it in the list. Even though I
>> agree that everybody knows COPY is a command, not a function.
> We refer to SQL commands by just their names all over the documentation without
> saying "an EXPLAIN command" etc, and I think this falls in that same category.
>
>> - to call functions defined in the standard internal library, by using an
>> + to call functions defined in the standard internal function library by using an
>> interface similar to their SQL signature.
>> Isn't it a bit redundant to say "internal function library" when we are already
>> talking about function definitions?
>>
>> I agree that it may seem redundant, I added "function" here for the sake of consistency with lines 1829/1830 (if applied to the master branch)
>> where the documentation mentions "standard internal function library".
> I hadn't seen that, but with that in mind I agree that being consistent is good
> so I'll withdraw that comment.
>
> --
> Daniel Gustafsson
>
>
>
Attachments:
[text/x-patch] doc_improvements_postgresql-18_v2.patch (19.8K, ../../284a26c6-0a38-47ab-bd73-e28943029046@postgrespro.ru/3-doc_improvements_postgresql-18_v2.patch)
download | inline diff:
diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml
index 0a2a8b49fdb..71c2bbf7615 100644
--- a/doc/src/sgml/config.sgml
+++ b/doc/src/sgml/config.sgml
@@ -1232,11 +1232,11 @@ include_dir 'conf.d'
<primary><varname>oauth_validator_libraries</varname> configuration parameter</primary>
</indexterm>
</term>
<listitem>
<para>
- The library/libraries to use for validating OAuth connection tokens. If
+ Sets the library/libraries to use for validating OAuth connection tokens. If
only one validator library is provided, it will be used by default for
any OAuth connections; otherwise, all
<link linkend="auth-oauth"><literal>oauth</literal> HBA entries</link>
must explicitly set a <literal>validator</literal> chosen from this
list. If set to an empty string (the default), OAuth connections will be
@@ -1398,11 +1398,11 @@ include_dir 'conf.d'
</term>
<listitem>
<para>
Specifies a list of cipher suites that are allowed by connections using
<acronym>TLS</acronym> version 1.3. Multiple cipher suites can be
- specified by using a colon separated list. If left blank, the default
+ specified by using a colon-separated list. If left blank, the default
set of cipher suites in <productname>OpenSSL</productname> will be used.
</para>
<para>
This parameter can only be set in the
@@ -2430,11 +2430,11 @@ include_dir 'conf.d'
<primary><varname>max_files_per_process</varname> configuration parameter</primary>
</indexterm>
</term>
<listitem>
<para>
- Sets the maximum number of open files each server subprocess is
+ Sets the maximum number of files each server subprocess is
allowed to open simultaneously; files already opened in the
postmaster are not counted toward this limit. The default is one
thousand files.
</para>
<para>
diff --git a/doc/src/sgml/installation.sgml b/doc/src/sgml/installation.sgml
index 593202f4fb2..fe8d73e1f8c 100644
--- a/doc/src/sgml/installation.sgml
+++ b/doc/src/sgml/installation.sgml
@@ -3168,11 +3168,11 @@ ninja install
<term><option>-DPG_TEST_EXTRA=<replaceable>TEST_SUITES</replaceable></option></term>
<listitem>
<para>
Enable additional test suites, which are not run by default because
they are not secure to run on a multiuser system, require special
- software to run, or are resource intensive. The argument is a
+ software to run, or are resource-intensive. The argument is a
whitespace-separated list of tests to enable. See
<xref linkend="regress-additional"/> for details. If the
<envar>PG_TEST_EXTRA</envar> environment variable is set when the
tests are run, it overrides this setup-time option.
</para>
diff --git a/doc/src/sgml/postgres-fdw.sgml b/doc/src/sgml/postgres-fdw.sgml
index 781a01067f7..9b032fbf675 100644
--- a/doc/src/sgml/postgres-fdw.sgml
+++ b/doc/src/sgml/postgres-fdw.sgml
@@ -1224,11 +1224,11 @@ postgres=# SELECT postgres_fdw_disconnect_all();
<variablelist>
<varlistentry>
<term><literal>PostgresFdwCleanupResult</literal></term>
<listitem>
<para>
- Waiting for transaction abort on remote server.
+ Waiting for transaction abort on a remote server.
</para>
</listitem>
</varlistentry>
<varlistentry>
diff --git a/doc/src/sgml/postgres.sgml b/doc/src/sgml/postgres.sgml
index af476c82fcc..2101442c90f 100644
--- a/doc/src/sgml/postgres.sgml
+++ b/doc/src/sgml/postgres.sgml
@@ -47,11 +47,11 @@ break is not needed in a wider output rendering.
important aspects of the <productname>PostgreSQL</productname> system.
It makes no attempt to be a comprehensive treatment of the topics it covers.
</para>
<para>
- After you have successfully completed this tutorial you will want to
+ After you have successfully completed this tutorial, you will want to
read the <xref linkend="sql"/> section to gain a better understanding
of the SQL language, or <xref linkend="client-interfaces"/> for
information about developing applications with
<productname>PostgreSQL</productname>. Those who provision and
manage their own PostgreSQL installation should also read <xref linkend="admin"/>.
diff --git a/doc/src/sgml/protocol.sgml b/doc/src/sgml/protocol.sgml
index 9d755232873..39e2d1ca7a2 100644
--- a/doc/src/sgml/protocol.sgml
+++ b/doc/src/sgml/protocol.sgml
@@ -1634,11 +1634,11 @@ SELCT 1/0;<!-- this typo is intentional -->
</para>
<para>
Likewise the server expects the client to not begin
the <acronym>SSL</acronym> negotiation until it receives the server's
- single byte response to the <acronym>SSL</acronym> request. If the
+ single-byte response to the <acronym>SSL</acronym> request. If the
client begins the <acronym>SSL</acronym> negotiation immediately without
waiting for the server response to be received it can reduce connection
latency by one round-trip. However this comes at the cost of not being
able to handle the case where the server sends a negative response to the
<acronym>SSL</acronym> request. In that case instead of continuing with either GSSAPI or an
@@ -2226,11 +2226,11 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
<term><literal>CREATE_REPLICATION_SLOT</literal> <replaceable class="parameter">slot_name</replaceable> [ <literal>TEMPORARY</literal> ] { <literal>PHYSICAL</literal> | <literal>LOGICAL</literal> <replaceable class="parameter">output_plugin</replaceable> } [ ( <replaceable class="parameter">option</replaceable> [, ...] ) ]
<indexterm><primary>CREATE_REPLICATION_SLOT</primary></indexterm>
</term>
<listitem>
<para>
- Create a physical or logical replication
+ Creates a physical or logical replication
slot. See <xref linkend="streaming-replication-slots"/> for more about
replication slots.
</para>
<variablelist>
@@ -2258,11 +2258,11 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
<varlistentry>
<term><literal>TEMPORARY</literal></term>
<listitem>
<para>
- Specify that this replication slot is a temporary one. Temporary
+ Specifies that this replication slot is a temporary one. Temporary
slots are not saved to disk and are automatically dropped on error
or when the session has finished.
</para>
</listitem>
</varlistentry>
@@ -2394,11 +2394,11 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
<term><literal>ALTER_REPLICATION_SLOT</literal> <replaceable class="parameter">slot_name</replaceable> ( <replaceable class="parameter">option</replaceable> [, ...] )
<indexterm><primary>ALTER_REPLICATION_SLOT</primary></indexterm>
</term>
<listitem>
<para>
- Change the definition of a replication slot.
+ Changes the definition of a replication slot.
See <xref linkend="streaming-replication-slots"/> for more about
replication slots. This command is currently only supported for logical
replication slots.
</para>
@@ -2451,11 +2451,11 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
<term><literal>READ_REPLICATION_SLOT</literal> <replaceable class="parameter">slot_name</replaceable>
<indexterm><primary>READ_REPLICATION_SLOT</primary></indexterm>
</term>
<listitem>
<para>
- Read some information associated with a replication slot. Returns a tuple
+ Reads some information associated with a replication slot. Returns a tuple
with <literal>NULL</literal> values if the replication slot does not
exist. This command is currently only supported for physical replication
slots.
</para>
@@ -2500,11 +2500,11 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
<term><literal>START_REPLICATION</literal> [ <literal>SLOT</literal> <replaceable class="parameter">slot_name</replaceable> ] [ <literal>PHYSICAL</literal> ] <replaceable class="parameter">XXX/XXX</replaceable> [ <literal>TIMELINE</literal> <replaceable class="parameter">tli</replaceable> ]
<indexterm><primary>START_REPLICATION</primary></indexterm>
</term>
<listitem>
<para>
- Instructs server to start streaming WAL, starting at
+ Instructs the server to start streaming WAL, starting at
WAL location <replaceable class="parameter">XXX/XXX</replaceable>.
If <literal>TIMELINE</literal> option is specified,
streaming starts on timeline <replaceable class="parameter">tli</replaceable>;
otherwise, the server's current timeline is selected. The server can
reply with an error, for example if the requested section of WAL has already
@@ -2896,11 +2896,11 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
<varlistentry id="protocol-replication-start-replication-slot-logical">
<term><literal>START_REPLICATION</literal> <literal>SLOT</literal> <replaceable class="parameter">slot_name</replaceable> <literal>LOGICAL</literal> <replaceable class="parameter">XXX/XXX</replaceable> [ ( <replaceable>option_name</replaceable> [ <replaceable>option_value</replaceable> ] [, ...] ) ]</term>
<listitem>
<para>
- Instructs server to start streaming WAL for logical replication,
+ Instructs the server to start streaming WAL for logical replication,
starting at either WAL location <replaceable
class="parameter">XXX/XXX</replaceable> or the slot's
<literal>confirmed_flush_lsn</literal> (see <xref
linkend="view-pg-replication-slots"/>), whichever is greater. This
behavior makes it easier for clients to avoid updating their local LSN
@@ -2980,11 +2980,11 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
<literal>DROP_REPLICATION_SLOT</literal> <replaceable class="parameter">slot_name</replaceable> <optional> <literal>WAIT</literal> </optional>
<indexterm><primary>DROP_REPLICATION_SLOT</primary></indexterm>
</term>
<listitem>
<para>
- Drops a replication slot, freeing any reserved server-side resources.
+ Instructs the server to drop a replication slot, freeing any reserved server-side resources.
</para>
<variablelist>
<varlistentry>
<term><replaceable class="parameter">slot_name</replaceable></term>
@@ -3191,11 +3191,11 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
<varlistentry>
<term><literal>MAX_RATE</literal> <replaceable>rate</replaceable></term>
<listitem>
<para>
- Limit (throttle) the maximum amount of data transferred from server
+ Limits (throttle) the maximum amount of data transferred from server
to client per unit of time. The expected unit is kilobytes per second.
If this option is specified, the value must either be equal to zero
or it must fall within the range from 32 kB through 1 GB (inclusive).
If zero is passed or the option is not specified, no restriction is
imposed on the transfer.
@@ -3205,11 +3205,11 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
<varlistentry>
<term><literal>TABLESPACE_MAP [ <replaceable class="parameter">boolean</replaceable> ]</literal></term>
<listitem>
<para>
- If true, include information about symbolic links present in the
+ If true, includes information about symbolic links present in the
directory <filename>pg_tblspc</filename> in a file named
<filename>tablespace_map</filename>. The tablespace map file includes
each symbolic link name as it exists in the directory
<filename>pg_tblspc/</filename> and the full path of that symbolic link.
The default is false.
@@ -3255,11 +3255,11 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
Specifies the checksum algorithm that should be applied to each file included
in the backup manifest. Currently, the available
algorithms are <literal>NONE</literal>, <literal>CRC32C</literal>,
<literal>SHA224</literal>, <literal>SHA256</literal>,
<literal>SHA384</literal>, and <literal>SHA512</literal>.
- The default is <literal>CRC32C</literal>.
+ The defv2ault is <literal>CRC32C</literal>.
</para>
</listitem>
</varlistentry>
<varlistentry>
diff --git a/doc/src/sgml/ref/pg_recvlogical.sgml b/doc/src/sgml/ref/pg_recvlogical.sgml
index 263ebdeeab4..2a0de0cfb63 100644
--- a/doc/src/sgml/ref/pg_recvlogical.sgml
+++ b/doc/src/sgml/ref/pg_recvlogical.sgml
@@ -82,11 +82,11 @@ PostgreSQL documentation
<option>--plugin</option>, for the database specified
by <option>--dbname</option>.
</para>
<para>
- The <option>--slot</option> and <option>--dbname</option> are required
+ The <option>--slot</option> and <option>--dbname</option> options are required
for this action.
</para>
<para>
The <option>--enable-two-phase</option> and <option>--enable-failover</option>
@@ -102,11 +102,11 @@ PostgreSQL documentation
Drop the replication slot with the name specified
by <option>--slot</option>, then exit.
</para>
<para>
- The <option>--slot</option> is required for this action.
+ The <option>--slot</option> option is required for this action.
</para>
</listitem>
</varlistentry>
<varlistentry>
@@ -119,12 +119,12 @@ PostgreSQL documentation
or disconnect, retry in a loop unless
<option>--no-loop</option> is specified.
</para>
<para>
- The <option>--slot</option> and <option>--dbname</option>,
- <option>--file</option> are required for this action.
+ The <option>--slot</option>, <option>--dbname</option>, and
+ <option>--file</option> options are required for this action.
</para>
<para>
The stream format is determined by the output plugin specified when
the slot was created.
diff --git a/doc/src/sgml/ref/pgbench.sgml b/doc/src/sgml/ref/pgbench.sgml
index a5edf612443..8c92be6eb21 100644
--- a/doc/src/sgml/ref/pgbench.sgml
+++ b/doc/src/sgml/ref/pgbench.sgml
@@ -2823,11 +2823,11 @@ statement latencies in milliseconds, failures and retries:
<para>
Errors when the thread manages its clients (e.g. the client could not
start a connection to the database server / the socket for connecting
the client to the database server has become invalid). In such cases
all clients of this thread stop while other threads continue to work.
- However, <option>--exit-on-abort</option> is specified, all of the
+ However, if <option>--exit-on-abort</option> is specified, all of the
threads stop immediately in this case.
</para>
</listitem>
<listitem>
<para>
diff --git a/doc/src/sgml/regress.sgml b/doc/src/sgml/regress.sgml
index 8838fe7f022..6812e3f11e0 100644
--- a/doc/src/sgml/regress.sgml
+++ b/doc/src/sgml/regress.sgml
@@ -252,11 +252,11 @@ make check-world -j8 >/dev/null
</para>
<para>
Some test suites are not run by default, either because they are not secure
to run on a multiuser system, because they require special software or
- because they are resource intensive. You can decide which test suites to
+ because they are resource-intensive. You can decide which test suites to
run additionally by setting the <command>make</command> or environment
variable <varname>PG_TEST_EXTRA</varname> to a whitespace-separated list,
for example:
<programlisting>
make check-world PG_TEST_EXTRA='kerberos ldap ssl load_balance libpq_encryption'
@@ -323,11 +323,11 @@ make check-world PG_TEST_EXTRA='kerberos ldap ssl load_balance libpq_encryption'
<para>
Runs an additional test suite in
<filename>src/bin/pg_upgrade/t/002_pg_upgrade.pl</filename> which
cycles the regression database through <command>pg_dump</command>/
<command>pg_restore</command>. Not enabled by default because it
- is resource intensive.
+ is resource-intensive.
</para>
</listitem>
</varlistentry>
<varlistentry>
@@ -354,21 +354,21 @@ make check-world PG_TEST_EXTRA='kerberos ldap ssl load_balance libpq_encryption'
<term><literal>wal_consistency_checking</literal></term>
<listitem>
<para>
Uses <literal>wal_consistency_checking=all</literal> while running
certain tests under <filename>src/test/recovery</filename>. Not
- enabled by default because it is resource intensive.
+ enabled by default because it is resource-intensive.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>xid_wraparound</literal></term>
<listitem>
<para>
Runs the test suite under <filename>src/test/modules/xid_wraparound</filename>.
- Not enabled by default because it is resource intensive.
+ Not enabled by default because it is resource-intensive.
</para>
</listitem>
</varlistentry>
</variablelist>
diff --git a/doc/src/sgml/system-views.sgml b/doc/src/sgml/system-views.sgml
index 7971498fe75..0e623e7fb86 100644
--- a/doc/src/sgml/system-views.sgml
+++ b/doc/src/sgml/system-views.sgml
@@ -51,11 +51,11 @@
</thead>
<tbody>
<row>
<entry><link linkend="view-pg-aios"><structname>pg_aios</structname></link></entry>
- <entry>In-use asynchronous IO handles</entry>
+ <entry>in-use asynchronous IO handles</entry>
</row>
<row>
<entry><link linkend="view-pg-available-extensions"><structname>pg_available_extensions</structname></link></entry>
<entry>available extensions</entry>
diff --git a/doc/src/sgml/xfunc.sgml b/doc/src/sgml/xfunc.sgml
index 04bf919b343..ad1751a7dbf 100644
--- a/doc/src/sgml/xfunc.sgml
+++ b/doc/src/sgml/xfunc.sgml
@@ -2397,11 +2397,11 @@ PG_FUNCTION_INFO_V1(funcname);
<para>
To call another version-1 function, you can use
<function>DirectFunctionCall<replaceable>n</replaceable>(func,
arg1, ..., argn)</function>. This is particularly useful when you want
- to call functions defined in the standard internal library, by using an
+ to call functions defined in the standard internal function library by using an
interface similar to their SQL signature.
</para>
<para>
These convenience functions and similar ones can be found
@@ -3938,11 +3938,11 @@ extern bool InjectionPointDetach(const char *name);
<filename>src/test/modules/injection_points</filename> in the PostgreSQL
source tree.
</para>
<para>
- Enabling injections points requires
+ Enabling injection points requires
<option>--enable-injection-points</option> with
<command>configure</command> or <option>-Dinjection_points=true</option>
with <application>Meson</application>.
</para>
</sect2>
@@ -3955,11 +3955,11 @@ extern bool InjectionPointDetach(const char *name);
of cumulative statistics registered in the
<link linkend="monitoring-stats-setup">Cumulative Statistics System</link>.
</para>
<para>
- First, define a <literal>PgStat_KindInfo</literal> that includes all
+ First, define <literal>PgStat_KindInfo</literal> that includes all
the information related to the custom type registered. For example:
<programlisting>
static const PgStat_KindInfo custom_stats = {
.name = "custom_stats",
.fixed_amount = false,
^ permalink raw reply [nested|flat] 23+ messages in thread
* Re: Documentation improvement patch
2025-09-10 07:54 Documentation improvement patch Oleg <o.sibiryakov@postgrespro.ru>
2025-10-10 07:15 ` Re: Documentation improvement patch Daniel Gustafsson <daniel@yesql.se>
2025-10-13 10:51 ` Re: Documentation improvement patch Oleg <o.sibiryakov@postgrespro.ru>
2025-10-22 08:02 ` Re: Documentation improvement patch Daniel Gustafsson <daniel@yesql.se>
2025-10-25 19:01 ` Re: Documentation improvement patch Oleg <o.sibiryakov@postgrespro.ru>
@ 2025-10-30 10:15 ` Peter Eisentraut <peter@eisentraut.org>
2025-11-14 09:04 ` Re: Documentation improvement patch Daniel Gustafsson <daniel@yesql.se>
0 siblings, 1 reply; 23+ messages in thread
From: Peter Eisentraut @ 2025-10-30 10:15 UTC (permalink / raw)
To: Oleg <o.sibiryakov@postgrespro.ru>; Daniel Gustafsson <daniel@yesql.se>; +Cc: pgsql-docs@lists.postgresql.org
On 25.10.25 21:01, Oleg wrote:
> Dear Daniel,
>
> Thank you for your prompt feedback.
>
> Attached, please find the updated documentation patch, which
> incorporates your suggestions from both the first and second rounds of
> review.
<term><literal>ALTER_REPLICATION_SLOT</literal> <replaceable
class="parameter">slot_name</replaceable> ( <replaceable
class="parameter">option</replaceable> [, ...] )
<indexterm><primary>ALTER_REPLICATION_SLOT</primary></indexterm>
</term>
<listitem>
<para>
- Change the definition of a replication slot.
+ Changes the definition of a replication slot.
I think these are intentionally written in imperative style. Compare
the synopses of the main SQL commands: "change the definition of a
domain" etc.
- First, define a <literal>PgStat_KindInfo</literal> that includes all
+ First, define <literal>PgStat_KindInfo</literal> that includes all
I think this change is incorrect. You are being asked to define an
instance of PgStat_KindInfo, not PgStat_KindInfo itself (which already
exists).
The remaining changes look ok to me.
^ permalink raw reply [nested|flat] 23+ messages in thread
* Re: Documentation improvement patch
2025-09-10 07:54 Documentation improvement patch Oleg <o.sibiryakov@postgrespro.ru>
2025-10-10 07:15 ` Re: Documentation improvement patch Daniel Gustafsson <daniel@yesql.se>
2025-10-13 10:51 ` Re: Documentation improvement patch Oleg <o.sibiryakov@postgrespro.ru>
2025-10-22 08:02 ` Re: Documentation improvement patch Daniel Gustafsson <daniel@yesql.se>
2025-10-25 19:01 ` Re: Documentation improvement patch Oleg <o.sibiryakov@postgrespro.ru>
2025-10-30 10:15 ` Re: Documentation improvement patch Peter Eisentraut <peter@eisentraut.org>
@ 2025-11-14 09:04 ` Daniel Gustafsson <daniel@yesql.se>
2025-11-19 11:02 ` Re: Documentation improvement patch Peter Eisentraut <peter@eisentraut.org>
0 siblings, 1 reply; 23+ messages in thread
From: Daniel Gustafsson @ 2025-11-14 09:04 UTC (permalink / raw)
To: Peter Eisentraut <peter@eisentraut.org>; +Cc: Oleg <o.sibiryakov@postgrespro.ru>; pgsql-docs@lists.postgresql.org
> On 30 Oct 2025, at 11:15, Peter Eisentraut <peter@eisentraut.org> wrote:
> - Change the definition of a replication slot.
> + Changes the definition of a replication slot.
>
> I think these are intentionally written in imperative style. Compare the synopses of the main SQL commands: "change the definition of a domain" etc.
I agree, I too think these are intentionally written like this. The document
isn't entirely consistent and does mix style quite a bit but I don't think
these changes change the needle enough to make.
Attached is a v3 with the remaining changes and a stab at commit message that I
think we should go ahead with.
--
Daniel Gustafsson
Attachments:
[application/octet-stream] v3-0001-doc-Assorted-documentation-improvements.patch (12.2K, ../../93538952-E9CC-492C-9BDD-9249AD4C6B91@yesql.se/2-v3-0001-doc-Assorted-documentation-improvements.patch)
download | inline diff:
From a641eb6ed524d1af9e3b6fb9cc8e954a3e4831e0 Mon Sep 17 00:00:00 2001
From: Daniel Gustafsson <dgustafsson@postgresql.org>
Date: Fri, 14 Nov 2025 09:46:24 +0100
Subject: [PATCH v3] doc: Assorted documentation improvements
A set of wording improvements and spelling fixes.
Author: Oleg Sibiryakov <o.sibiryakov@postgrespro.ru>
Reviewed-by: Daniel Gustafsson <daniel@yesql.se>
Reviewed-by: Peter Eisentraut <peter@eisentraut.org>
Discussion: https://postgr.es/m/e62bedb5-c26f-4d37-b4ed-ce9b55f1e980@postgrespro.r
---
doc/src/sgml/config.sgml | 6 +++---
doc/src/sgml/installation.sgml | 2 +-
doc/src/sgml/postgres-fdw.sgml | 2 +-
doc/src/sgml/postgres.sgml | 2 +-
doc/src/sgml/protocol.sgml | 10 +++++-----
doc/src/sgml/ref/pg_recvlogical.sgml | 8 ++++----
doc/src/sgml/ref/pgbench.sgml | 2 +-
doc/src/sgml/regress.sgml | 8 ++++----
doc/src/sgml/system-views.sgml | 2 +-
doc/src/sgml/xfunc.sgml | 4 ++--
10 files changed, 23 insertions(+), 23 deletions(-)
diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml
index d7e48f61905..21f49f4764d 100644
--- a/doc/src/sgml/config.sgml
+++ b/doc/src/sgml/config.sgml
@@ -1234,7 +1234,7 @@ include_dir 'conf.d'
</term>
<listitem>
<para>
- The library/libraries to use for validating OAuth connection tokens. If
+ Sets the library/libraries to use for validating OAuth connection tokens. If
only one validator library is provided, it will be used by default for
any OAuth connections; otherwise, all
<link linkend="auth-oauth"><literal>oauth</literal> HBA entries</link>
@@ -1400,7 +1400,7 @@ include_dir 'conf.d'
<para>
Specifies a list of cipher suites that are allowed by connections using
<acronym>TLS</acronym> version 1.3. Multiple cipher suites can be
- specified by using a colon separated list. If left blank, the default
+ specified by using a colon-separated list. If left blank, the default
set of cipher suites in <productname>OpenSSL</productname> will be used.
</para>
@@ -2436,7 +2436,7 @@ include_dir 'conf.d'
</term>
<listitem>
<para>
- Sets the maximum number of open files each server subprocess is
+ Sets the maximum number of files each server subprocess is
allowed to open simultaneously; files already opened in the
postmaster are not counted toward this limit. The default is one
thousand files.
diff --git a/doc/src/sgml/installation.sgml b/doc/src/sgml/installation.sgml
index 593202f4fb2..fe8d73e1f8c 100644
--- a/doc/src/sgml/installation.sgml
+++ b/doc/src/sgml/installation.sgml
@@ -3170,7 +3170,7 @@ ninja install
<para>
Enable additional test suites, which are not run by default because
they are not secure to run on a multiuser system, require special
- software to run, or are resource intensive. The argument is a
+ software to run, or are resource-intensive. The argument is a
whitespace-separated list of tests to enable. See
<xref linkend="regress-additional"/> for details. If the
<envar>PG_TEST_EXTRA</envar> environment variable is set when the
diff --git a/doc/src/sgml/postgres-fdw.sgml b/doc/src/sgml/postgres-fdw.sgml
index 781a01067f7..9b032fbf675 100644
--- a/doc/src/sgml/postgres-fdw.sgml
+++ b/doc/src/sgml/postgres-fdw.sgml
@@ -1226,7 +1226,7 @@ postgres=# SELECT postgres_fdw_disconnect_all();
<term><literal>PostgresFdwCleanupResult</literal></term>
<listitem>
<para>
- Waiting for transaction abort on remote server.
+ Waiting for transaction abort on a remote server.
</para>
</listitem>
</varlistentry>
diff --git a/doc/src/sgml/postgres.sgml b/doc/src/sgml/postgres.sgml
index af476c82fcc..2101442c90f 100644
--- a/doc/src/sgml/postgres.sgml
+++ b/doc/src/sgml/postgres.sgml
@@ -49,7 +49,7 @@ break is not needed in a wider output rendering.
</para>
<para>
- After you have successfully completed this tutorial you will want to
+ After you have successfully completed this tutorial, you will want to
read the <xref linkend="sql"/> section to gain a better understanding
of the SQL language, or <xref linkend="client-interfaces"/> for
information about developing applications with
diff --git a/doc/src/sgml/protocol.sgml b/doc/src/sgml/protocol.sgml
index d1b9af11b07..aa3c5130d94 100644
--- a/doc/src/sgml/protocol.sgml
+++ b/doc/src/sgml/protocol.sgml
@@ -1636,7 +1636,7 @@ SELCT 1/0;<!-- this typo is intentional -->
<para>
Likewise the server expects the client to not begin
the <acronym>SSL</acronym> negotiation until it receives the server's
- single byte response to the <acronym>SSL</acronym> request. If the
+ single-byte response to the <acronym>SSL</acronym> request. If the
client begins the <acronym>SSL</acronym> negotiation immediately without
waiting for the server response to be received it can reduce connection
latency by one round-trip. However this comes at the cost of not being
@@ -2228,7 +2228,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
</term>
<listitem>
<para>
- Create a physical or logical replication
+ Creates a physical or logical replication
slot. See <xref linkend="streaming-replication-slots"/> for more about
replication slots.
</para>
@@ -2502,7 +2502,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
</term>
<listitem>
<para>
- Instructs server to start streaming WAL, starting at
+ Instructs the server to start streaming WAL, starting at
WAL location <replaceable class="parameter">XXX/XXX</replaceable>.
If <literal>TIMELINE</literal> option is specified,
streaming starts on timeline <replaceable class="parameter">tli</replaceable>;
@@ -2898,7 +2898,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
<term><literal>START_REPLICATION</literal> <literal>SLOT</literal> <replaceable class="parameter">slot_name</replaceable> <literal>LOGICAL</literal> <replaceable class="parameter">XXX/XXX</replaceable> [ ( <replaceable>option_name</replaceable> [ <replaceable>option_value</replaceable> ] [, ...] ) ]</term>
<listitem>
<para>
- Instructs server to start streaming WAL for logical replication,
+ Instructs the server to start streaming WAL for logical replication,
starting at either WAL location <replaceable
class="parameter">XXX/XXX</replaceable> or the slot's
<literal>confirmed_flush_lsn</literal> (see <xref
@@ -2982,7 +2982,7 @@ psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"
</term>
<listitem>
<para>
- Drops a replication slot, freeing any reserved server-side resources.
+ Instructs the server to drop a replication slot, freeing any reserved server-side resources.
</para>
<variablelist>
diff --git a/doc/src/sgml/ref/pg_recvlogical.sgml b/doc/src/sgml/ref/pg_recvlogical.sgml
index 263ebdeeab4..2a0de0cfb63 100644
--- a/doc/src/sgml/ref/pg_recvlogical.sgml
+++ b/doc/src/sgml/ref/pg_recvlogical.sgml
@@ -84,7 +84,7 @@ PostgreSQL documentation
</para>
<para>
- The <option>--slot</option> and <option>--dbname</option> are required
+ The <option>--slot</option> and <option>--dbname</option> options are required
for this action.
</para>
@@ -104,7 +104,7 @@ PostgreSQL documentation
</para>
<para>
- The <option>--slot</option> is required for this action.
+ The <option>--slot</option> option is required for this action.
</para>
</listitem>
</varlistentry>
@@ -121,8 +121,8 @@ PostgreSQL documentation
</para>
<para>
- The <option>--slot</option> and <option>--dbname</option>,
- <option>--file</option> are required for this action.
+ The <option>--slot</option>, <option>--dbname</option>, and
+ <option>--file</option> options are required for this action.
</para>
<para>
diff --git a/doc/src/sgml/ref/pgbench.sgml b/doc/src/sgml/ref/pgbench.sgml
index ecfc3d2f2b7..2e401d1ceb8 100644
--- a/doc/src/sgml/ref/pgbench.sgml
+++ b/doc/src/sgml/ref/pgbench.sgml
@@ -2858,7 +2858,7 @@ statement latencies in milliseconds, failures and retries:
start a connection to the database server / the socket for connecting
the client to the database server has become invalid). In such cases
all clients of this thread stop while other threads continue to work.
- However, <option>--exit-on-abort</option> is specified, all of the
+ However, if <option>--exit-on-abort</option> is specified, all of the
threads stop immediately in this case.
</para>
</listitem>
diff --git a/doc/src/sgml/regress.sgml b/doc/src/sgml/regress.sgml
index 8838fe7f022..6812e3f11e0 100644
--- a/doc/src/sgml/regress.sgml
+++ b/doc/src/sgml/regress.sgml
@@ -254,7 +254,7 @@ make check-world -j8 >/dev/null
<para>
Some test suites are not run by default, either because they are not secure
to run on a multiuser system, because they require special software or
- because they are resource intensive. You can decide which test suites to
+ because they are resource-intensive. You can decide which test suites to
run additionally by setting the <command>make</command> or environment
variable <varname>PG_TEST_EXTRA</varname> to a whitespace-separated list,
for example:
@@ -325,7 +325,7 @@ make check-world PG_TEST_EXTRA='kerberos ldap ssl load_balance libpq_encryption'
<filename>src/bin/pg_upgrade/t/002_pg_upgrade.pl</filename> which
cycles the regression database through <command>pg_dump</command>/
<command>pg_restore</command>. Not enabled by default because it
- is resource intensive.
+ is resource-intensive.
</para>
</listitem>
</varlistentry>
@@ -356,7 +356,7 @@ make check-world PG_TEST_EXTRA='kerberos ldap ssl load_balance libpq_encryption'
<para>
Uses <literal>wal_consistency_checking=all</literal> while running
certain tests under <filename>src/test/recovery</filename>. Not
- enabled by default because it is resource intensive.
+ enabled by default because it is resource-intensive.
</para>
</listitem>
</varlistentry>
@@ -366,7 +366,7 @@ make check-world PG_TEST_EXTRA='kerberos ldap ssl load_balance libpq_encryption'
<listitem>
<para>
Runs the test suite under <filename>src/test/modules/xid_wraparound</filename>.
- Not enabled by default because it is resource intensive.
+ Not enabled by default because it is resource-intensive.
</para>
</listitem>
</varlistentry>
diff --git a/doc/src/sgml/system-views.sgml b/doc/src/sgml/system-views.sgml
index 7971498fe75..0e623e7fb86 100644
--- a/doc/src/sgml/system-views.sgml
+++ b/doc/src/sgml/system-views.sgml
@@ -53,7 +53,7 @@
<tbody>
<row>
<entry><link linkend="view-pg-aios"><structname>pg_aios</structname></link></entry>
- <entry>In-use asynchronous IO handles</entry>
+ <entry>in-use asynchronous IO handles</entry>
</row>
<row>
diff --git a/doc/src/sgml/xfunc.sgml b/doc/src/sgml/xfunc.sgml
index 7dcd7d32329..55a99c0ff34 100644
--- a/doc/src/sgml/xfunc.sgml
+++ b/doc/src/sgml/xfunc.sgml
@@ -2399,7 +2399,7 @@ PG_FUNCTION_INFO_V1(funcname);
To call another version-1 function, you can use
<function>DirectFunctionCall<replaceable>n</replaceable>(func,
arg1, ..., argn)</function>. This is particularly useful when you want
- to call functions defined in the standard internal library, by using an
+ to call functions defined in the standard internal function library by using an
interface similar to their SQL signature.
</para>
@@ -3940,7 +3940,7 @@ extern bool InjectionPointDetach(const char *name);
</para>
<para>
- Enabling injections points requires
+ Enabling injection points requires
<option>--enable-injection-points</option> with
<command>configure</command> or <option>-Dinjection_points=true</option>
with <application>Meson</application>.
--
2.39.3 (Apple Git-146)
=
^ permalink raw reply [nested|flat] 23+ messages in thread
* Re: Documentation improvement patch
2025-09-10 07:54 Documentation improvement patch Oleg <o.sibiryakov@postgrespro.ru>
2025-10-10 07:15 ` Re: Documentation improvement patch Daniel Gustafsson <daniel@yesql.se>
2025-10-13 10:51 ` Re: Documentation improvement patch Oleg <o.sibiryakov@postgrespro.ru>
2025-10-22 08:02 ` Re: Documentation improvement patch Daniel Gustafsson <daniel@yesql.se>
2025-10-25 19:01 ` Re: Documentation improvement patch Oleg <o.sibiryakov@postgrespro.ru>
2025-10-30 10:15 ` Re: Documentation improvement patch Peter Eisentraut <peter@eisentraut.org>
2025-11-14 09:04 ` Re: Documentation improvement patch Daniel Gustafsson <daniel@yesql.se>
@ 2025-11-19 11:02 ` Peter Eisentraut <peter@eisentraut.org>
2025-11-19 14:14 ` Re: Documentation improvement patch Daniel Gustafsson <daniel@yesql.se>
0 siblings, 1 reply; 23+ messages in thread
From: Peter Eisentraut @ 2025-11-19 11:02 UTC (permalink / raw)
To: Daniel Gustafsson <daniel@yesql.se>; +Cc: Oleg <o.sibiryakov@postgrespro.ru>; pgsql-docs@lists.postgresql.org
On 14.11.25 10:04, Daniel Gustafsson wrote:
>> On 30 Oct 2025, at 11:15, Peter Eisentraut <peter@eisentraut.org> wrote:
>
>> - Change the definition of a replication slot.
>> + Changes the definition of a replication slot.
>>
>> I think these are intentionally written in imperative style. Compare the synopses of the main SQL commands: "change the definition of a domain" etc.
>
> I agree, I too think these are intentionally written like this. The document
> isn't entirely consistent and does mix style quite a bit but I don't think
> these changes change the needle enough to make.
The following changes are left in your patch that should not be changed
per the above discussion (all in doc/src/sgml/protocol.sgml):
- Create a physical or logical replication
+ Creates a physical or logical replication
- Instructs server to start streaming WAL, starting at
+ Instructs the server to start streaming WAL, starting at
- Instructs server to start streaming WAL for logical replication,
+ Instructs the server to start streaming WAL for logical replication,
Separately, maybe this could be improved further:
- Sets the maximum number of open files each server subprocess is
+ Sets the maximum number of files each server subprocess is
allowed to open simultaneously; files already opened in the
I think it would be more correct to say something like "... number of
files each server subprocess is allowed to have open simultaneously ..."
(not how many open actions are happening concurrently).
^ permalink raw reply [nested|flat] 23+ messages in thread
* Re: Documentation improvement patch
2025-09-10 07:54 Documentation improvement patch Oleg <o.sibiryakov@postgrespro.ru>
2025-10-10 07:15 ` Re: Documentation improvement patch Daniel Gustafsson <daniel@yesql.se>
2025-10-13 10:51 ` Re: Documentation improvement patch Oleg <o.sibiryakov@postgrespro.ru>
2025-10-22 08:02 ` Re: Documentation improvement patch Daniel Gustafsson <daniel@yesql.se>
2025-10-25 19:01 ` Re: Documentation improvement patch Oleg <o.sibiryakov@postgrespro.ru>
2025-10-30 10:15 ` Re: Documentation improvement patch Peter Eisentraut <peter@eisentraut.org>
2025-11-14 09:04 ` Re: Documentation improvement patch Daniel Gustafsson <daniel@yesql.se>
2025-11-19 11:02 ` Re: Documentation improvement patch Peter Eisentraut <peter@eisentraut.org>
@ 2025-11-19 14:14 ` Daniel Gustafsson <daniel@yesql.se>
2025-11-25 07:08 ` Re: Documentation improvement patch Oleg <o.sibiryakov@postgrespro.ru>
0 siblings, 1 reply; 23+ messages in thread
From: Daniel Gustafsson @ 2025-11-19 14:14 UTC (permalink / raw)
To: Peter Eisentraut <peter@eisentraut.org>; +Cc: Oleg <o.sibiryakov@postgrespro.ru>; pgsql-docs@lists.postgresql.org
> On 19 Nov 2025, at 12:02, Peter Eisentraut <peter@eisentraut.org> wrote:
> The following changes are left in your patch that should not be changed per the above discussion (all in doc/src/sgml/protocol.sgml):
I did consider these to be separate but re-reading I agree that they should be
removed.
> Separately, maybe this could be improved further:
>
> - Sets the maximum number of open files each server subprocess is
> + Sets the maximum number of files each server subprocess is
> allowed to open simultaneously; files already opened in the
>
> I think it would be more correct to say something like "... number of files each server subprocess is allowed to have open simultaneously ..." (not how many open actions are happening concurrently).
I wonder if the original intent was to write "Sets the maximum number of open
files each server subprocess is allowed to have simultaneously;"? That being
said, your suggestion is better so I'll go with that.
I will push the patch with the above changes a bit later today.
--
Daniel Gustafsson
^ permalink raw reply [nested|flat] 23+ messages in thread
* Re: Documentation improvement patch
2025-09-10 07:54 Documentation improvement patch Oleg <o.sibiryakov@postgrespro.ru>
2025-10-10 07:15 ` Re: Documentation improvement patch Daniel Gustafsson <daniel@yesql.se>
2025-10-13 10:51 ` Re: Documentation improvement patch Oleg <o.sibiryakov@postgrespro.ru>
2025-10-22 08:02 ` Re: Documentation improvement patch Daniel Gustafsson <daniel@yesql.se>
2025-10-25 19:01 ` Re: Documentation improvement patch Oleg <o.sibiryakov@postgrespro.ru>
2025-10-30 10:15 ` Re: Documentation improvement patch Peter Eisentraut <peter@eisentraut.org>
2025-11-14 09:04 ` Re: Documentation improvement patch Daniel Gustafsson <daniel@yesql.se>
2025-11-19 11:02 ` Re: Documentation improvement patch Peter Eisentraut <peter@eisentraut.org>
2025-11-19 14:14 ` Re: Documentation improvement patch Daniel Gustafsson <daniel@yesql.se>
@ 2025-11-25 07:08 ` Oleg <o.sibiryakov@postgrespro.ru>
0 siblings, 0 replies; 23+ messages in thread
From: Oleg @ 2025-11-25 07:08 UTC (permalink / raw)
To: Daniel Gustafsson <daniel@yesql.se>; Peter Eisentraut <peter@eisentraut.org>; +Cc: pgsql-docs@lists.postgresql.org
Daniel, Peter, thank you for the thorough review of the patch.
--
Oleg Sibiryakov
On 19.11.2025 17:14, Daniel Gustafsson wrote:
>> On 19 Nov 2025, at 12:02, Peter Eisentraut <peter@eisentraut.org> wrote:
>> The following changes are left in your patch that should not be changed per the above discussion (all in doc/src/sgml/protocol.sgml):
> I did consider these to be separate but re-reading I agree that they should be
> removed.
>
>> Separately, maybe this could be improved further:
>>
>> - Sets the maximum number of open files each server subprocess is
>> + Sets the maximum number of files each server subprocess is
>> allowed to open simultaneously; files already opened in the
>>
>> I think it would be more correct to say something like "... number of files each server subprocess is allowed to have open simultaneously ..." (not how many open actions are happening concurrently).
> I wonder if the original intent was to write "Sets the maximum number of open
> files each server subprocess is allowed to have simultaneously;"? That being
> said, your suggestion is better so I'll go with that.
>
> I will push the patch with the above changes a bit later today.
>
> --
> Daniel Gustafsson
>
>
>
^ permalink raw reply [nested|flat] 23+ messages in thread
end of thread, other threads:[~2025-11-25 07:08 UTC | newest]
Thread overview: 23+ messages (download: mbox mbox.gz follow: Atom feed)
-- links below jump to the message on this page --
2024-09-05 09:33 Documentation improvement patch Oleg Sibiryakov <o.sibiryakov@postgrespro.ru>
2024-09-06 13:20 ` Daniel Gustafsson <daniel@yesql.se>
2024-09-10 11:46 ` Oleg Sibiryakov <o.sibiryakov@postgrespro.ru>
2024-09-10 13:02 ` Daniel Gustafsson <daniel@yesql.se>
2024-09-11 09:53 ` Peter Eisentraut <peter@eisentraut.org>
2024-09-13 10:50 ` Oleg Sibiryakov <o.sibiryakov@postgrespro.ru>
2024-10-01 08:04 ` Oleg Sibiryakov <o.sibiryakov@postgrespro.ru>
2024-10-01 08:59 ` Daniel Gustafsson <daniel@yesql.se>
2024-10-02 08:09 ` Oleg Sibiryakov <o.sibiryakov@postgrespro.ru>
2024-10-02 12:58 ` Daniel Gustafsson <daniel@yesql.se>
2024-10-07 08:54 ` Oleg Sibiryakov <o.sibiryakov@postgrespro.ru>
2025-09-10 07:54 Documentation improvement patch Oleg <o.sibiryakov@postgrespro.ru>
2025-10-10 06:38 ` Oleg <o.sibiryakov@postgrespro.ru>
2025-10-10 07:15 ` Daniel Gustafsson <daniel@yesql.se>
2025-10-13 10:51 ` Oleg <o.sibiryakov@postgrespro.ru>
2025-10-22 02:41 ` Oleg <o.sibiryakov@postgrespro.ru>
2025-10-22 08:02 ` Daniel Gustafsson <daniel@yesql.se>
2025-10-25 19:01 ` Oleg <o.sibiryakov@postgrespro.ru>
2025-10-30 10:15 ` Peter Eisentraut <peter@eisentraut.org>
2025-11-14 09:04 ` Daniel Gustafsson <daniel@yesql.se>
2025-11-19 11:02 ` Peter Eisentraut <peter@eisentraut.org>
2025-11-19 14:14 ` Daniel Gustafsson <daniel@yesql.se>
2025-11-25 07:08 ` Oleg <o.sibiryakov@postgrespro.ru>
This inbox is served by agora; see mirroring instructions
for how to clone and mirror all data and code used for this inbox