Re: libpq parameter parsing problem

--0000000000000ce9b4059c25ac14
Content-Type: text/plain; charset="UTF-8"

On Tue, Jan 14, 2020 at 7:40 PM Michael Paquier <[email protected]> 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.

--0000000000000ce9b4059c25ac14
Content-Type: text/html; charset="UTF-8"
Content-Transfer-Encoding: quoted-printable

<div dir=3D"ltr"><div dir=3D"ltr"><div class=3D"gmail_default" style=3D"fon=
t-family:arial,helvetica,sans-serif"><span style=3D"font-family:Arial,Helve=
tica,sans-serif">On Tue, Jan 14, 2020 at 7:40 PM Michael Paquier &lt;<a hre=
f=3D"mailto:[email protected]">[email protected]</a>&gt; wrote:</span><=
br></div></div><div class=3D"gmail_quote"><blockquote class=3D"gmail_quote"=
 style=3D"margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);p=
adding-left:1ex">On Tue, Jan 14, 2020 at 06:52:07PM -0700, David G. Johnsto=
n wrote:<br>
&gt; I would probably choose to move the example for the options parameters=
 to<br>
&gt; the &quot;Parameter Key Words&quot; options section:<br>
<br>
I think that this would be inconsistent with the rest, as that&#39;s a URI<=
br>
and all the other examples are there.=C2=A0 I agree with the feeling of<br>
Alvaro upthread that we could do a better effort with the handling of<br>
the examples in this section, but it is quite unclear to me if that<br>
would actually bring more clarity to the whole, and that&#39;s not really<b=
r>
the job of this patch.<br><br></blockquote><div><br></div><div class=3D"gma=
il_default" style=3D"font-family:arial,helvetica,sans-serif">My rationale i=
s more since none of the other options have structural parts that require e=
scaping, and rarely do the values themselves require escaping, that tossing=
 that single example for a seldom-used option into the middle of the &quot;=
usage examples&quot; section doesn&#39;t really fit.=C2=A0 What the example=
 does is clarify a specific combination of factors, URI and &quot;options&q=
uot;, that require special attention.=C2=A0 I&#39;d rather bury that specia=
l case in the documentation for options then explain it in detail in the ge=
neric 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.=C2=A0 Its not a strong opinion but I don&#39;t think adding =
it there while leaving the other common compound usage examples as a whole =
above is a misplacement - &quot;options&quot; is special and can very well =
have special treatment.=C2=A0 It will be found by those that need to know a=
bout it.</div><div class=3D"gmail_default" style=3D"font-family:arial,helve=
tica,sans-serif"><br></div><div class=3D"gmail_default" style=3D"font-famil=
y:arial,helvetica,sans-serif">In any case I do think that calling out the f=
act that &quot;structural&quot; pieces of the option parameter need to be e=
ncoded should happen regardless of the placement of the example that demons=
trates those structural elements being encoded.=C2=A0 For the rest some peo=
ple using unusual values may have to deal with escaping - for users of &quo=
t;options&quot; they are going to and their attention should be drawn to th=
at fact to help avoid the confusion that prompted this patch.</div><div cla=
ss=3D"gmail_default" style=3D"font-family:arial,helvetica,sans-serif"><br><=
/div><div class=3D"gmail_default" style=3D"font-family:arial,helvetica,sans=
-serif">David J.</div><div class=3D"gmail_default" style=3D"font-family:ari=
al,helvetica,sans-serif"><br></div></div></div>

--0000000000000ce9b4059c25ac14--