v2-0001-Doc-Move-un-parenthesized-syntax-to-compatibility.patch

From 3fd4631c160f8c0b2817d9b3704ff80939cacea5 Mon Sep 17 00:00:00 2001
From: Melanie Plageman <melanieplageman@gmail.com>
Date: Fri, 21 Apr 2023 18:11:06 -0400
Subject: [PATCH v2] Doc: Move un-parenthesized syntax to compatibility for few
 SQL commands

Move documentation of the un-parenthesized syntax for VACUUM, ANALYZE,
EXPLAIN, and CLUSTER to the "Compatibility" section of their
documentation to improve readability of the preferred, parenthesized
syntax.

Discussion: https://postgr.es/m/flat/CAAKRu_bc5uHieG1976kGqJKxyWtyQt9yvktjsVX%2Bi7NOigDjOA%40mail.gmail.com
---
 doc/src/sgml/ref/analyze.sgml | 16 ++++++++--------
 doc/src/sgml/ref/cluster.sgml | 25 ++++++++++++++++---------
 doc/src/sgml/ref/explain.sgml | 17 ++++++++---------
 doc/src/sgml/ref/vacuum.sgml  | 18 ++++++++----------
 4 files changed, 40 insertions(+), 36 deletions(-)

diff --git a/doc/src/sgml/ref/analyze.sgml b/doc/src/sgml/ref/analyze.sgml
index 20c6f9939f..a3cde13b9a 100644
--- a/doc/src/sgml/ref/analyze.sgml
+++ b/doc/src/sgml/ref/analyze.sgml
@@ -22,7 +22,6 @@ PostgreSQL documentation
  <refsynopsisdiv>
 <synopsis>
 ANALYZE [ ( <replaceable class="parameter">option</replaceable> [, ...] ) ] [ <replaceable class="parameter">table_and_columns</replaceable> [, ...] ]
-ANALYZE [ VERBOSE ] [ <replaceable class="parameter">table_and_columns</replaceable> [, ...] ]
 
 <phrase>where <replaceable class="parameter">option</replaceable> can be one of:</phrase>
 
