The following documentation comment has been logged on the website:
Page: https://www.postgresql.org/docs/15/sql-altersystem.html
Description:
Documentation say
ALTER SYSTEM SET configuration_parameter { TO | = } { value | 'value' |
DEFAULT }
The variant 'value' has special, not obvious behaviour and must be
documented.
This syntax representation and accompanying text annoys me too. It is logical behavior and described accurately, but I think readability could be improved.
I suggest changing it to:
SET configuration_parameter { TO | = } { value [, ...] | DEFAULT }
Values can be specified as unquoted alphanumeric+underscore sequences. If the value contains any non-alphanumeric (plus underscore) characters it should be enclosed in quotes (single or double, it does not matter). For settings that accept multiple values, separate each value to be supplied with a comma (and optional whitespace).
This concern is not limited to this page though, and should be applied elsewhere as is applicable.
I haven't tried to exhaustively enumerate when quoting is required, and probably the quoting rules should be centralized and the description simplified to:
The rules for when individual values must be quoted is described in Chapter 20.1.1. For settings that accept multiple values, separate each value with a comma and optional whitespace.
That chapter does indeed already explain for each type of value when quoting is required.
David J.