Thread: Typo in description of PROGRAM parameter for the COPY command

The following documentation comment has been logged on the website:

Page: https://www.postgresql.org/docs/14/sql-copy.html
Description:

On this page https://www.postgresql.org/docs/current/sql-copy.html the
description of the PROGRAM parameter for the COPY command has the following
sentence with a minor typo:

    > ...so if you need to pass any arguments to shell command that come
from an untrusted source...

The "to shell command that come" part should be changed so it either reads
like this:

    > ...so if you need to pass any arguments to a shell command that comes
from an untrusted source...

...or it reads like this:

    > ...so if you need to pass any arguments to shell commands that come
from an untrusted source...

Many thanks,
Eric Mutta.

> On 21 Aug 2022, at 03:31, PG Doc comments form <noreply@postgresql.org> wrote:

>> ...so if you need to pass any arguments to shell command that come
> from an untrusted source...
>
> The "to shell command that come" part should be changed so it either reads
> like this:
>
>> ...so if you need to pass any arguments to a shell command that comes
> from an untrusted source...
>
> ...or it reads like this:
>
>> ...so if you need to pass any arguments to shell commands that come
> from an untrusted source...

Not being a native english speaker, but since we're already referring to "the
command" in the sentence it seems more natural to me to change to "the shell
command".

--
Daniel Gustafsson        https://vmware.com/

Daniel Gustafsson <daniel@yesql.se> writes:
> On 21 Aug 2022, at 03:31, PG Doc comments form <noreply@postgresql.org> wrote:
>> ...so if you need to pass any arguments to shell command that come
>> from an untrusted source...
>>
>> The "to shell command that come" part should be changed so it either reads
>> like this:
>>
>> ...so if you need to pass any arguments to a shell command that comes
>> from an untrusted source...
>>
>> ...or it reads like this:
>>
>> ...so if you need to pass any arguments to shell commands that come
>> from an untrusted source...

> Not being a native english speaker, but since we're already referring to "the
> command" in the sentence it seems more natural to me to change to "the shell
> command".

Hmm ... to me the main problem with this fragment is that it's not
entirely clear whether we're speaking of untrusted arguments or an
untrusted shell command, ie which one is the antecedent of "that".
The proposed variants seem to make that worse not better.  I suggest
rephrasing like

... so if you need to include any shell command arguments that come from
an untrusted source, you must ...

Or maybe even better, just drop "shell command" from that phrase
altogether.

Probably also s/passing/including/ in the next sentence.

            regards, tom lane

> On 21 Aug 2022, at 20:48, Tom Lane <tgl@sss.pgh.pa.us> wrote:
>
> Daniel Gustafsson <daniel@yesql.se> writes:
>> On 21 Aug 2022, at 03:31, PG Doc comments form <noreply@postgresql.org> wrote:
>>> ...so if you need to pass any arguments to shell command that come
>>> from an untrusted source...
>>>
>>> The "to shell command that come" part should be changed so it either reads
>>> like this:
>>>
>>> ...so if you need to pass any arguments to a shell command that comes
>>> from an untrusted source...
>>>
>>> ...or it reads like this:
>>>
>>> ...so if you need to pass any arguments to shell commands that come
>>> from an untrusted source...
>
>> Not being a native english speaker, but since we're already referring to "the
>> command" in the sentence it seems more natural to me to change to "the shell
>> command".
>
> Hmm ... to me the main problem with this fragment is that it's not
> entirely clear whether we're speaking of untrusted arguments or an
> untrusted shell command, ie which one is the antecedent of "that".
> The proposed variants seem to make that worse not better. I suggest
> rephrasing like
>
> ... so if you need to include any shell command arguments that come from
> an untrusted source, you must ...
>
> Or maybe even better, just drop "shell command" from that phrase
> altogether.
>
> Probably also s/passing/including/ in the next sentence.

Agreed, those suggestions make it better.

Skimming the page I noticed that we wrap CSV in <literal/> in all but a few
places, which seemed randomly "chosen".  Another sentence which stood out to me
was this one on FREEZE:

    "This violates the normal rules of MVCC visibility and users specifying
    should be aware of the potential problems this might cause."

The use of "specifying" seems odd to me, removing it makes it read clearer
IM-non-native-O.

The attached includes all the above suggestions.

--
Daniel Gustafsson        https://vmware.com/

Daniel Gustafsson <daniel@yesql.se> writes:
> Skimming the page I noticed that we wrap CSV in <literal/> in all but a few
> places, which seemed randomly "chosen".  Another sentence which stood out to me
> was this one on FREEZE:

>     "This violates the normal rules of MVCC visibility and users specifying
>     should be aware of the potential problems this might cause."

> The use of "specifying" seems odd to me, removing it makes it read clearer
> IM-non-native-O.

I suppose the author was aiming at "specifying it", but I agree that
just dropping "specifying" works fine with fewer words.

> The attached includes all the above suggestions.

LGTM.

            regards, tom lane