On Fri, Apr 21, 2023 at 6:55 PM Nathan Bossart <nathandboss...@gmail.com> wrote: > > On Fri, Apr 21, 2023 at 06:29:16PM -0400, Melanie Plageman wrote: > > Over in [2], it was suggested that moving the un-parenthesized syntax to > > the "Compatibility" section of their respective docs pages would be > > okay. Patch attached. > > I think that's reasonable. > > > I left out CLUSTER since that syntax change is so new. > > I think it'd be okay to move this one, too. The parenthesized syntax has > been available since v14, and I suspect CLUSTER isn't terribly widely used, > anyway. (Side note: it looks like "CLUSTER (VERBOSE)" doesn't work, which > seems weird to me.)
Attached v2 includes changes for CLUSTER syntax docs. I wasn't quite sure that we can move down CLUSTER [VERBOSE] syntax to the compatibility section since CLUSTER (VERBOSE) doesn't work. This seems like it should work (VACUUM and ANALYZE do). I put extra "[ ]" around the main CLUSTER syntax but I don't know that this is actually the same as documenting that CLUSTER VERBOSE does work but CLUSTER (VERBOSE) doesn't. > Most of these commands have an existing note about the deprecated syntax. > Could those be removed with this change? Ah, yes. Good catch! I have removed these. - Melanie
From 3fd4631c160f8c0b2817d9b3704ff80939cacea5 Mon Sep 17 00:00:00 2001 From: Melanie Plageman <melanieplage...@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
