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

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

diff --git a/doc/src/sgml/fdwhandler.sgml b/doc/src/sgml/fdwhandler.sgml
index 98882ddab8..69feefe66b 100644
--- a/doc/src/sgml/fdwhandler.sgml
+++ b/doc/src/sgml/fdwhandler.sgml
@@ -1075,46 +1075,37 @@ 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
-     <literal>TRUNCATE_REL_CONTEXT_NORMAL</literal>, which means that
-     the foreign table is specified WITHOUT <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>,
-     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.
-    </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
+     on a foreign table.  <literal>rels</literal> is a list of
+     <structname>Relation</structname> data structures for each
+     foreign tables to be truncated.
+     <literal>rels_extra</literal> is a list of <literal>int</literal> values
+     of the same length as <literal>rels</literal>.  Each element of
+     <literal>rels_extra</literal> is a bitmask of flags and provides extra
+     information about the corresponding foreign table.  Currently, the only
+     defined flag is <literal>TRUNCATE_REL_CONTEXT_ONLY</literal>, which means
+     that the foreign table was specified with the <literal>ONLY</literal>
+     clause in the original <command>TRUNCATE</command> command.
+    </para>
+
+    <para>
+     <literal>behavior</literal> is either
+     <literal>DROP_RESTRICT</literal> or <literal>DROP_CASCADE</literal>.
+     <literal>DROP_CASCADE</literal> indicates that the
+     <literal>CASCADE</literal> option was specified in the original
      <command>TRUNCATE</command> command.
     </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 included the
+     <literal>RESTART IDENTITY</literal> option.
     </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
+     <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>
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