pg.ddx.io pgsql-docs@postgresql.org mailing list archive
help / color / mirror / Atom feedUnclear Wording
8+ messages / 4 participants
[nested] [flat]
* Unclear Wording
@ 2022-06-06 22:11 PG Doc comments form <noreply@postgresql.org>
0 siblings, 1 reply; 8+ messages in thread
From: PG Doc comments form @ 2022-06-06 22:11 UTC (permalink / raw)
To: pgsql-docs@lists.postgresql.org; +Cc: pg@kirasoft.com
The following documentation comment has been logged on the website:
Page: https://www.postgresql.org/docs/14/plpgsql-errors-and-messages.html
Description:
Dear Sirs,
From the page on RAISE ...
I read this 3 times and tripped over "write a format", which should be use
(or specify) a format string ...
Current:
After level if any, you can write a format (which must be a simple string
literal, not an expression). The format string specifies the error message
text to be reported.
Suggested Rewrite:
After level if any, you can specify a format string (which must be a simple
string literal, not an expression). The format string specifies the error
message text to be reported.
PS: Thank you for some of the best documentation ever published!
The link, just in case:
https://www.postgresql.org/docs/14/plpgsql-errors-and-messages.html
^ permalink raw reply [nested|flat] 8+ messages in thread
* Re: Unclear Wording
@ 2022-06-08 00:15 Bruce Momjian <bruce@momjian.us>
parent: PG Doc comments form <noreply@postgresql.org>
0 siblings, 2 replies; 8+ messages in thread
From: Bruce Momjian @ 2022-06-08 00:15 UTC (permalink / raw)
To: pg@kirasoft.com; pgsql-docs@lists.postgresql.org
On Mon, Jun 6, 2022 at 10:11:54PM +0000, PG Doc comments form wrote:
> The following documentation comment has been logged on the website:
>
> Page: https://www.postgresql.org/docs/14/plpgsql-errors-and-messages.html
> Description:
>
> Dear Sirs,
> From the page on RAISE ...
> I read this 3 times and tripped over "write a format", which should be use
> (or specify) a format string ...
>
> Current:
> After level if any, you can write a format (which must be a simple string
> literal, not an expression). The format string specifies the error message
> text to be reported.
>
> Suggested Rewrite:
> After level if any, you can specify a format string (which must be a simple
> string literal, not an expression). The format string specifies the error
> message text to be reported.
Good idea, patch attached.
--
Bruce Momjian <bruce@momjian.us> https://momjian.us
EDB https://enterprisedb.com
Indecision is a decision. Inaction is an action. Mark Batterson
Attachments:
[text/x-diff] format.diff (611B, ../../Yp%2FqFiNg6VapoZeZ@momjian.us/2-format.diff)
download | inline diff:
diff --git a/doc/src/sgml/plpgsql.sgml b/doc/src/sgml/plpgsql.sgml
index d9a74896d5..cedc11ab1f 100644
--- a/doc/src/sgml/plpgsql.sgml
+++ b/doc/src/sgml/plpgsql.sgml
@@ -3778,7 +3778,7 @@ RAISE ;
<para>
After <replaceable class="parameter">level</replaceable> if any,
- you can write a <replaceable class="parameter">format</replaceable>
+ you can specify a <replaceable class="parameter">format string</replaceable>
(which must be a simple string literal, not an expression). The
format string specifies the error message text to be reported.
The format string can be followed
^ permalink raw reply [nested|flat] 8+ messages in thread
* Re: Unclear Wording
@ 2022-06-08 02:34 Laurenz Albe <laurenz.albe@cybertec.at>
parent: Bruce Momjian <bruce@momjian.us>
1 sibling, 0 replies; 8+ messages in thread
From: Laurenz Albe @ 2022-06-08 02:34 UTC (permalink / raw)
To: Bruce Momjian <bruce@momjian.us>; pg@kirasoft.com; pgsql-docs@lists.postgresql.org
On Tue, 2022-06-07 at 20:15 -0400, Bruce Momjian wrote:
> > Page: https://www.postgresql.org/docs/14/plpgsql-errors-and-messages.html
> > Description:
> >
> > Dear Sirs,
> > From the page on RAISE ...
> > I read this 3 times and tripped over "write a format", which should be use
> > (or specify) a format string ...
> >
> > Current:
> > After level if any, you can write a format (which must be a simple string
> > literal, not an expression). The format string specifies the error message
> > text to be reported.
> >
> > Suggested Rewrite:
> > After level if any, you can specify a format string (which must be a simple
> > string literal, not an expression). The format string specifies the error
> > message text to be reported.
>
> Good idea, patch attached.
+1
Yours,
Laurenz Albe
^ permalink raw reply [nested|flat] 8+ messages in thread
* Re: Unclear Wording
@ 2022-06-08 17:49 Peter Eisentraut <peter.eisentraut@enterprisedb.com>
parent: Bruce Momjian <bruce@momjian.us>
1 sibling, 1 reply; 8+ messages in thread
From: Peter Eisentraut @ 2022-06-08 17:49 UTC (permalink / raw)
To: Bruce Momjian <bruce@momjian.us>; pg@kirasoft.com; pgsql-docs@lists.postgresql.org
On 08.06.22 02:15, Bruce Momjian wrote:
> - you can write a <replaceable class="parameter">format</replaceable>
> + you can specify a <replaceable class="parameter">format string</replaceable>
The "format" refers to the earlier synopsis, so that should be changed,
too. Or put the "string" outside the <replaceable> element.
^ permalink raw reply [nested|flat] 8+ messages in thread
* Re: Unclear Wording
@ 2022-06-08 19:07 Bruce Momjian <bruce@momjian.us>
parent: Peter Eisentraut <peter.eisentraut@enterprisedb.com>
0 siblings, 1 reply; 8+ messages in thread
From: Bruce Momjian @ 2022-06-08 19:07 UTC (permalink / raw)
To: Peter Eisentraut <peter.eisentraut@enterprisedb.com>; +Cc: pg@kirasoft.com; pgsql-docs@lists.postgresql.org
On Wed, Jun 8, 2022 at 07:49:07PM +0200, Peter Eisentraut wrote:
> On 08.06.22 02:15, Bruce Momjian wrote:
> > - you can write a <replaceable class="parameter">format</replaceable>
> > + you can specify a <replaceable class="parameter">format string</replaceable>
>
> The "format" refers to the earlier synopsis, so that should be changed, too.
> Or put the "string" outside the <replaceable> element.
I thought about moving it outside, so I did that in this patch.
--
Bruce Momjian <bruce@momjian.us> https://momjian.us
EDB https://enterprisedb.com
Indecision is a decision. Inaction is an action. Mark Batterson
Attachments:
[text/x-diff] format.diff (611B, ../../YqDzVYf+eltyVfAk@momjian.us/2-format.diff)
download | inline diff:
diff --git a/doc/src/sgml/plpgsql.sgml b/doc/src/sgml/plpgsql.sgml
index d9a74896d5..cf387dfc3f 100644
--- a/doc/src/sgml/plpgsql.sgml
+++ b/doc/src/sgml/plpgsql.sgml
@@ -3778,7 +3778,7 @@ RAISE ;
<para>
After <replaceable class="parameter">level</replaceable> if any,
- you can write a <replaceable class="parameter">format</replaceable>
+ you can specify a <replaceable class="parameter">format</replaceable> string
(which must be a simple string literal, not an expression). The
format string specifies the error message text to be reported.
The format string can be followed
^ permalink raw reply [nested|flat] 8+ messages in thread
* Re: Unclear Wording
@ 2022-06-22 21:00 Bruce Momjian <bruce@momjian.us>
parent: Bruce Momjian <bruce@momjian.us>
0 siblings, 0 replies; 8+ messages in thread
From: Bruce Momjian @ 2022-06-22 21:00 UTC (permalink / raw)
To: Peter Eisentraut <peter.eisentraut@enterprisedb.com>; +Cc: pg@kirasoft.com; pgsql-docs@lists.postgresql.org
On Wed, Jun 8, 2022 at 03:07:01PM -0400, Bruce Momjian wrote:
> On Wed, Jun 8, 2022 at 07:49:07PM +0200, Peter Eisentraut wrote:
> > On 08.06.22 02:15, Bruce Momjian wrote:
> > > - you can write a <replaceable class="parameter">format</replaceable>
> > > + you can specify a <replaceable class="parameter">format string</replaceable>
> >
> > The "format" refers to the earlier synopsis, so that should be changed, too.
> > Or put the "string" outside the <replaceable> element.
>
> I thought about moving it outside, so I did that in this patch.
Patch applied to all supported versions of Postgres.
--
Bruce Momjian <bruce@momjian.us> https://momjian.us
EDB https://enterprisedb.com
Indecision is a decision. Inaction is an action. Mark Batterson
^ permalink raw reply [nested|flat] 8+ messages in thread
* Unclear wording
@ 2025-07-11 16:12 PG Doc comments form <noreply@postgresql.org>
0 siblings, 1 reply; 8+ messages in thread
From: PG Doc comments form @ 2025-07-11 16:12 UTC (permalink / raw)
To: pgsql-docs@lists.postgresql.org; +Cc: postgresql@mackler.email
The following documentation comment has been logged on the website:
Page: https://www.postgresql.org/docs/17/ddl-schemas.html
Description:
In §5.10.3 these two sentences seem inconsistent:
> When objects are referenced in any other context without schema
qualification...the search path is traversed until a matching object is
found. Therefore, in the default configuration, any unqualified access again
can only refer to the public schema.
Either unqualified access can refer to any schema in the search path,
because the search path is traversed until a matching object is found, or
else unqualified access can only refer to the public schema because the
search path will not be traversed looking in other schemas for a matching
object, but both of those possibilities conflict with one or the other of
the sentences quoted from the manual.
Obviously I'm missing something; I don't know which of the two sentences
quoted from the manual to believe, or if I am to understand both are true,
what I am misunderstanding about their meaning.
^ permalink raw reply [nested|flat] 8+ messages in thread
* Re: Unclear wording
@ 2025-07-12 10:19 Laurenz Albe <laurenz.albe@cybertec.at>
parent: PG Doc comments form <noreply@postgresql.org>
0 siblings, 0 replies; 8+ messages in thread
From: Laurenz Albe @ 2025-07-12 10:19 UTC (permalink / raw)
To: postgresql@mackler.email; pgsql-docs@lists.postgresql.org
On Fri, 2025-07-11 at 16:12 +0000, PG Doc comments form wrote:
> Page: https://www.postgresql.org/docs/17/ddl-schemas.html
> Description:
>
> In §5.10.3 these two sentences seem inconsistent:
>
> > When objects are referenced in any other context without schema
> qualification...the search path is traversed until a matching object is
> found. Therefore, in the default configuration, any unqualified access again
> can only refer to the public schema.
>
> Either unqualified access can refer to any schema in the search path,
> because the search path is traversed until a matching object is found, or
> else unqualified access can only refer to the public schema because the
> search path will not be traversed looking in other schemas for a matching
> object, but both of those possibilities conflict with one or the other of
> the sentences quoted from the manual.
>
> Obviously I'm missing something; I don't know which of the two sentences
> quoted from the manual to believe, or if I am to understand both are true,
> what I am misunderstanding about their meaning.
I don't see an inconsistency. The key phrase is "in the default configuration".
The default value for 'search_path' is '"$user", public'.
Now by default there is no schema with the same name as the database user, so
the effective default search path is just the 'public' schema.
Yours,
Laurenz Albe
^ permalink raw reply [nested|flat] 8+ messages in thread
end of thread, other threads:[~2025-07-12 10:19 UTC | newest]
Thread overview: 8+ messages (download: mbox mbox.gz follow: Atom feed)
-- links below jump to the message on this page --
2022-06-06 22:11 Unclear Wording PG Doc comments form <noreply@postgresql.org>
2022-06-08 00:15 ` Bruce Momjian <bruce@momjian.us>
2022-06-08 02:34 ` Laurenz Albe <laurenz.albe@cybertec.at>
2022-06-08 17:49 ` Peter Eisentraut <peter.eisentraut@enterprisedb.com>
2022-06-08 19:07 ` Bruce Momjian <bruce@momjian.us>
2022-06-22 21:00 ` Bruce Momjian <bruce@momjian.us>
2025-07-11 16:12 Unclear wording PG Doc comments form <noreply@postgresql.org>
2025-07-12 10:19 ` Re: Unclear wording Laurenz Albe <laurenz.albe@cybertec.at>
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