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.
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
