From 0c8f40863acb94963df9fd6a4369eb71efe9a93b Mon Sep 17 00:00:00 2001
From: Fujii Masao <fujii@postgresql.org>
Date: Tue, 27 Apr 2021 18:39:30 +0900
Subject: [PATCH] doc: Review for "Allow TRUNCATE command to truncate foreign
 tables".

Typos, corrections and language improvements in the docs.

Author: Justin Pryzby, Fujii Masao
Reviewed-by: Bharath Rupireddy, Justin Pryzby, Fujii Masao
Discussion: https://postgr.es/m/20210411041658.GB14564@telsasoft.com
---
 doc/src/sgml/fdwhandler.sgml   | 37 ++++++++++++++++------------------
 doc/src/sgml/postgres-fdw.sgml |  8 +++++++-
 doc/src/sgml/ref/truncate.sgml |  2 +-
 3 files changed, 25 insertions(+), 22 deletions(-)

diff --git a/doc/src/sgml/fdwhandler.sgml b/doc/src/sgml/fdwhandler.sgml
index e08441ec8b..8aa7edfe4a 100644
--- a/doc/src/sgml/fdwhandler.sgml
+++ b/doc/src/sgml/fdwhandler.sgml
@@ -1076,27 +1076,25 @@ ExecForeignTruncate(List *rels,
                     bool restart_seqs);
 </programlisting>
 
-     Truncate a set of foreign tables specified in <literal>rels</literal>.
-     This function is called when <xref linkend="sql-truncate"/> is executed
-     on foreign tables.  <literal>rels</literal> is the list of
-     <structname>Relation</structname> data structure that indicates
-     a foreign table to truncate.
+     Truncate foreign tables.  This function is called when
+     <xref linkend="sql-truncate"/> is executed on a foreign table.
+     <literal>rels</literal> is a list of <structname>Relation</structname>
+     data structures of foreign tables to truncate.
     </para>
 
     <para>
-     <literal>behavior</literal> defines how foreign tables should
-     be truncated, using as possible values <literal>DROP_RESTRICT</literal>,
-     which means that <literal>RESTRICT</literal> option is specified,
-     and <literal>DROP_CASCADE</literal>, which means that
-     <literal>CASCADE</literal> option is specified, in
-     <command>TRUNCATE</command> command.
+     <literal>behavior</literal> is either <literal>DROP_RESTRICT</literal>
+     or <literal>DROP_CASCADE</literal> indicating that the
+     <literal>RESTRICT</literal> or <literal>CASCADE</literal> option was
+     requested in the original <command>TRUNCATE</command> command,
+     respectively.
     </para>
     
     <para>
-     <literal>restart_seqs</literal> is set to <literal>true</literal>
-     if <literal>RESTART IDENTITY</literal> option is specified in
-     <command>TRUNCATE</command> command.  It is <literal>false</literal>
-     if <literal>CONTINUE IDENTITY</literal> option is specified.
+     If <literal>restart_seqs</literal> is <literal>true</literal>,
+     the original <command>TRUNCATE</command> command requested the
+     <literal>RESTART IDENTITY</literal> behavior, otherwise the
+     <literal>CONTINUE IDENTITY</literal> behavior was requested.
     </para>
 
     <para>
@@ -1109,11 +1107,10 @@ ExecForeignTruncate(List *rels,
     </para>
 
     <para>
-     <command>TRUNCATE</command> invokes
-     <function>ExecForeignTruncate</function> once per foreign server
-     that foreign tables to truncate belong to.  This means that all foreign
-     tables included in <literal>rels</literal> must belong to the same
-     server.
+     <function>ExecForeignTruncate</function> is invoked once per
+     foreign server for which foreign tables are to be truncated.
+     This means that all foreign tables included in <literal>rels</literal>
+     must belong to the same server.
     </para>
 
     <para>
diff --git a/doc/src/sgml/postgres-fdw.sgml b/doc/src/sgml/postgres-fdw.sgml
index b0806c1274..839126c4ef 100644
--- a/doc/src/sgml/postgres-fdw.sgml
+++ b/doc/src/sgml/postgres-fdw.sgml
@@ -459,11 +459,17 @@ OPTIONS (ADD password_required 'false');
      <listitem>
       <para>
        This option controls whether <filename>postgres_fdw</filename> allows
-       foreign tables to be truncated using <command>TRUNCATE</command>
+       foreign tables to be truncated using the <command>TRUNCATE</command>
        command. It can be specified for a foreign table or a foreign server.
        A table-level option overrides a server-level option.
        The default is <literal>true</literal>.
       </para>
+
+      <para>
+       Of course, if the remote table is not in fact truncatable, an error
+       would occur anyway.  Use of this option primarily allows the error to
+       be thrown locally without querying the remote server.
+      </para>
      </listitem>
     </varlistentry>
    </variablelist>
diff --git a/doc/src/sgml/ref/truncate.sgml b/doc/src/sgml/ref/truncate.sgml
index acf3633be4..9d846f88c9 100644
--- a/doc/src/sgml/ref/truncate.sgml
+++ b/doc/src/sgml/ref/truncate.sgml
@@ -173,7 +173,7 @@ TRUNCATE [ TABLE ] [ ONLY ] <replaceable class="parameter">name</replaceable> [
 
   <para>
    <command>TRUNCATE</command> can be used for foreign tables if
-   the foreign data wrapper supports, for instance,
+   supported by the foreign data wrapper, for instance,
    see <xref linkend="postgres-fdw"/>.
   </para>
  </refsect1>