@@ -56,13 +55,6 @@ ANALYZE [ VERBOSE ] [ <replaceable class="parameter">table_and_columns</replacea
    It is further possible to give a list of column names for a table,
    in which case only the statistics for those columns are collected.
   </para>
-
-  <para>
-   When the option list is surrounded by parentheses, the options can be
-   written in any order.  The parenthesized syntax was added in
-   <productname>PostgreSQL</productname> 11;  the unparenthesized syntax
-   is deprecated.
-  </para>
  </refsect1>
 
  <refsect1>
@@ -346,6 +338,14 @@ ANALYZE [ VERBOSE ] [ <replaceable class="parameter">table_and_columns</replacea
   <para>
    There is no <command>ANALYZE</command> statement in the SQL standard.
   </para>
+
+  <para>
+   The following syntax was used before <productname>PostgreSQL</productname>
+   version 11.0 and is still supported:
+   <synopsis>
+    ANALYZE [ VERBOSE ] [ <replaceable class="parameter">table_and_columns</replaceable> [, ...] ]
+   </synopsis>
+  </para>
  </refsect1>
 
  <refsect1>
diff --git a/doc/src/sgml/ref/cluster.sgml b/doc/src/sgml/ref/cluster.sgml
index 29f0f1fd90..5bbe1ae2f5 100644
--- a/doc/src/sgml/ref/cluster.sgml
+++ b/doc/src/sgml/ref/cluster.sgml
@@ -21,9 +21,7 @@ PostgreSQL documentation
 
  <refsynopsisdiv>
 <synopsis>
-CLUSTER [VERBOSE] <replaceable class="parameter">table_name</replaceable> [ USING <replaceable class="parameter">index_name</replaceable> ]
-CLUSTER ( <replaceable class="parameter">option</replaceable> [, ...] ) <replaceable class="parameter">table_name</replaceable> [ USING <replaceable class="parameter">index_name</replaceable> ]
-CLUSTER [VERBOSE]
+CLUSTER [ ( <replaceable class="parameter">option</replaceable> [, ...] ) <replaceable class="parameter">table_name</replaceable> [ USING <replaceable class="parameter">index_name</replaceable> ] ]
 
 <phrase>where <replaceable class="parameter">option</replaceable> can be one of:</phrase>
 
@@ -252,12 +250,21 @@ CLUSTER;
   </para>
 
   <para>
-   The syntax
-<synopsis>
-CLUSTER <replaceable class="parameter">index_name</replaceable> ON <replaceable class="parameter">table_name</replaceable>
-</synopsis>
-  is also supported for compatibility with pre-8.3 <productname>PostgreSQL</productname>
-  versions.
+   The following syntaxes are supported for compatibility:
+  </para>
+
+  <para>
+   Compatible with pre-8.3 <productname>PostgreSQL</productname> versions:
+   <synopsis>
+    CLUSTER <replaceable class="parameter">index_name</replaceable> ON <replaceable class="parameter">table_name</replaceable>
+   </synopsis>
+
+   Compatible with pre-14 <productname>PostgreSQL</productname> versions:
+   <synopsis>
+    CLUSTER [VERBOSE] <replaceable class="parameter">table_name</replaceable> [ USING <replaceable class="parameter">index_name</replaceable> ]
+    CLUSTER [VERBOSE]
+   </synopsis>
+
   </para>
  </refsect1>
 
diff --git a/doc/src/sgml/ref/explain.sgml b/doc/src/sgml/ref/explain.sgml
index 410490951b..96f5cadc6b 100644
--- a/doc/src/sgml/ref/explain.sgml
+++ b/doc/src/sgml/ref/explain.sgml
@@ -32,7 +32,6 @@ PostgreSQL documentation
  <refsynopsisdiv>
 <synopsis>
 EXPLAIN [ ( <replaceable class="parameter">option</replaceable> [, ...] ) ] <replaceable class="parameter">statement</replaceable>
-EXPLAIN [ ANALYZE ] [ VERBOSE ] <replaceable class="parameter">statement</replaceable>
 
 <phrase>where <replaceable class="parameter">option</replaceable> can be one of:</phrase>
 
@@ -106,14 +105,6 @@ ROLLBACK;
 </programlisting>
    </para>
   </important>
-
-  <para>
-   Only the <literal>ANALYZE</literal> and <literal>VERBOSE</literal> options
-   can be specified, and only in that order, without surrounding the option
-   list in parentheses.  Prior to <productname>PostgreSQL</productname> 9.0,
-   the unparenthesized syntax was the only one supported.  It is expected that
-   all new options will be supported only in the parenthesized syntax.
-  </para>
  </refsect1>
 
  <refsect1>
@@ -529,6 +520,14 @@ EXPLAIN (GENERIC_PLAN)
   <para>
    There is no <command>EXPLAIN</command> statement defined in the SQL standard.
   </para>
+
+  <para>
+   The following syntax was used before <productname>PostgreSQL</productname>
+   version 9.0 and is still supported:
+   <synopsis>
+    EXPLAIN [ ANALYZE ] [ VERBOSE ] <replaceable class="parameter">statement</replaceable>
+   </synopsis>
+  </para>
  </refsect1>
 
  <refsect1>
diff --git a/doc/src/sgml/ref/vacuum.sgml b/doc/src/sgml/ref/vacuum.sgml
index 57bc4c23ec..19a12cdeb0 100644
--- a/doc/src/sgml/ref/vacuum.sgml
+++ b/doc/src/sgml/ref/vacuum.sgml
@@ -22,7 +22,6 @@ PostgreSQL documentation
  <refsynopsisdiv>
 <synopsis>
 VACUUM [ ( <replaceable class="parameter">option</replaceable> [, ...] ) ] [ <replaceable class="parameter">table_and_columns</replaceable> [, ...] ]
-VACUUM [ FULL ] [ FREEZE ] [ VERBOSE ] [ ANALYZE ] [ <replaceable class="parameter">table_and_columns</replaceable> [, ...] ]
 
 <phrase>where <replaceable class="parameter">option</replaceable> can be one of:</phrase>
 
@@ -90,15 +89,6 @@ VACUUM [ FULL ] [ FREEZE ] [ VERBOSE ] [ ANALYZE ] [ <replaceable class="paramet
    much slower and requires an <literal>ACCESS EXCLUSIVE</literal> lock on
    each table while it is being processed.
   </para>
-
-  <para>
-   When the option list is surrounded by parentheses, the options can be
-   written in any order.  Without parentheses, options must be specified
-   in exactly the order shown above.
-   The parenthesized syntax was added in
-   <productname>PostgreSQL</productname> 9.0;  the unparenthesized
-   syntax is deprecated.
-  </para>
  </refsect1>
 
  <refsect1>
@@ -532,6 +522,14 @@ VACUUM (VERBOSE, ANALYZE) onek;
   <para>
    There is no <command>VACUUM</command> statement in the SQL standard.
   </para>
+
+  <para>
+   The following syntax was used before <productname>PostgreSQL</productname>
+   version 9.0 and is still supported:
+   <synopsis>
+    VACUUM [ FULL ] [ FREEZE ] [ VERBOSE ] [ ANALYZE ] [ <replaceable class="parameter">table_and_columns</replaceable> [, ...] ]
+   </synopsis>
+  </para>
  </refsect1>
 
  <refsect1>
-- 
2.37.2