Re: [PATCH] Doc: Mention OFF as an alias for EXPLAIN SERIALIZE NONE

Original
>From: David Rowley <dgrowleyml(at)gmail(dot)com>
>Date: 2026-08-02 15:20
>To: ZizhuanLiu X-MAN <44973863(at)qq(dot)com>
>Cc: pgsql-hackers <pgsql-hackers(at)lists(dot)postgresql(dot)org>
>Subject: Re: [PATCH] Doc: Mention OFF as an alias for EXPLAIN SERIALIZE NONE
>
>On Sun, 7 Jun 2026 at 15:29, ZizhuanLiu X-MAN <44973863(at)qq(dot)com> wrote:
>> The parsing logic in `ParseExplainOptionList()` (explain_state.c) accepts
>> the keyword `OFF` and treats it as an exact alias for `NONE`. This behavior
>> is functional but currently undocumented.
>
>It sounds like you've assumed that every existing feature must be
>documented. This is a false assumption. Plenty of things exist in
>PostgreSQL that are not documented. You might be surprised to discover
>that you can type "ANALYSE" (the British spelling) instead of
>"ANALYZE" (the American spelling) to gather statistics on a table. Or
>that you can terminate your psql session with "exit" or "quit" (only
>\q is documented). The "exit" / "quit" feature was added to psql to
>help people who are not used to the tool. We don't want to document
>that, as we don't want that to become the default way that people use
>to exit the tool.
>

Not every configuration style knob requires documentation. Values like
0/1, false/true generally do not. We should document a flag only when it is reasonably notable.

>One thing that having undocumented features gives us is a much lower
>bar that the undocumented feature can one day be removed.
>

If so, this may account for why there was no prior record before OFF.

>What value do you suppose documenting that "off" is a valid option for
>EXPLAIN SERIALIZE brings to the project? In my view, it's a negative
>value as it adds more words to the documents without teaching anyone
>about any new behaviour.
>
>I suggest we reject this patch and keep the documentation and code for
>this exactly as it is.
>
>David

Should this patch be considered non significant and subject to future removal, I’ll withdraw it.

Thanks again for your review, David.

And thanks all of you reviewing.

regards,
--
ZizhuanLiu (X-MAN)
44973863(at)qq(dot)com