pg.ddx.io pgsql-docs@postgresql.org mailing list archive
help / color / mirror / Atom feedmisc doc fixes for REL_12_STABLE
4+ messages / 2 participants
[nested] [flat]
Commits from this thread:
2019-07-13 170d11b8e7 de14e54d7b Fix and improve several places in the docs
* misc doc fixes for REL_12_STABLE
@ 2019-07-11 14:49 Liudmila Mantrova <l.mantrova@postgrespro.ru>
2019-07-12 04:44 ` Re: misc doc fixes for REL_12_STABLE Michael Paquier <michael@paquier.xyz>
0 siblings, 1 reply; 4+ messages in thread
From: Liudmila Mantrova @ 2019-07-11 14:49 UTC (permalink / raw)
To: pgsql-docs@lists.postgresql.org
Hi,
Please consider a patch that fixes some trivial issues in new doc
fragments (a couple of typos/ambiguities and some tags that affect
translation).
--
Liudmila Mantrova
Technical writer at Postgres Professional: http://www.postgrespro.com
The Russian Postgres Company
Attachments:
fix-doc-inconsistencies.patch (text/x-patch, 9.3K) download
diff --git a/doc/src/sgml/backup.sgml b/doc/src/sgml/backup.sgml
index 9d4c000..2fdbcb4 100644
--- a/doc/src/sgml/backup.sgml
+++ b/doc/src/sgml/backup.sgml
@@ -962,10 +962,10 @@ SELECT * FROM pg_stop_backup(false, true);
The process for an exclusive backup is mostly the same as for a
non-exclusive one, but it differs in a few key steps. This type of
backup can only be taken on a primary and does not allow concurrent
- backups. Moreover, because it writes a backup_label file on the
- master, it can cause the master to fail to restart automatically after
- a crash. On the other hand, the erroneous removal of a backup_label
- file from a backup or standby is a common mistake which can result
+ backups. Moreover, because it creates a backup label file, as
+ described below, it can block automatic restart of the master server
+ after a crash. On the other hand, the erroneous removal of this
+ file from a backup or standby is a common mistake, which can result
in serious data corruption. If it is necessary to use this method,
the following steps may be used.
</para>
@@ -1025,10 +1025,10 @@ SELECT pg_start_backup('label', true);
</para>
<para>
As noted above, if the server crashes during the backup it may not be
- possible to restart until the <literal>backup_label</literal> file has
+ possible to restart until the <filename>backup_label</filename> file has
been manually deleted from the <envar>PGDATA</envar> directory. Note
that it is very important to never remove the
- <literal>backup_label</literal> file when restoring a backup, because
+ <filename>backup_label</filename> file when restoring a backup, because
this will result in corruption. Confusion about when it is appropriate
to remove this file is a common cause of data corruption when using this
method; be very certain that you remove the file only on an existing
@@ -1075,7 +1075,7 @@ SELECT pg_stop_backup();
lack of disk space, failure to call <function>pg_stop_backup</function>
will leave the server in backup mode indefinitely, causing future backups
to fail and increasing the risk of a restart failure during the time that
- <literal>backup_label</literal> exists.
+ <filename>backup_label</filename> exists.
</para>
</listitem>
</orderedlist>
diff --git a/doc/src/sgml/biblio.sgml b/doc/src/sgml/biblio.sgml
index f06305d..bf3aebd 100644
--- a/doc/src/sgml/biblio.sgml
+++ b/doc/src/sgml/biblio.sgml
@@ -137,14 +137,11 @@
</biblioentry>
<biblioentry id="sqltr-19075-6">
- <title>SQL Technical Report</title>
+ <title><ulink url="http://standards.iso.org/ittf/PubliclyAvailableStandards/c067367_ISO_IEC_TR_19075-6_2017.zip">SQL Technical Report</ulink></title>
<subtitle>Part 6: SQL support for JavaScript Object
Notation (JSON)</subtitle>
- <edition>First Edition.</edition>
- <biblioid>
- <ulink url="http://standards.iso.org/ittf/PubliclyAvailableStandards/c067367_ISO_IEC_TR_19075-6_2017.zip"></ulink>.
- </biblioid>
- <pubdate>2017.</pubdate>
+ <edition>First Edition</edition>
+ <pubdate>2017</pubdate>
</biblioentry>
</bibliodiv>
diff --git a/doc/src/sgml/ref/alter_foreign_table.sgml b/doc/src/sgml/ref/alter_foreign_table.sgml
index b27eb6f..0f11897 100644
--- a/doc/src/sgml/ref/alter_foreign_table.sgml
+++ b/doc/src/sgml/ref/alter_foreign_table.sgml
@@ -227,8 +227,8 @@ ALTER FOREIGN TABLE [ IF EXISTS ] <replaceable class="parameter">name</replaceab
<listitem>
<para>
Backward compatibility syntax for removing the <literal>oid</literal>
- system column. As oid system columns cannot be added anymore, this never
- has an effect.
+ system column. As <literal>oid</literal> system columns cannot be added
+ anymore, this never has an effect.
</para>
</listitem>
</varlistentry>
diff --git a/doc/src/sgml/ref/pg_checksums.sgml b/doc/src/sgml/ref/pg_checksums.sgml
index 33706d1..162bafd 100644
--- a/doc/src/sgml/ref/pg_checksums.sgml
+++ b/doc/src/sgml/ref/pg_checksums.sgml
@@ -120,7 +120,7 @@ PostgreSQL documentation
to be written safely to disk. This option causes
<command>pg_checksums</command> to return without waiting, which is
faster, but means that a subsequent operating system crash can leave
- the updated data folder corrupt. Generally, this option is useful
+ the updated data directory corrupt. Generally, this option is useful
for testing but should not be used on a production installation.
This option has no effect when using <literal>--check</literal>.
</para>
diff --git a/doc/src/sgml/ref/pg_dump.sgml b/doc/src/sgml/ref/pg_dump.sgml
index 8fa2314..017713f 100644
--- a/doc/src/sgml/ref/pg_dump.sgml
+++ b/doc/src/sgml/ref/pg_dump.sgml
@@ -749,7 +749,7 @@ PostgreSQL documentation
<term><option>--extra-float-digits=<replaceable class="parameter">ndigits</replaceable></option></term>
<listitem>
<para>
- Use the specified value of extra_float_digits when dumping
+ Use the specified value of <option>extra_float_digits</option> when dumping
floating-point data, instead of the maximum available precision.
Routine dumps made for backup purposes should not use this option.
</para>
diff --git a/doc/src/sgml/ref/pg_rewind.sgml b/doc/src/sgml/ref/pg_rewind.sgml
index 4d91eeb..52a1caa 100644
--- a/doc/src/sgml/ref/pg_rewind.sgml
+++ b/doc/src/sgml/ref/pg_rewind.sgml
@@ -184,7 +184,7 @@ PostgreSQL documentation
to be written safely to disk. This option causes
<command>pg_rewind</command> to return without waiting, which is
faster, but means that a subsequent operating system crash can leave
- the synchronized data folder corrupt. Generally, this option is
+ the synchronized data directory corrupt. Generally, this option is
useful for testing but should not be used when creating a production
installation.
</para>
diff --git a/doc/src/sgml/ref/pgbench.sgml b/doc/src/sgml/ref/pgbench.sgml
index e3b73a4..13ef168 100644
--- a/doc/src/sgml/ref/pgbench.sgml
+++ b/doc/src/sgml/ref/pgbench.sgml
@@ -474,10 +474,10 @@ pgbench <optional> <replaceable>options</replaceable> </optional> <replaceable>d
</listitem>
</itemizedlist>
- Because in "prepared" mode <application>pgbench</application> reuses
- the parse analysis result for the second and subsequent query
- iteration, <application>pgbench</application> runs faster in the
- prepared mode than in other modes.
+ In the <literal>prepared</literal> mode, <application>pgbench</application>
+ reuses the parse analysis result starting from the second query
+ iteration, so <application>pgbench</application> runs faster
+ than in other modes.
</para>
<para>
The default is simple query protocol. (See <xref linkend="protocol"/>
diff --git a/doc/src/sgml/ref/reindex.sgml b/doc/src/sgml/ref/reindex.sgml
index 303436c..10881ab 100644
--- a/doc/src/sgml/ref/reindex.sgml
+++ b/doc/src/sgml/ref/reindex.sgml
@@ -156,7 +156,7 @@ REINDEX [ ( VERBOSE ) ] { INDEX | TABLE | SCHEMA | DATABASE | SYSTEM } [ CONCURR
<para>
When this option is used, <productname>PostgreSQL</productname> will rebuild the
index without taking any locks that prevent concurrent inserts,
- updates, or deletes on the table; whereas a standard reindex build
+ updates, or deletes on the table; whereas a standard index rebuild
locks out writes (but not reads) on the table until it's done.
There are several caveats to be aware of when using this option
— see <xref linkend="sql-reindex-concurrently"
@@ -280,12 +280,12 @@ REINDEX [ ( VERBOSE ) ] { INDEX | TABLE | SCHEMA | DATABASE | SYSTEM } [ CONCURR
of writes. This method is invoked by specifying the
<literal>CONCURRENTLY</literal> option of <command>REINDEX</command>. When this option
is used, <productname>PostgreSQL</productname> must perform two scans of the table
- for each index that needs to be rebuild and in addition it must wait for
- all existing transactions that could potentially use the index to
- terminate. This method requires more total work than a standard index
+ for each index that needs to be rebuilt and wait for termination of
+ all existing transactions that could potentially use the index.
+ This method requires more total work than a standard index
rebuild and takes significantly longer to complete as it needs to wait
for unfinished transactions that might modify the index. However, since
- it allows normal operations to continue while the index is rebuilt, this
+ it allows normal operations to continue while the index is being rebuilt, this
method is useful for rebuilding indexes in a production environment. Of
course, the extra CPU, memory and I/O load imposed by the index rebuild
may slow down other operations.
@@ -442,8 +442,8 @@ broken_db=> \q
</programlisting></para>
<para>
- Rebuild a table while authorizing read and write operations on involved
- relations when performed:
+ Rebuild indexes for a table, without blocking read and write operations
+ on involved relations while reindexing is in progress:
<programlisting>
REINDEX TABLE CONCURRENTLY my_broken_table;
* Re: misc doc fixes for REL_12_STABLE
2019-07-11 14:49 misc doc fixes for REL_12_STABLE Liudmila Mantrova <l.mantrova@postgrespro.ru>
@ 2019-07-12 04:44 ` Michael Paquier <michael@paquier.xyz>
2019-07-12 09:35 ` Re: misc doc fixes for REL_12_STABLE Liudmila Mantrova <l.mantrova@postgrespro.ru>
0 siblings, 1 reply; 4+ messages in thread
From: Michael Paquier @ 2019-07-12 04:44 UTC (permalink / raw)
To: Liudmila Mantrova <l.mantrova@postgrespro.ru>; +Cc: pgsql-docs@lists.postgresql.org
On Thu, Jul 11, 2019 at 05:49:26PM +0300, Liudmila Mantrova wrote:
> Please consider a patch that fixes some trivial issues in new doc fragments
> (a couple of typos/ambiguities and some tags that affect translation).
Thanks for the patch. I have one comment.
> - backups. Moreover, because it writes a backup_label file on the
> - master, it can cause the master to fail to restart automatically after
> - a crash. On the other hand, the erroneous removal of a backup_label
> - file from a backup or standby is a common mistake which can result
> + backups. Moreover, because it creates a backup label file, as
> + described below, it can block automatic restart of the master server
> + after a crash. On the other hand, the erroneous removal of this
> + file from a backup or standby is a common mistake, which can result
> in serious data corruption. If it is necessary to use this method,
> the following steps may be used.
Okay, yes that could be a bit confusing for the reader. Nit: I would
replace "master" with "primary" while we are in the area. What do you
think?
But that's the only comment I have, the rest looks good!
--
Michael
Attachments:
signature.asc (application/pgp-signature, 832B) download
^ permalink raw reply [nested|flat] 4+ messages in thread
* Re: misc doc fixes for REL_12_STABLE
2019-07-11 14:49 misc doc fixes for REL_12_STABLE Liudmila Mantrova <l.mantrova@postgrespro.ru>
2019-07-12 04:44 ` Re: misc doc fixes for REL_12_STABLE Michael Paquier <michael@paquier.xyz>
@ 2019-07-12 09:35 ` Liudmila Mantrova <l.mantrova@postgrespro.ru>
2019-07-13 05:45 ` Re: misc doc fixes for REL_12_STABLE Michael Paquier <michael@paquier.xyz>
0 siblings, 1 reply; 4+ messages in thread
From: Liudmila Mantrova @ 2019-07-12 09:35 UTC (permalink / raw)
To: Michael Paquier <michael@paquier.xyz>; +Cc: pgsql-docs@lists.postgresql.org
On 7/12/19 7:44 AM, Michael Paquier wrote:
> On Thu, Jul 11, 2019 at 05:49:26PM +0300, Liudmila Mantrova wrote:
>> Please consider a patch that fixes some trivial issues in new doc fragments
>> (a couple of typos/ambiguities and some tags that affect translation).
> Thanks for the patch. I have one comment.
>
>> - backups. Moreover, because it writes a backup_label file on the
>> - master, it can cause the master to fail to restart automatically after
>> - a crash. On the other hand, the erroneous removal of a backup_label
>> - file from a backup or standby is a common mistake which can result
>> + backups. Moreover, because it creates a backup label file, as
>> + described below, it can block automatic restart of the master server
>> + after a crash. On the other hand, the erroneous removal of this
>> + file from a backup or standby is a common mistake, which can result
>> in serious data corruption. If it is necessary to use this method,
>> the following steps may be used.
> Okay, yes that could be a bit confusing for the reader. Nit: I would
> replace "master" with "primary" while we are in the area. What do you
> think?
>
> But that's the only comment I have, the rest looks good!
> --
> Michael
Hi Michael,
Changing master to primary was my first inclination, but I saw that we
have 8 masters and 4 primaries here. So maybe we should have another
consistency patch (that probably goes beyond this chapter). I can
prepare one if you like.
P.S. I'm not particularly happy about this paragraph either, but that's
as far as I could get without twisting the original ideas.
--
Liudmila Mantrova
Technical writer at Postgres Professional: http://www.postgrespro.com
The Russian Postgres Company
^ permalink raw reply [nested|flat] 4+ messages in thread
* Re: misc doc fixes for REL_12_STABLE
2019-07-11 14:49 misc doc fixes for REL_12_STABLE Liudmila Mantrova <l.mantrova@postgrespro.ru>
2019-07-12 04:44 ` Re: misc doc fixes for REL_12_STABLE Michael Paquier <michael@paquier.xyz>
2019-07-12 09:35 ` Re: misc doc fixes for REL_12_STABLE Liudmila Mantrova <l.mantrova@postgrespro.ru>
@ 2019-07-13 05:45 ` Michael Paquier <michael@paquier.xyz>
0 siblings, 0 replies; 4+ messages in thread
From: Michael Paquier @ 2019-07-13 05:45 UTC (permalink / raw)
To: Liudmila Mantrova <l.mantrova@postgrespro.ru>; +Cc: pgsql-docs@lists.postgresql.org
On Fri, Jul 12, 2019 at 12:35:49PM +0300, Liudmila Mantrova wrote:
> Changing master to primary was my first inclination, but I saw that we have
> 8 masters and 4 primaries here. So maybe we should have another consistency
> patch (that probably goes beyond this chapter). I can prepare one if you
> like.
I have been looking at your patch again, and committed your
improvements as they were originally presented as my comment can apply
to much more places. Thanks!
--
Michael
Attachments:
signature.asc (application/pgp-signature, 832B) download
^ permalink raw reply [nested|flat] 4+ messages in thread
end of thread, other threads:[~2019-07-13 05:45 UTC | newest]
Thread overview: 4+ messages (download: mbox mbox.gz follow: Atom feed)
-- links below jump to the message on this page --
2019-07-11 14:49 misc doc fixes for REL_12_STABLE Liudmila Mantrova <l.mantrova@postgrespro.ru>
2019-07-12 04:44 ` Michael Paquier <michael@paquier.xyz>
2019-07-12 09:35 ` Liudmila Mantrova <l.mantrova@postgrespro.ru>
2019-07-13 05:45 ` Michael Paquier <michael@paquier.xyz>
This inbox is served by DDX for PostgreSQL; see mirroring instructions
for how to clone and mirror all data and code used for this inbox