From 7bbd9312464899dfc2c70fdc64c95a298ac01594 Mon Sep 17 00:00:00 2001
From: Justin Pryzby <pryzbyj@telsasoft.com>
Date: Thu, 8 Apr 2021 10:10:58 -0500
Subject: [PATCH 1/3] WIP doc review: Allow TRUNCATE command to truncate
 foreign tables.

8ff1c94649f5c9184ac5f07981d8aea9dfd7ac19
---
 doc/src/sgml/fdwhandler.sgml   | 43 +++++++++++++++++-----------------
 doc/src/sgml/postgres-fdw.sgml |  2 +-
 doc/src/sgml/ref/truncate.sgml |  2 +-
 3 files changed, 23 insertions(+), 24 deletions(-)

diff --git a/doc/src/sgml/fdwhandler.sgml b/doc/src/sgml/fdwhandler.sgml
index 98882ddab8..5a76dede24 100644
--- a/doc/src/sgml/fdwhandler.sgml
+++ b/doc/src/sgml/fdwhandler.sgml
@@ -1075,40 +1075,39 @@ ExecForeignTruncate(List *rels, List *rels_extra,
                     DropBehavior behavior, bool restart_seqs);
 </programlisting>
 
-     Truncate a set of foreign tables specified in <literal>rels</literal>.
+     Truncate foreign tables.
      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.  <literal>rels_extra</literal> the list of
-     <literal>int</literal> value, which delivers extra information about
-     a foreign table to truncate.  Possible values are
+     on a foreign table.  <literal>rels</literal> is a list of
+     <structname>Relation</structname> data structures for the
+     foreign tables to be truncated.  <literal>rels_extra</literal> is a list of
+     corresponding <literal>int</literal> values which provide extra information about
+     the foreign tables.  Each element of rels_extra may have the value
      <literal>TRUNCATE_REL_CONTEXT_NORMAL</literal>, which means that
-     the foreign table is specified WITHOUT <literal>ONLY</literal> clause
+     the foreign table is specified <emphasis>WITHOUT</emphasis> the <literal>ONLY</literal> clause
      in <command>TRUNCATE</command>,
      <literal>TRUNCATE_REL_CONTEXT_ONLY</literal>, which means that
-     the foreign table is specified WITH <literal>ONLY</literal> clause,
-     and <literal>TRUNCATE_REL_CONTEXT_CASCADING</literal>,
+     the foreign table is specified <emphasis>WITH</emphasis> the <literal>ONLY</literal> clause,
+     or <literal>TRUNCATE_REL_CONTEXT_CASCADING</literal>,
      which means that the foreign table is not specified explicitly,
-     but will be truncated due to dependency (for example, partition table).
-     There is one-to-one mapping between <literal>rels</literal> and
-     <literal>rels_extra</literal>.  The number of entries is the same
-     between the two lists.
+     but will be truncated due to a dependency (for example, a table partition).
     </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
+     <literal>behavior</literal> must be specified as
+     <literal>DROP_RESTRICT</literal> or <literal>DROP_CASCADE</literal>.
+     If specified as <literal>DROP_RESTRICT</literal>, the
+     <literal>RESTRICT</literal> option will be included in the
      <command>TRUNCATE</command> command.
+     If specified as <literal>DROP_CASCADE</literal>, the
+     <literal>CASCADE</literal> option will be included.
     </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 specified as <literal>true</literal>,
+     the <command>TRUNCATE</command> command will include the
+     <literal>RESTART IDENTITY</literal> option.
+     Otherwise, the <command>TRUNCATE</command> command will include the
+     <literal>CONTINUE IDENTITY</literal> option.
     </para>
 
     <para>
diff --git a/doc/src/sgml/postgres-fdw.sgml b/doc/src/sgml/postgres-fdw.sgml
index 5320accf6f..116434f658 100644
--- a/doc/src/sgml/postgres-fdw.sgml
+++ b/doc/src/sgml/postgres-fdw.sgml
@@ -452,7 +452,7 @@ 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>.
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>
-- 
2.17.0