doc changes

Reviewed-by: David G. Johnston <david.g.johnston@gmail.com>

Author: robertmhaas

doc/src/sgml/pgplanadvice.sgml

@@ -21,7 +21,7 @@
   underlying data changes, the planner normally has the option to adjust the
   plan in an attempt to preserve good performance. If the plan advice prevents
   this, a very poor plan may be chosen. It is important to use plan advice
-  only when risks of constraining the planner's choices are outweighed by
+  only when the risks of constraining the planner's choices are outweighed by
   the benefits.
  </para>
 
@@ -39,7 +39,7 @@
    <link linkend="sql-load"><literal>LOAD</literal></link> command. If you
    wish to use the
    <link linkend="pgplanadvice-collector">collector interface</link>,
-   you must also the <literal>pg_plan_advice</literal> extension
+   you must also install the <literal>pg_plan_advice</literal> extension
    in the database where you wish to use the collector. Use the command
    <literal>CREATE EXTENSION pg_plan_advice</literal> to do this. If you do
    not wish to use the collector interface, this step is not required.
@@ -157,8 +157,8 @@ EXPLAIN (COSTS OFF)
    there is a bug in your advice string, or the plan in question was not
    considered viable by the core planner. This commonly happens for one of two
    reasons. First, it might be the planner believes that the plan you're trying
-   to force would be semantically incorrect -- that is, it would produce the
-   wrong results -- and for that reason it wasn't considered. Second, it might
+   to force would be semantically incorrect - that is, it would produce the
+   wrong results - and for that reason it wasn't considered. Second, it might
    be that the planner rejected the plan you were hoping to generate on some
    grounds other than cost. For example, given a very simple query such as
    <literal>SELECT * FROM some_table</literal>, the query planner will
@@ -218,8 +218,8 @@ EXPLAIN (COSTS OFF)
    cases, such as the examples shown above, the advice target is simply the
    relation alias. However, a more complex syntax is required when subqueries
    are used, when tables are partitioned, or when the same relation alias is
-   mentioned more than once in the same subquery (e.g. <literal>(foo JOIN bar
-   ON foo.a = bar.a) x JOIN foo ON x.b = foo.b</literal>. Any combination of
+   mentioned more than once in the same subquery (e.g., <literal>(foo JOIN bar
+   ON foo.a = bar.a) x JOIN foo ON x.b = foo.b</literal>). Any combination of
    these three things can occur simultaneously: a relation could be mentioned
    more than once, be partitioned, and be used inside of a subquery.
   </para>
@@ -234,22 +234,22 @@ alias_name#occurrence_number/partition_schema.partition_name@plan_name
 
   <para>
    All components except for the <literal>alias_name</literal> are optional
-   and included only when required. When a component is omitted, the associated
-   punctuation must also be omitted. For the first occurrence of a table
-   within a given subquery, generated advice will omit the occurrence number,
-   but it is legal to write <literal>#1</literal>, if desired. The partition
-   schema and partition name are included only for children of partitioned
-   tables. In generated advice, we always incude both, but it is legal to
-   omit the schema. The plan name is omitted for the toplevel plan, and must
-   be included for any subplan.
+   and are included only when required. When a component is omitted, the
+   preceding punctuation must also be omitted. For the first occurrence of a
+   table within a given subquery, generated advice will omit the occurrence
+   number, but it is legal to write <literal>#1</literal>, if desired. The
+   partition schema and partition name are included only for children of
+   partitioned tables. In generated advice, <literal>pg_plan_advice</literal>
+   always includes both, but it is legal to omit the schema. The plan name is
+   omitted for the top-level plan, and must be included for any subplan.
   </para>
 
   <para>
    It is not always easy to determine the correct advice target by examining
-   the query; for instance, if the planner pulls up a subquery into the parent
+   the query. For instance, if the planner pulls up a subquery into the parent
    query level, everything inside of it becomes part of the parent query level,
    and uses the parent query's subplan name (or no subplan name, if pulled up
-   to the toplevel). Furthermore, the correct subquery name is sometimes not
+   to the top level). Furthermore, the correct subquery name is sometimes not
    obvious. For example, when two queries are joined using an operation such as
    <literal>UNION</literal> or <literal>INTERSECT</literal>, no name for the
    subqueries is present in the SQL syntax; instead, a system-generated name is
@@ -301,9 +301,9 @@ BITMAP_HEAP_SCAN(<replaceable>target</replaceable> [ ... ])</synopsis>
    </para>
 
    <para>
-    <literal>FOREIGN_SCAN</literal> specifies that a foreign join between
-    a several foreign tables should be pushed down to a remote server so
-    that it can be implenented as a single <literal>Foreign Scan</literal>.
+    <literal>FOREIGN_SCAN</literal> specifies that a join between two or
+    more foreign tables should be pushed down to a remote server so
+    that it can be implemented as a single <literal>Foreign Scan</literal>.
     Specifying <literal>FOREIGN_SCAN</literal> for a single foreign table is
     neither necessary nor permissible: a <literal>Foreign Scan</literal> will
     need to be used regardless. If you want to prevent a join from being
@@ -348,7 +348,7 @@ JOIN_ORDER(<replaceable>join_order_item</replaceable> [ ... ])
    <para>
     If a <literal>JOIN_ORDER</literal> list contains a parenthesized sublist,
     it specifies a non-outer-deep join. The tables in the sublist must first
-    be joined to each other much as if the sublist were a toplevel
+    be joined to each other much as if the sublist were a top-level
     <literal>JOIN_ORDER</literal> list, and the resulting join product must
     then appear on the inner side of a join at the appropriate point in the
     join order. For example, <literal>JOIN_ORDER(a (b c) d)</literal> requires
