public inbox for pgsql-docs@postgresql.org
help / color / mirror / Atom feedFrom: Shinya Kato <shinya11.kato@gmail.com>
To: maciek@sakrejda.org
Cc: surya poondla <suryapoondla4@gmail.com>
Cc: pgsql-docs@lists.postgresql.org
Subject: Re: doc: Clarify ANALYZE VERBOSE output
Date: Thu, 14 May 2026 21:14:27 +0900
Message-ID: <CAOzEurTyYgcPFAJGp5=BF9gObqgs8neQOvWo0g+txJMA8deYyw@mail.gmail.com> (raw)
In-Reply-To: <CAOtHd0CEvKrPnOx6_nv--R5sRwg47QqbrQG6P_2D0QQwxO9rcg@mail.gmail.com>
References: <CAOzEurTpMTUEW8kHu-zKB0EBtuPfpvyoJ--8pxKe87p24BGrpg@mail.gmail.com>
<CAOVWO5ov8_JR5Tj2J6cXPZF9cPM3P4w3yhVM9=NeiDMqY3t_PA@mail.gmail.com>
<CAOtHd0CEvKrPnOx6_nv--R5sRwg47QqbrQG6P_2D0QQwxO9rcg@mail.gmail.com>
On Tue, May 12, 2026 at 5:15 AM Maciek Sakrejda <m.sakrejda@gmail.com> wrote:
>
> On Tue, May 5, 2026 at 4:26 PM surya poondla <suryapoondla4@gmail.com> wrote:
> > On the wording debate: I think David and Maciek are both pointing at
> > the same real issue, the description should convey (a) "what kind of
> > information" users will see, and (b) "when" they'll see it.
> >
> > Given that, I'd suggest leaning toward something like:
> > "Sends a detailed INFO message to the client for each table as it is processed."
> >
> > I feel with the above message we balance, the server's perspective ("sends" rather than "prints"), and conveys timing ("after each table is processed").
>
> I agree with the analysis, and I think the proposed wording works well.
>
> > This same phrasing could work for both VACUUM and ANALYZE VERBOSE, keeping them consistent.
>
> +1 for consistency.
Sorry for the delayed response, and thank you for the feedback. I
agree with the points raised, so I have updated the patch accordingly.
--
Best regards,
Shinya Kato
NTT OSS Center
Attachments:
[application/octet-stream] v2-0001-doc-Clarify-VERBOSE-output-for-ANALYZE-and-VACUUM.patch (2.2K, 2-v2-0001-doc-Clarify-VERBOSE-output-for-ANALYZE-and-VACUUM.patch)
download | inline diff:
From 71b4878918abf8915c7cbfea24b90668a793c61e Mon Sep 17 00:00:00 2001
From: Shinya Kato <shinya11.kato@gmail.com>
Date: Thu, 14 May 2026 21:12:04 +0900
Subject: [PATCH v2] doc: Clarify VERBOSE output for ANALYZE and VACUUM
ANALYZE VERBOSE emits a detailed per-table INFO level report, like
VACUUM VERBOSE. Reword both option descriptions to convey the
server's perspective ("sends" rather than "prints") and to clarify
the timing of the output. Use identical wording for the two commands
for consistency.
Author: Shinya Kato <shinya11.kato@gmail.com>
Reviewed-by: Maciek Sakrejda <m.sakrejda@gmail.com>
Reviewed-by: Fujii Masao <masao.fujii@gmail.com>
Reviewed-by: David G. Johnston <david.g.johnston@gmail.com>
Reviewed-by: Surya Poondla <suryapoondla4@gmail.com>
Reviewed-by: Yushu Chen <gentcys@gmail.com>
Discussion: https://postgr.es/m/CAOzEurTpMTUEW8kHu-zKB0EBtuPfpvyoJ--8pxKe87p24BGrpg@mail.gmail.com
---
doc/src/sgml/ref/analyze.sgml | 3 ++-
doc/src/sgml/ref/vacuum.sgml | 4 ++--
2 files changed, 4 insertions(+), 3 deletions(-)
diff --git a/doc/src/sgml/ref/analyze.sgml b/doc/src/sgml/ref/analyze.sgml
index ec81f00fecf..aee7a4f560d 100644
--- a/doc/src/sgml/ref/analyze.sgml
+++ b/doc/src/sgml/ref/analyze.sgml
@@ -65,7 +65,8 @@ ANALYZE [ ( <replaceable class="parameter">option</replaceable> [, ...] ) ] [ <r
<term><literal>VERBOSE</literal></term>
<listitem>
<para>
- Enables display of progress messages at <literal>INFO</literal> level.
+ Sends a detailed <literal>INFO</literal> message to the client
+ for each table as it is processed.
</para>
</listitem>
</varlistentry>
diff --git a/doc/src/sgml/ref/vacuum.sgml b/doc/src/sgml/ref/vacuum.sgml
index bd5dcaf86a5..06f64f3827f 100644
--- a/doc/src/sgml/ref/vacuum.sgml
+++ b/doc/src/sgml/ref/vacuum.sgml
@@ -129,8 +129,8 @@ VACUUM [ ( <replaceable class="parameter">option</replaceable> [, ...] ) ] [ <re
<term><literal>VERBOSE</literal></term>
<listitem>
<para>
- Prints a detailed vacuum activity report for each table
- at <literal>INFO</literal> level.
+ Sends a detailed <literal>INFO</literal> message to the client
+ for each table as it is processed.
</para>
</listitem>
</varlistentry>
--
2.47.3
reply
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Reply to all the recipients using the --to and --cc options:
reply via email
To: pgsql-docs@postgresql.org
Cc: shinya11.kato@gmail.com, maciek@sakrejda.org, suryapoondla4@gmail.com, pgsql-docs@lists.postgresql.org
Subject: Re: doc: Clarify ANALYZE VERBOSE output
In-Reply-To: <CAOzEurTyYgcPFAJGp5=BF9gObqgs8neQOvWo0g+txJMA8deYyw@mail.gmail.com>
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
This inbox is served by agora; see mirroring instructions
for how to clone and mirror all data and code used for this inbox