Hi, I find the inclusion of the un-parenthesized syntax for VACUUM, ANALYZE, and EXPLAIN in the docs makes it harder to understand the preferred, parenthesized syntax (see [1] as an example).
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 left out CLUSTER since that syntax change is so new. - Melanie [1] https://www.postgresql.org/docs/devel/sql-analyze.html [2] https://www.postgresql.org/message-id/3024596.1681940741%40sss.pgh.pa.us
From adef275c702833c6a4441d347ab8303403576fb2 Mon Sep 17 00:00:00 2001 From: Melanie Plageman <melanieplage...@gmail.com> Date: Fri, 21 Apr 2023 18:11:06 -0400 Subject: [PATCH v1] Doc: Move un-parenthesized syntax to compatibility for few SQL commands Move documentation of the un-parenthesized syntax for VACUUM, ANALYZE, and EXPLAIN to the "Compatibility" section of their documentation to improve readability of the preferred, parenthesized syntax. Discussion: https://postgr.es/m/3024596.1681940741%40sss.pgh.pa.us --- doc/src/sgml/ref/analyze.sgml | 9 ++++++++- doc/src/sgml/ref/explain.sgml | 9 ++++++++- doc/src/sgml/ref/vacuum.sgml | 9 ++++++++- 3 files changed, 24 insertions(+), 3 deletions(-) diff --git a/doc/src/sgml/ref/analyze.sgml b/doc/src/sgml/ref/analyze.sgml index 20c6f9939f..08d6902276 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> @@ -346,6 +345,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/explain.sgml b/doc/src/sgml/ref/explain.sgml index 410490951b..748bbf1eeb 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> @@ -529,6 +528,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..5dc43d480d 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> @@ -532,6 +531,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
