reserved characters section in docs could use some clarification

[robx]

Environment

• PostgreSQL version: 10.10
• PostgREST version: 6.0.0
• Operating system: Linux

Description of issue

I find the documentation on escaping reserved characters to be quite confusing. I was trying to filter using in and parentheses, e.g. finally column=in.(%22(parenthesized)%22).

Some points of confusion:

• is it about the filter syntax containing reserved characters, or the filter value? (e.g. I was expecting a consisten way of quoting, but it turns out that =eq. doesn't need any escaping)
• is it about quoting individual reserved characters, or whole strings? (initially I thought it should be fine to quote reserved characters one by one, e.g. %22(%22parenthesized%22)%22.

[steve-chavez]

It's about quoting whole strings, you're right in that the wording of that section implies individual characters.

Also, it depends on the operator. For example the filter values of eq and fts don't need quoting for parens/commas. Because in has parens/commas as part of its syntax it does need quoting for using them in the filter value.

I'll move the issue to docs. I'd gladly review a PR for clarification.

[wolfgangwalther]

We have PostgREST/postgrest#1943 now, so instead of explaining our inconsistent quoting rules, we'd rather standardize them.