Received: from malur.postgresql.org ([217.196.149.56])
	by arkaria.postgresql.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_CBC_SHA1:256)
	(Exim 4.89)
	(envelope-from <pgsql-docs-owner+archive@lists.postgresql.org>)
	id 1idh8G-0007JO-CS
	for pgsql-docs@arkaria.postgresql.org; Sat, 07 Dec 2019 20:56:52 +0000
Received: from localhost ([127.0.0.1] helo=malur.postgresql.org)
	by malur.postgresql.org with esmtp (Exim 4.89)
	(envelope-from <pgsql-docs-owner+archive@lists.postgresql.org>)
	id 1idh8D-0004sS-9T
	for pgsql-docs@arkaria.postgresql.org; Sat, 07 Dec 2019 20:56:49 +0000
Received: from makus.postgresql.org ([2001:4800:3e1:1::229])
	by malur.postgresql.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_CBC_SHA1:256)
	(Exim 4.89)
	(envelope-from <tgl@sss.pgh.pa.us>)
	id 1idh8C-0004sL-US
	for pgsql-docs@lists.postgresql.org; Sat, 07 Dec 2019 20:56:49 +0000
Received: from sss.pgh.pa.us ([66.207.139.130])
	by makus.postgresql.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256)
	(Exim 4.92)
	(envelope-from <tgl@sss.pgh.pa.us>)
	id 1idh87-0004DV-H7
	for pgsql-docs@lists.postgresql.org; Sat, 07 Dec 2019 20:56:47 +0000
Received: from sss1.sss.pgh.pa.us (localhost [127.0.0.1])
	by sss.pgh.pa.us (8.14.4/8.14.4) with ESMTP id xB7KudnX014958;
	Sat, 7 Dec 2019 15:56:39 -0500
From: Tom Lane <tgl@sss.pgh.pa.us>
To: Julien Rouhaud <rjuju123@gmail.com>
cc: Tatsuo Ishii <ishii@sraoss.co.jp>, pgsql-docs@lists.postgresql.org
Subject: Re: Typo in perform.sgml?
In-reply-to: <29011.1575737207@sss.pgh.pa.us>
References: <20191207.200500.989741087350666720.t-ishii@sraoss.co.jp>
 <CAOBaU_afRuoGf40O0YN_ncZ5L5pEXF8HaUXJ6A_S3XgOJWH5Dw@mail.gmail.com>
 <29011.1575737207@sss.pgh.pa.us>
Comments: In-reply-to Tom Lane <tgl@sss.pgh.pa.us>
	message dated "Sat, 07 Dec 2019 11:46:47 -0500"
MIME-Version: 1.0
Content-Type: multipart/mixed; boundary="----- =_aaaaaaaaaa0"
Content-ID: <14881.1575752103.0@sss.pgh.pa.us>
Date: Sat, 07 Dec 2019 15:56:39 -0500
Message-ID: <14957.1575752199@sss.pgh.pa.us>
List-Id: <pgsql-docs.lists.postgresql.org>
List-Help: <https://lists.postgresql.org/manage/>
List-Subscribe: <https://lists.postgresql.org/manage/>
List-Post: <mailto:pgsql-docs@lists.postgresql.org>
List-Owner: <mailto:pgsql-docs-owner@lists.postgresql.org>
List-Archive: <https://www.postgresql.org/list/pgsql-docs>
Precedence: bulk

------- =_aaaaaaaaaa0
Content-Type: text/plain; charset="us-ascii"
Content-ID: <14881.1575752103.1@sss.pgh.pa.us>

I wrote:
> Actually, that whole para could do with a rewrite; whoever wrote
> it was obviously not familiar with Strunk & White's dictum
> "Omit needless words".

Looking closer, there were also some unnecessary inconsistencies with
the rest of the section, such as use of "records" rather than "rows",
and different markup choices.  I propose the attached ... it's
actually a bit longer than the original, but that's because it
offers more details.

			regards, tom lane


------- =_aaaaaaaaaa0
Content-Type: text/x-diff; name="improve-subplan-pruning-docs.patch";
	charset="us-ascii"
Content-ID: <14881.1575752103.2@sss.pgh.pa.us>
Content-Description: improve-subplan-pruning-docs.patch
Content-Transfer-Encoding: quoted-printable

diff --git a/doc/src/sgml/perform.sgml b/doc/src/sgml/perform.sgml
index 715aff6..0f61b09 100644
--- a/doc/src/sgml/perform.sgml
+++ b/doc/src/sgml/perform.sgml
@@ -896,15 +896,16 @@ EXPLAIN ANALYZE SELECT * FROM tenk1 WHERE unique1 &l=
t; 100 AND unique2 &gt; 9000
    </para>
 =

    <para>
-    Generally, the <command>EXPLAIN</command> output will display details=
 for
-    every plan node which was generated by the query planner.  However, t=
here
-    are cases where the executor is able to determine that certain nodes =
are
-    not required; currently, the only node types to support this are the
-    <literal>Append</literal> and <literal>MergeAppend</literal> nodes.  =
These
-    node types have the ability to discard subnodes which they are able t=
o
-    determine won't contain any records required by the query.  It is pos=
sible
-    to determine that nodes have been removed in this way by the presence=
 of a
-    "Subplans Removed" property in the <command>EXPLAIN</command> output.
+    Normally, <command>EXPLAIN</command> will display every plan node
+    created by the planner.  However, there are cases where the executor
+    can determine that certain nodes need not be executed because they
+    cannot produce any rows, based on parameter values that were not
+    available at planning time.  (Currently this can only happen for chil=
d
+    nodes of an Append or MergeAppend node that is scanning a partitioned
+    table.)  When this happens, those plan nodes are omitted from
+    the <command>EXPLAIN</command> output and a <literal>Subplans
+    Removed: <replaceable>N</replaceable></literal> annotation appears
+    instead.
    </para>
   </sect2>
 =


------- =_aaaaaaaaaa0--