Original
>From: David Rowley <[email protected]>
>Date: 2026-08-02 15:20
>To: ZizhuanLiu X-MAN <[email protected]>
>Cc: pgsql-hackers <[email protected]>
>Subject: Re: [PATCH] Doc: Mention OFF as an alias for EXPLAIN SERIALIZE NONE
>
>On Sun, 7 Jun 2026 at 15:29, ZizhuanLiu X-MAN <[email protected]> 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)
[email protected]
