Re: libpq parameter parsing problem

On Tue, Jan 14, 2020 at 7:40 PM Michael Paquier <michael(at)paquier(dot)xyz> wrote:

> On Tue, Jan 14, 2020 at 06:52:07PM -0700, David G. Johnston wrote:
> > I would probably choose to move the example for the options parameters to
> > the "Parameter Key Words" options section:
>
> I think that this would be inconsistent with the rest, as that's a URI
> and all the other examples are there. I agree with the feeling of
> Alvaro upthread that we could do a better effort with the handling of
> the examples in this section, but it is quite unclear to me if that
> would actually bring more clarity to the whole, and that's not really
> the job of this patch.
>
>
My rationale is more since none of the other options have structural parts
that require escaping, and rarely do the values themselves require
escaping, that tossing that single example for a seldom-used option into
the middle of the "usage examples" section doesn't really fit. What the
example does is clarify a specific combination of factors, URI and
"options", that require special attention. I'd rather bury that special
case in the documentation for options then explain it in detail in the
generic URI section - the structural elements involved are already
mentioned in the options section and this just clarifies how they are
written in the URI situation. Its not a strong opinion but I don't think
adding it there while leaving the other common compound usage examples as a
whole above is a misplacement - "options" is special and can very well have
special treatment. It will be found by those that need to know about it.

In any case I do think that calling out the fact that "structural" pieces
of the option parameter need to be encoded should happen regardless of the
placement of the example that demonstrates those structural elements being
encoded. For the rest some people using unusual values may have to deal
with escaping - for users of "options" they are going to and their
attention should be drawn to that fact to help avoid the confusion that
prompted this patch.

David J.