pg.ddx.io pgsql-docs@postgresql.org mailing list archive
help / color / mirror / Atom feedTypo in description of PROGRAM parameter for the COPY command
5+ messages / 3 participants
[nested] [flat]
* Typo in description of PROGRAM parameter for the COPY command
@ 2022-08-21 01:31 PG Doc comments form <noreply@postgresql.org>
0 siblings, 1 reply; 5+ messages in thread
From: PG Doc comments form @ 2022-08-21 01:31 UTC (permalink / raw)
To: pgsql-docs@lists.postgresql.org; +Cc: eric.mutta@gmail.com
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.
^ permalink raw reply [nested|flat] 5+ messages in thread
* Re: Typo in description of PROGRAM parameter for the COPY command
@ 2022-08-21 18:29 Daniel Gustafsson <daniel@yesql.se>
parent: PG Doc comments form <noreply@postgresql.org>
0 siblings, 1 reply; 5+ messages in thread
From: Daniel Gustafsson @ 2022-08-21 18:29 UTC (permalink / raw)
To: eric.mutta@gmail.com; pgsql-docs@lists.postgresql.org
> 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/
^ permalink raw reply [nested|flat] 5+ messages in thread
* Re: Typo in description of PROGRAM parameter for the COPY command
@ 2022-08-21 18:48 Tom Lane <tgl@sss.pgh.pa.us>
parent: Daniel Gustafsson <daniel@yesql.se>
0 siblings, 1 reply; 5+ messages in thread
From: Tom Lane @ 2022-08-21 18:48 UTC (permalink / raw)
To: Daniel Gustafsson <daniel@yesql.se>; +Cc: eric.mutta@gmail.com; pgsql-docs@lists.postgresql.org
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
^ permalink raw reply [nested|flat] 5+ messages in thread
* Re: Typo in description of PROGRAM parameter for the COPY command
@ 2022-08-21 19:07 Daniel Gustafsson <daniel@yesql.se>
parent: Tom Lane <tgl@sss.pgh.pa.us>
0 siblings, 1 reply; 5+ messages in thread
From: Daniel Gustafsson @ 2022-08-21 19:07 UTC (permalink / raw)
To: Tom Lane <tgl@sss.pgh.pa.us>; +Cc: eric.mutta@gmail.com; pgsql-docs@lists.postgresql.org
> 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/
Attachments:
[application/octet-stream] copy.diff (2.7K, ../../C032C9AB-21E4-440C-ADC8-9AC7412C3D19@yesql.se/2-copy.diff)
download | inline diff:
diff --git a/doc/src/sgml/ref/copy.sgml b/doc/src/sgml/ref/copy.sgml
index 63afa0d97e..c25b52d0cb 100644
--- a/doc/src/sgml/ref/copy.sgml
+++ b/doc/src/sgml/ref/copy.sgml
@@ -157,10 +157,10 @@ COPY { <replaceable class="parameter">table_name</replaceable> [ ( <replaceable
</para>
<para>
Note that the command is invoked by the shell, so if you need to pass
- any arguments to shell command that come from an untrusted source, you
+ any arguments that come from an untrusted source, you
must be careful to strip or escape any special characters that might
have a special meaning for the shell. For security reasons, it is best
- to use a fixed command string, or at least avoid passing any user input
+ to use a fixed command string, or at least avoid including any user input
in it.
</para>
</listitem>
@@ -227,7 +227,7 @@ COPY { <replaceable class="parameter">table_name</replaceable> [ ( <replaceable
<para>
Note that all other sessions will immediately be able to see the data
once it has been successfully loaded. This violates the normal rules
- of MVCC visibility and users specifying should be aware of the
+ of MVCC visibility and users should be aware of the
potential problems this might cause.
</para>
</listitem>
@@ -708,7 +708,7 @@ COPY <replaceable class="parameter">count</replaceable>
Separated Value (<literal>CSV</literal>) file format used by many other
programs, such as spreadsheets. Instead of the escaping rules used by
<productname>PostgreSQL</productname>'s standard text format, it
- produces and recognizes the common CSV escaping mechanism.
+ produces and recognizes the common <literal>CSV</literal> escaping mechanism.
</para>
<para>
@@ -766,7 +766,7 @@ COPY <replaceable class="parameter">count</replaceable>
<note>
<para>
- CSV format will both recognize and produce CSV files with quoted
+ <literal>CSV</literal> format will both recognize and produce <literal>CSV</literal> files with quoted
values containing embedded carriage returns and line feeds. Thus
the files are not strictly one line per table row like text-format
files.
@@ -775,7 +775,7 @@ COPY <replaceable class="parameter">count</replaceable>
<note>
<para>
- Many programs produce strange and occasionally perverse CSV files,
+ Many programs produce strange and occasionally perverse <literal>CSV</literal> files,
so the file format is more a convention than a standard. Thus you
might encounter some files that cannot be imported using this
mechanism, and <command>COPY</command> might produce files that other
^ permalink raw reply [nested|flat] 5+ messages in thread
* Re: Typo in description of PROGRAM parameter for the COPY command
@ 2022-08-21 19:14 Tom Lane <tgl@sss.pgh.pa.us>
parent: Daniel Gustafsson <daniel@yesql.se>
0 siblings, 0 replies; 5+ messages in thread
From: Tom Lane @ 2022-08-21 19:14 UTC (permalink / raw)
To: Daniel Gustafsson <daniel@yesql.se>; +Cc: eric.mutta@gmail.com; pgsql-docs@lists.postgresql.org
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
^ permalink raw reply [nested|flat] 5+ messages in thread
end of thread, other threads:[~2022-08-21 19:14 UTC | newest]
Thread overview: 5+ messages (download: mbox mbox.gz follow: Atom feed)
-- links below jump to the message on this page --
2022-08-21 01:31 Typo in description of PROGRAM parameter for the COPY command PG Doc comments form <noreply@postgresql.org>
2022-08-21 18:29 ` Daniel Gustafsson <daniel@yesql.se>
2022-08-21 18:48 ` Tom Lane <tgl@sss.pgh.pa.us>
2022-08-21 19:07 ` Daniel Gustafsson <daniel@yesql.se>
2022-08-21 19:14 ` Tom Lane <tgl@sss.pgh.pa.us>
This inbox is served by DDX for PostgreSQL; see mirroring instructions
for how to clone and mirror all data and code used for this inbox