@@ -366,12 +366,12 @@ Join
 </programlisting>
 
    <para>
-    If a <literal>JOIN_ORDER</literal> list contains a sublist surronded by
+    If a <literal>JOIN_ORDER</literal> list contains a sublist surrounded by
     curly braces, this also specifies a non-outer-deep join. However, the join
     order within the sublist is not constrained. For example, specifiying
-    <literal>JOIN_ORDER(a {b c} d</literal> would allow the scans of
+    <literal>JOIN_ORDER(a {b c} d)</literal> would allow the scans of
     <literal>b</literal> and <literal>c</literal> to be swapped in the
-    previous example, which is not allowed when parenthese are used.
+    previous example, which is not allowed when parentheses are used.
    </para>
 
    <para>
@@ -401,21 +401,21 @@ join_method_name(<replaceable>join_method_item</replaceable> [ ... ])
 
 <phrase>and <replaceable>join_method_item</replaceable> is:</phrase>
 
-<replaceable>advice_target</replaceable> |
+{ <replaceable>advice_target</replaceable> |
 ( <replaceable>advice_target</replaceable> [ ... ] ) }</synopsis>
 
    <para>
     Join method advice specifies the table, or set of tables, that should
     appear on the inner side of a join using the named join method. For
     example, <literal>HASH_JOIN(a b)</literal> means that each of
     <literal>a</literal> and <literal>b</literal> should appear on the inner
-    side of a hash join; a confirming plan must contain at least two hash
+    side of a hash join; a conforming plan must contain at least two hash
     joins, one of which has <literal>a</literal> and nothing else on the
     inner side, and the other of which has <literal>b</literal> and nothing
     else on the inner side. On the other hand,
     <literal>HASH_JOIN((a b))</literal> means that the join product of
     <literal>a</literal> and <literal>b</literal> should appear together
-    on the inner side of a a single hash join.
+    on the inner side of a single hash join.
    </para>
 
    <para>
@@ -442,7 +442,7 @@ PARTITIONWISE(<replaceable>partitionwise_item</replaceable> [ ... ])
 
 <phrase>where <replaceable>partitionwise_item</replaceable> is:</phrase>
 
-<replaceable>advice_target</replaceable> |
+{ <replaceable>advice_target</replaceable> |
 ( <replaceable>advice_target</replaceable> [ ... ] ) }</synopsis>
 
    <para>
@@ -465,7 +465,7 @@ SEMIJOIN_NON_UNIQUE(<replaceable>sj_unique_item</replaceable> [ ... ])
 
 <phrase>where <replaceable>sj_unique_item</replaceable> is:</phrase>
 
-<replaceable>advice_target</replaceable> |
+{ <replaceable>advice_target</replaceable> |
 ( <replaceable>advice_target</replaceable> [ ... ] ) }</synopsis>
 
    <para>
@@ -488,7 +488,7 @@ NO_GATHER(<replaceable>advice_target</replaceable> [ ... ])
 
 <phrase>where <replaceable>gather_item</replaceable> is:</phrase>
 
-<replaceable>advice_target</replaceable> |
+{ <replaceable>advice_target</replaceable> |
 ( <replaceable>advice_target</replaceable> [ ... ] ) }</synopsis>
 
    <para>
@@ -559,7 +559,7 @@ rhaas=# EXPLAIN (COSTS OFF)
    <literal>HASH_JOIN(f g)</literal> is actually a request for two logically
    separate behaviors, whereas <literal>JOIN_ORDER(f g)</literal> is a single
    request. When providing advice feedback, <literal>EXPLAIN</literal> shows
-   each logical request separtely, together with all the feedback applicable
+   each logical request separately, together with all the feedback applicable
    to that request type.
   </para>
 
@@ -579,15 +579,15 @@ rhaas=# EXPLAIN (COSTS OFF)
    <listitem>
     <para>
      <literal>partially matched</literal> means that some but not all of the
-     specified advice targetes were observed during query planning.
+     specified advice targets were observed during query planning.
     </para>
    </listitem>
 
    <listitem>
     <para>
      <literal>not matched</literal> means that none of the
      specified advice targets were observed during query planning. This may
-     be happen if the advice simply doesn't match the query, or it may
+     happen if the advice simply doesn't match the query, or it may
      occur if the relevant portion of the query was not planned, perhaps
      because it was gated by a condition that was simplified to constant false.
     </para>
@@ -829,11 +829,11 @@ rhaas=# EXPLAIN (COSTS OFF)
       <varname>pg_plan_advice.always_store_advice_details</varname> allows
       <literal>EXPLAIN</literal> to show details related to plan advice even
       when prepared queries are used.  The default value is
-      <literal>false</literal>.  When planning a prepared query, we do not
-      know whether <literal>EXPLAIN</literal> will be used, so by default, to
-      reduce overhead, we do not generate plan advice, and we do not generate
-      feedback on supplied advice. This means that if
-      <literal>EXPLAIN EXECUTE</literal> is later used on the prepared query,
+      <literal>false</literal>.  When planning a prepared query, it is not
+      possible to know whether <literal>EXPLAIN</literal> will later be used,
+      so by default, to reduce overhead, <literal>pg_plan_advice</literal>
+      will not generate plan advice or feedback on supplied advice. This means
+      that if <literal>EXPLAIN EXECUTE</literal> is used on the prepared query,
       it will not be able to show this information. Changing this setting to
       <literal>true</literal> avoids this problem, but adds additional
       overhead. It is probably a good idea to enable this option only in