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