Re: 'value' has special behaviour in alter system

On Thu, Dec 15, 2022 at 4:45 AM PG Doc comments form <noreply(at)postgresql(dot)org>
wrote:

> 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.