MIME-Version: 1.0
References: 
 <CAOzEurTpMTUEW8kHu-zKB0EBtuPfpvyoJ--8pxKe87p24BGrpg@mail.gmail.com>
 <CAOtHd0AY4LuM+-JqFyzs4mPHG8yeAwfP5yr2EZg21RVO0442BA@mail.gmail.com>
 <CAHGQGwE2dC5aNBgV5AtpMMdZNpkGn1PAa9o=whi8_Wb3m3ruAA@mail.gmail.com>
 <CAKFQuwZUSetJvoXewwofTNP5dLfhg7S31NNJhZ=G+ZbOOCZ=ug@mail.gmail.com>
 <CAOzEurS7aNO=TnZztwnxJdLgmNnmotwcocxVR2s4qLrZ66ZkxQ@mail.gmail.com>
 <CAOtHd0AC7Yg-Fz+1uRHc=mqsVtpH6b5NM-uL_Chd2vwKT5jf7g@mail.gmail.com>
 <CAKFQuwYHBDNe0nyASfUCaw+s1rO+=yKTBd24yUf6nF6a1gRALw@mail.gmail.com>
In-Reply-To: 
 <CAKFQuwYHBDNe0nyASfUCaw+s1rO+=yKTBd24yUf6nF6a1gRALw@mail.gmail.com>
From: Maciek Sakrejda <maciek@pganalyze.com>
Date: Wed, 15 Apr 2026 09:38:26 -0700
Message-ID: 
 <CADXhmgTd+yONJz3FpxXW0W-y_qn69Tkc97whFQsdODBstBXOXw@mail.gmail.com>
Subject: Re: doc: Clarify ANALYZE VERBOSE output
To: "David G. Johnston" <david.g.johnston@gmail.com>
Cc: maciek@sakrejda.org, Shinya Kato <shinya11.kato@gmail.com>,
	Fujii Masao <masao.fujii@gmail.com>, pgsql-docs@lists.postgresql.org
Content-Type: text/plain; charset="UTF-8"
Content-Transfer-Encoding: quoted-printable
Archived-At: 
 <https://www.postgresql.org/message-id/CADXhmgTd%2ByONJz3FpxXW0W-y_qn69Tkc97whFQsdODBstBXOXw%40mail.gmail.com>
Precedence: bulk

On Mon, Apr 13, 2026 at 3:29=E2=80=AFPM David G. Johnston
<david.g.johnston@gmail.com> wrote:
>> On Tue, Apr 7, 2026 at 6:57=E2=80=AFPM Shinya Kato <shinya11.kato@gmail.=
com> wrote:
>> > I believe the current "Outputs" section is intentionally kept simple t=
o minimize maintenance overhead. While expanding it might be a worthwhile f=
ollow-up, it probably deserves its own dedicated discussion.
>>
>> +1, listing output details is signing up for busywork.
>
>
> Given how expansive and thorough our documentation is, and the fact this =
is user-facing output, I'm not seeing why this gets a pass on the documenta=
tion requirement.  That said, I concur this patch needn't be responsible fo=
r dealing with that - I'm not even sure whether trying to do that on the va=
cuum/analyze pages is even the correct choice since at least some of what i=
s output is object-specific and not generic to vacuum itself.  Though stuff=
 like timings are.  Even if we want to leave ourselves the "it's undocument=
ed so it can be changed at will" clause we can simply write that in.

It's not getting "a pass". Ultimately it's a judgment call:
maintenance cost versus existing conventions (how we document command
output in other places), utility to the user of having detailed docs
on this, and how easy it is to check the actual output by just running
the command. I think on balance it's not worth doing here, and "it's
undocumented so it can be changed at will" is equivalent to saying
nothing (so we might as well say nothing).

>> maybe something
>> along these lines:
>>
>> "Prints detailed stats at <literal>INFO</literal> level for each table
>> as it is processed."
>>
>
> I really don't like the word "Print" here.  What the client decides to do=
 with the INFO message is up to them - the interface to document for the se=
rver is simply sending the message and its details.

Fair enough, though we do use "print" as a synonym for "log" all over
the place. "Emit" was suggested down-thread; I think that's also a
good choice. Your "Sends" below also works.

> I was apparently mistaken about this info showing in the server log file =
though.
>
> So that leaves me with suggesting:
>
> "Enables the sending of a detailed INFO message to the client after each =
table is processed."

I'd simplify it to just

"Sends a detailed INFO message to the client after each table is processed.=
"

Technically the option itself is not doing the sending, but the
relationship of the option to the behavior is obvious, and I don't
think complicating the language to reflect the actual mechanism adds
anything.

Thanks,
Maciek