From ab29a7a9c6ffaddaf6788a13e83f1a249f06bb1b Mon Sep 17 00:00:00 2001
From: Nathan Bossart <nathan@postgresql.org>
Date: Wed, 19 Jul 2023 15:26:59 -0700
Subject: [PATCH] Doc: move unparenthesized syntaxes for a few commands.

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

Author: Melanie Plageman
Discussion: https://postgr.es/m/CAAKRu_bc5uHieG1976kGqJKxyWtyQt9yvktjsVX%2Bi7NOigDjOA%40mail.gmail.com
---
 doc/src/sgml/ref/analyze.sgml | 16 ++++++++--------
 doc/src/sgml/ref/cluster.sgml | 14 ++++++++++----
 doc/src/sgml/ref/explain.sgml | 19 ++++++++++---------
 doc/src/sgml/ref/vacuum.sgml  | 20 ++++++++++----------
 4 files changed, 38 insertions(+), 31 deletions(-)

diff --git a/doc/src/sgml/ref/analyze.sgml b/doc/src/sgml/ref/analyze.sgml
index aa3e9e1c5f..1fba089265 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>
@@ -339,6 +331,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 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 b6d5655c19..557a94cea7 100644
--- a/doc/src/sgml/ref/cluster.sgml
+++ b/doc/src/sgml/ref/cluster.sgml
@@ -22,7 +22,6 @@ PostgreSQL documentation
  <refsynopsisdiv>
 <synopsis>
 CLUSTER [ ( <replaceable class="parameter">option</replaceable> [, ...] ) ] [ <replaceable class="parameter">table_name</replaceable> [ USING <replaceable class="parameter">index_name</replaceable> ] ]
-CLUSTER [ VERBOSE ] [ <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>
 
@@ -240,12 +239,19 @@ CLUSTER;
   </para>
 
   <para>
-   The syntax
+   The following syntax was used before <productname>PostgreSQL</productname>
+   17 and is still supported:
+<synopsis>
+CLUSTER [ VERBOSE ] [ <replaceable class="parameter">table_name</replaceable> [ USING <replaceable class="parameter">index_name</replaceable> ] ]
+</synopsis>
+  </para>
+
+  <para>
+   The following syntax was used before <productname>PostgreSQL</productname>
+   8.3 and is still supported:
 <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.
   </para>
  </refsect1>
 
diff --git a/doc/src/sgml/ref/explain.sgml b/doc/src/sgml/ref/explain.sgml
index 410490951b..ae493c86d6 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,16 @@ 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>
+   Note that in this syntax, the options must be specified in exactly the order
+   shown.
+  </para>
  </refsect1>
 
  <refsect1>
diff --git a/doc/src/sgml/ref/vacuum.sgml b/doc/src/sgml/ref/vacuum.sgml
index 65c03bf829..90cde70c07 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>
@@ -525,6 +515,16 @@ 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>
+   Note that in this syntax, the options must be specified in exactly the order
+   shown.
+  </para>
  </refsect1>
 
  <refsect1>