pg.ddx.io pgsql-docs@postgresql.org mailing list archive
help / color / mirror / Atom feedManua correction
7+ messages / 3 participants
[nested] [flat]
* Manua correction
@ 2021-07-13 02:24 PG Doc comments form <noreply@postgresql.org>
2021-07-15 21:36 ` Re: Manua correction Bruce Momjian <bruce@momjian.us>
0 siblings, 1 reply; 7+ messages in thread
From: PG Doc comments form @ 2021-07-13 02:24 UTC (permalink / raw)
To: pgsql-docs@lists.postgresql.org; +Cc: troy@frericks.us
The following documentation comment has been logged on the website:
Page: https://www.postgresql.org/docs/13/functions-string.html
Description:
Hopefully the referrer page was kept. I'm referring to the string functions
page that reads...
==
position ( substring text IN string text ) → integer
Returns starting index of specified substring within string, or zero if it's
not present.
position('om' in 'Thomas') → 3
==
should describe the situation where multiple occurrences of substring are in
the string text... might read...
Returns starting index of the first occurrence of the specified substring
within string, or zero if it's not present.
Troy.
#
^ permalink raw reply [nested|flat] 7+ messages in thread
* Re: Manua correction
2021-07-13 02:24 Manua correction PG Doc comments form <noreply@postgresql.org>
@ 2021-07-15 21:36 ` Bruce Momjian <bruce@momjian.us>
2021-07-16 03:12 ` Re: Manua correction Tom Lane <tgl@sss.pgh.pa.us>
0 siblings, 1 reply; 7+ messages in thread
From: Bruce Momjian @ 2021-07-15 21:36 UTC (permalink / raw)
To: troy@frericks.us; pgsql-docs@lists.postgresql.org
On Tue, Jul 13, 2021 at 02:24:01AM +0000, PG Doc comments form wrote:
> The following documentation comment has been logged on the website:
>
> Page: https://www.postgresql.org/docs/13/functions-string.html
> Description:
>
> Hopefully the referrer page was kept. I'm referring to the string functions
> page that reads...
> ==
> position ( substring text IN string text ) → integer
> Returns starting index of specified substring within string, or zero if it's
> not present.
> position('om' in 'Thomas') → 3
> ==
>
> should describe the situation where multiple occurrences of substring are in
> the string text... might read...
>
> Returns starting index of the first occurrence of the specified substring
> within string, or zero if it's not present.
Interesting. I see several cases where our docs are not clear we
process only the first match:
SELECT substring ('abc abd' FROM 'b.');
substring
-----------
bc
SELECT regexp_match('abc abd', 'b.');
regexp_match
--------------
{bc}
SELECT regexp_replace ('abc abf', 'b.', 'dd');
regexp_replace
----------------
add abf
SELECT strpos('abcb', 'b');
strpos
--------
2
SELECT position('a' IN 'abca');
position
----------
1
The attached patch improves these. I can backpatch this were
appropriate.
--
Bruce Momjian <bruce@momjian.us> https://momjian.us
EDB https://enterprisedb.com
If only the physical world exists, free will is an illusion.
Attachments:
[text/x-diff] substring.diff (4.2K, ../../20210715213623.GC14027@momjian.us/2-substring.diff)
download | inline diff:
diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index 6388385edc..4c8407148b 100644
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -2610,7 +2610,7 @@ repeat('Pg', 4) <returnvalue>PgPgPgPg</returnvalue>
<returnvalue>text</returnvalue>
</para>
<para>
- Extracts substring matching POSIX regular expression; see
+ Extracts the first substring matching POSIX regular expression; see
<xref linkend="functions-posix-regexp"/>.
</para>
<para>
@@ -2629,7 +2629,7 @@ repeat('Pg', 4) <returnvalue>PgPgPgPg</returnvalue>
<returnvalue>text</returnvalue>
</para>
<para>
- Extracts substring matching <acronym>SQL</acronym> regular expression;
+ Extracts the first substring matching <acronym>SQL</acronym> regular expression;
see <xref linkend="functions-similarto-regexp"/>. The first form has
been specified since SQL:2003; the second form was only in SQL:1999
and should be considered obsolete.
@@ -3109,7 +3109,7 @@ repeat('Pg', 4) <returnvalue>PgPgPgPg</returnvalue>
<returnvalue>text[]</returnvalue>
</para>
<para>
- Returns captured substring(s) resulting from the first match of a POSIX
+ Returns captured substring resulting from the first match of a POSIX
regular expression to the <parameter>string</parameter>; see
<xref linkend="functions-posix-regexp"/>.
</para>
@@ -3128,7 +3128,7 @@ repeat('Pg', 4) <returnvalue>PgPgPgPg</returnvalue>
<returnvalue>setof text[]</returnvalue>
</para>
<para>
- Returns captured substring(s) resulting from matching a POSIX regular
+ Returns captured substrings resulting from matching a POSIX regular
expression to the <parameter>string</parameter>; see
<xref linkend="functions-posix-regexp"/>.
</para>
@@ -3151,7 +3151,7 @@ repeat('Pg', 4) <returnvalue>PgPgPgPg</returnvalue>
<returnvalue>text</returnvalue>
</para>
<para>
- Replaces substring(s) matching a POSIX regular expression; see
+ Replaces substrings matching a POSIX regular expression; see
<xref linkend="functions-posix-regexp"/>.
</para>
<para>
@@ -3357,7 +3357,7 @@ repeat('Pg', 4) <returnvalue>PgPgPgPg</returnvalue>
<returnvalue>integer</returnvalue>
</para>
<para>
- Returns starting index of specified <parameter>substring</parameter>
+ Returns first starting index of specified <parameter>substring</parameter>
within <parameter>string</parameter>, or zero if it's not present.
(Same as <literal>position(<parameter>substring</parameter> in
<parameter>string</parameter>)</literal>, but note the reversed
@@ -3958,7 +3958,7 @@ SELECT format('Testing %3$s, %2$s, %s', 'one', 'two', 'three');
<returnvalue>integer</returnvalue>
</para>
<para>
- Returns starting index of specified <parameter>substring</parameter>
+ Returns first starting index of specified <parameter>substring</parameter>
within <parameter>bytes</parameter>, or zero if it's not present.
</para>
<para>
@@ -4885,7 +4885,7 @@ SELECT format('Testing %3$s, %2$s, %s', 'one', 'two', 'three');
<returnvalue>integer</returnvalue>
</para>
<para>
- Returns starting index of specified <parameter>substring</parameter>
+ Returns first starting index of specified <parameter>substring</parameter>
within <parameter>bits</parameter>, or zero if it's not present.
</para>
<para>
@@ -5511,7 +5511,7 @@ substring('foobar' similar '#"o_b#"%' escape '#') <lineannotation>NULL</linea
<replaceable>pattern</replaceable>)</function>, provides extraction of a
substring
that matches a POSIX regular expression pattern. It returns null if
- there is no match, otherwise the portion of the text that matched the
+ there is no match, otherwise the first portion of the text that matched the
pattern. But if the pattern contains any parentheses, the portion
of the text that matched the first parenthesized subexpression (the
one whose left parenthesis comes first) is
^ permalink raw reply [nested|flat] 7+ messages in thread
* Re: Manua correction
2021-07-13 02:24 Manua correction PG Doc comments form <noreply@postgresql.org>
2021-07-15 21:36 ` Re: Manua correction Bruce Momjian <bruce@momjian.us>
@ 2021-07-16 03:12 ` Tom Lane <tgl@sss.pgh.pa.us>
2021-07-19 14:23 ` Re: Manua correction Bruce Momjian <bruce@momjian.us>
0 siblings, 1 reply; 7+ messages in thread
From: Tom Lane @ 2021-07-16 03:12 UTC (permalink / raw)
To: Bruce Momjian <bruce@momjian.us>; +Cc: troy@frericks.us; pgsql-docs@lists.postgresql.org
Bruce Momjian <bruce@momjian.us> writes:
> Interesting. I see several cases where our docs are not clear we
> process only the first match:
At least two of these changes are flat out wrong. The places
that explicitly mention "substring(s)" are not doing so because
we failed to think about what that meant.
regards, tom lane
^ permalink raw reply [nested|flat] 7+ messages in thread
* Re: Manua correction
2021-07-13 02:24 Manua correction PG Doc comments form <noreply@postgresql.org>
2021-07-15 21:36 ` Re: Manua correction Bruce Momjian <bruce@momjian.us>
2021-07-16 03:12 ` Re: Manua correction Tom Lane <tgl@sss.pgh.pa.us>
@ 2021-07-19 14:23 ` Bruce Momjian <bruce@momjian.us>
2021-07-20 15:03 ` Re: Manua correction Tom Lane <tgl@sss.pgh.pa.us>
0 siblings, 1 reply; 7+ messages in thread
From: Bruce Momjian @ 2021-07-19 14:23 UTC (permalink / raw)
To: Tom Lane <tgl@sss.pgh.pa.us>; +Cc: troy@frericks.us; pgsql-docs@lists.postgresql.org
On Thu, Jul 15, 2021 at 11:12:38PM -0400, Tom Lane wrote:
> Bruce Momjian <bruce@momjian.us> writes:
> > Interesting. I see several cases where our docs are not clear we
> > process only the first match:
>
> At least two of these changes are flat out wrong. The places
> that explicitly mention "substring(s)" are not doing so because
> we failed to think about what that meant.
I really don't understand the use of "(s)" except in place where we are
really trying to point out the idea of one or multiple, and I don't see
that being significant in these cases --- can you clarify?
--
Bruce Momjian <bruce@momjian.us> https://momjian.us
EDB https://enterprisedb.com
If only the physical world exists, free will is an illusion.
^ permalink raw reply [nested|flat] 7+ messages in thread
* Re: Manua correction
2021-07-13 02:24 Manua correction PG Doc comments form <noreply@postgresql.org>
2021-07-15 21:36 ` Re: Manua correction Bruce Momjian <bruce@momjian.us>
2021-07-16 03:12 ` Re: Manua correction Tom Lane <tgl@sss.pgh.pa.us>
2021-07-19 14:23 ` Re: Manua correction Bruce Momjian <bruce@momjian.us>
@ 2021-07-20 15:03 ` Tom Lane <tgl@sss.pgh.pa.us>
2021-07-20 20:06 ` Re: Manua correction Bruce Momjian <bruce@momjian.us>
0 siblings, 1 reply; 7+ messages in thread
From: Tom Lane @ 2021-07-20 15:03 UTC (permalink / raw)
To: Bruce Momjian <bruce@momjian.us>; +Cc: troy@frericks.us; pgsql-docs@lists.postgresql.org
Bruce Momjian <bruce@momjian.us> writes:
> On Thu, Jul 15, 2021 at 11:12:38PM -0400, Tom Lane wrote:
>> At least two of these changes are flat out wrong. The places
>> that explicitly mention "substring(s)" are not doing so because
>> we failed to think about what that meant.
> I really don't understand the use of "(s)" except in place where we are
> really trying to point out the idea of one or multiple, and I don't see
> that being significant in these cases --- can you clarify?
See the example given for regexp_match:
regression=# select regexp_match('foobarbequebaz', '(bar)(beque)');
regexp_match
--------------
{bar,beque}
(1 row)
There's more than one parenthesized subpattern, so you get more than
one substring in the result. So I think that change is flat out
wrong.
The places where you changed "substring(s)" to "substrings" are maybe
not flat wrong, but I don't think they're improving the text either.
IIRC, in most of them you get one match if you didn't use the 'g'
flag, but possibly multiple matches if you did, and the "substring(s)"
wording is meant to allude to that without taking the space to spell
it out explicitly.
regards, tom lane
^ permalink raw reply [nested|flat] 7+ messages in thread
* Re: Manua correction
2021-07-13 02:24 Manua correction PG Doc comments form <noreply@postgresql.org>
2021-07-15 21:36 ` Re: Manua correction Bruce Momjian <bruce@momjian.us>
2021-07-16 03:12 ` Re: Manua correction Tom Lane <tgl@sss.pgh.pa.us>
2021-07-19 14:23 ` Re: Manua correction Bruce Momjian <bruce@momjian.us>
2021-07-20 15:03 ` Re: Manua correction Tom Lane <tgl@sss.pgh.pa.us>
@ 2021-07-20 20:06 ` Bruce Momjian <bruce@momjian.us>
2021-07-27 02:55 ` Re: Manua correction Bruce Momjian <bruce@momjian.us>
0 siblings, 1 reply; 7+ messages in thread
From: Bruce Momjian @ 2021-07-20 20:06 UTC (permalink / raw)
To: Tom Lane <tgl@sss.pgh.pa.us>; +Cc: troy@frericks.us; pgsql-docs@lists.postgresql.org
On Tue, Jul 20, 2021 at 11:03:09AM -0400, Tom Lane wrote:
> Bruce Momjian <bruce@momjian.us> writes:
> > I really don't understand the use of "(s)" except in place where we are
> > really trying to point out the idea of one or multiple, and I don't see
> > that being significant in these cases --- can you clarify?
>
> See the example given for regexp_match:
>
> regression=# select regexp_match('foobarbequebaz', '(bar)(beque)');
> regexp_match
> --------------
> {bar,beque}
> (1 row)
>
> There's more than one parenthesized subpattern, so you get more than
> one substring in the result. So I think that change is flat out
> wrong.
>
> The places where you changed "substring(s)" to "substrings" are maybe
> not flat wrong, but I don't think they're improving the text either.
> IIRC, in most of them you get one match if you didn't use the 'g'
> flag, but possibly multiple matches if you did, and the "substring(s)"
> wording is meant to allude to that without taking the space to spell
> it out explicitly.
I see what you mean --- there can be multiple capture groups, and
multiple match processing if 'g' is used. I think the text using "(s)"
is too complex, so I spelled out the use 'g' and clarified the case of
multiple groups in a single regex.
Updated patch attached, and I used a larger line context around the
changes to clarify what was being modified.
--
Bruce Momjian <bruce@momjian.us> https://momjian.us
EDB https://enterprisedb.com
If only the physical world exists, free will is an illusion.
Attachments:
[application/gzip] substring.diff.gz (1.8K, ../../20210720200617.GA27025@momjian.us/2-substring.diff.gz)
download
^ permalink raw reply [nested|flat] 7+ messages in thread
* Re: Manua correction
2021-07-13 02:24 Manua correction PG Doc comments form <noreply@postgresql.org>
2021-07-15 21:36 ` Re: Manua correction Bruce Momjian <bruce@momjian.us>
2021-07-16 03:12 ` Re: Manua correction Tom Lane <tgl@sss.pgh.pa.us>
2021-07-19 14:23 ` Re: Manua correction Bruce Momjian <bruce@momjian.us>
2021-07-20 15:03 ` Re: Manua correction Tom Lane <tgl@sss.pgh.pa.us>
2021-07-20 20:06 ` Re: Manua correction Bruce Momjian <bruce@momjian.us>
@ 2021-07-27 02:55 ` Bruce Momjian <bruce@momjian.us>
0 siblings, 0 replies; 7+ messages in thread
From: Bruce Momjian @ 2021-07-27 02:55 UTC (permalink / raw)
To: Tom Lane <tgl@sss.pgh.pa.us>; +Cc: troy@frericks.us; pgsql-docs@lists.postgresql.org
On Tue, Jul 20, 2021 at 04:06:17PM -0400, Bruce Momjian wrote:
> On Tue, Jul 20, 2021 at 11:03:09AM -0400, Tom Lane wrote:
> > The places where you changed "substring(s)" to "substrings" are maybe
> > not flat wrong, but I don't think they're improving the text either.
> > IIRC, in most of them you get one match if you didn't use the 'g'
> > flag, but possibly multiple matches if you did, and the "substring(s)"
> > wording is meant to allude to that without taking the space to spell
> > it out explicitly.
>
> I see what you mean --- there can be multiple capture groups, and
> multiple match processing if 'g' is used. I think the text using "(s)"
> is too complex, so I spelled out the use 'g' and clarified the case of
> multiple groups in a single regex.
>
> Updated patch attached, and I used a larger line context around the
> changes to clarify what was being modified.
Patch applied back to PG 13 --- before that, the text supplied as much
more minimal.
--
Bruce Momjian <bruce@momjian.us> https://momjian.us
EDB https://enterprisedb.com
If only the physical world exists, free will is an illusion.
^ permalink raw reply [nested|flat] 7+ messages in thread
end of thread, other threads:[~2021-07-27 02:55 UTC | newest]
Thread overview: 7+ messages (download: mbox mbox.gz follow: Atom feed)
-- links below jump to the message on this page --
2021-07-13 02:24 Manua correction PG Doc comments form <noreply@postgresql.org>
2021-07-15 21:36 ` Bruce Momjian <bruce@momjian.us>
2021-07-16 03:12 ` Tom Lane <tgl@sss.pgh.pa.us>
2021-07-19 14:23 ` Bruce Momjian <bruce@momjian.us>
2021-07-20 15:03 ` Tom Lane <tgl@sss.pgh.pa.us>
2021-07-20 20:06 ` Bruce Momjian <bruce@momjian.us>
2021-07-27 02:55 ` Bruce Momjian <bruce@momjian.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