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.

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

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