Special Chars in Param Settings - Mailing list pgsql-docs

The following documentation comment has been logged on the website:

Page: https://www.postgresql.org/docs/10/static/config-setting.html
Description:

        I have had a hard time interpreting Postgres Doc when it comes to
special characters in the configuration file, especially special characters
in file paths.

Why the concern?:
    Lately, I've been trying to implement some custom data types and a
function. A Haskell program developer would use them to write a Postgres
config file in a type-checked manner. My goal with that is to reduce the
possibility of typos and to free the developer from any escaping/quoting
duties. My code would convert values of special types into character stings
"under the hood". To do this conversion, I must have a rock-solid
understanding of what characters are special and where, and, how to escape
them, where that is possible. And where it is not, throw an error if given
an unsupported character.

Sections involved:

    High Level: 19.1.1 & 19.1.2 for PostgreSQL 10

    Low Level: 19.3.1 & 19.11.1 for PostgreSQL 10

    Note: the equivalent sections of doc for older versions of PostgreSQL are
affected as well. The remainder of this report assumes PostgreSQL 10 doc.

1)      It would be helpful to have a comment in 19.1.1 saying that each
parameter dictates which characters are special for that parameter and how
to escape them, if it is possible to escape them. For example,
unix_socket_directories uses double quotes, while most others do not.
Further, the dollar sign has special meaning for search_path, but I don't
think any other parameters treat it specially.
    Initially, the lack of this clarifying comment was confusing for me: 19.1.1
and 19.1.2 speak as though there is one set of rules for interpreting
special characters, not that each parameter gets to have its own.

2)    In 19.1.1, I believe it'd be more clear to say "replacing each single
quote with two consecutive single quotes" than to say "doubling any single
quotes", since the latter and current wording may be interpreted as
replacing single quotes with double quotes. 

3)    It is unclear why "$user" is placed in double quotes in the example given
in 19.1.2.
    Nowhere in the vicinity of this example is the dollar sign documented as a
special character, and nor are double quotes. Further, in 19.11.1, it does
not mention any need for wrapping $user in double quotes.

4)    It would also be helpful to be more explicit about which characters are
supported under which parameters and which are not. For example, it is legal
in Linux to have a double quote in a file path. But the
unix_socket_directories doc mentions no way of escaping a double quote
within double quotes. So I can only assume that the double quote is not
(fully?) supported for that parameter, at least not officially. I'd rather
be told explicitly. Please also consider backslashes, which are also legal
characters in Linux file names.
    I'd also like to be more confident that asterisks are supported in file
names, and not worry that maybe all parameters take that character to be
special. This goes back to point #1. With that clarifying comment, I would
know for sure that each parameter dictates its own interpretation rules
independently of the other parameters, except for the single quote rules
that all are subject to.

5)    For unix_socket_directories, if I have 'foo"bar' (single quotes
included), is that illegal for not closing the double quote, or is the
double quote taken literally? The documentation does not make this clear.

6)    And what about '"foo'sbar"'? Is the single quote (apostrophe) before the
"s" interpreted to close the single quote before foo, or is it taken
literally for being in the double quotes? If I were to take the doc
literally, then, according to 19.1.1, the single quote needs to be doubled,
since it is between single quotes (ignoring the fact that it is also between
double quotes).
    However, I have a hard time believing that is the intended meaning here,
given the intuitive meaning of double quotes. A clarifying comment in
unix_socket_directories doc about literal single quotes between double
quotes and literal double quotes between single quotes would be very
helpful. This would need a comment in 19.1.1 saying that single quotes
between double quotes (which are themselves between single quotes) are the
exception to the rule: there, single quotes do not need to be escaped in any
way (no doubling, no backslash-escaping).


Thank you for your time,
Jake Thomas