agora inbox for [email protected]
help / color / mirror / Atom feed[PATCH] doc: Use uppercase keywords in foreign key tutorial
17+ messages / 6 participants
[nested] [flat]
* [PATCH] doc: Use uppercase keywords in foreign key tutorial
@ 2025-10-16 08:30 Erik Wienhold <[email protected]>
0 siblings, 0 replies; 17+ messages in thread
From: Erik Wienhold @ 2025-10-16 08:30 UTC (permalink / raw)
Make it consistent with the rest of the docs.
---
doc/src/sgml/advanced.sgml | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/doc/src/sgml/advanced.sgml b/doc/src/sgml/advanced.sgml
index e15a3323dfb..1f37dc73be8 100644
--- a/doc/src/sgml/advanced.sgml
+++ b/doc/src/sgml/advanced.sgml
@@ -101,12 +101,12 @@ SELECT * FROM myview;
<programlisting>
CREATE TABLE cities (
- name varchar(80) primary key,
+ name varchar(80) PRIMARY KEY,
location point
);
CREATE TABLE weather (
- city varchar(80) references cities(name),
+ city varchar(80) REFERENCES cities(name),
temp_lo int,
temp_hi int,
prcp real,
--
2.51.0
--ndbxger6sdjxhx3v--
^ permalink raw reply [nested|flat] 17+ messages in thread
* [PATCH] doc: Use uppercase keywords in foreign key tutorial
@ 2025-10-16 08:30 Erik Wienhold <[email protected]>
0 siblings, 0 replies; 17+ messages in thread
From: Erik Wienhold @ 2025-10-16 08:30 UTC (permalink / raw)
Make it consistent with the rest of the docs.
---
doc/src/sgml/advanced.sgml | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/doc/src/sgml/advanced.sgml b/doc/src/sgml/advanced.sgml
index e15a3323dfb..1f37dc73be8 100644
--- a/doc/src/sgml/advanced.sgml
+++ b/doc/src/sgml/advanced.sgml
@@ -101,12 +101,12 @@ SELECT * FROM myview;
<programlisting>
CREATE TABLE cities (
- name varchar(80) primary key,
+ name varchar(80) PRIMARY KEY,
location point
);
CREATE TABLE weather (
- city varchar(80) references cities(name),
+ city varchar(80) REFERENCES cities(name),
temp_lo int,
temp_hi int,
prcp real,
--
2.51.0
--ndbxger6sdjxhx3v--
^ permalink raw reply [nested|flat] 17+ messages in thread
* 7.2.1. The FROM Clause
@ 2026-06-12 09:58 PG Doc comments form <[email protected]>
2026-06-14 20:09 ` Re: 7.2.1. The FROM Clause Laurenz Albe <[email protected]>
0 siblings, 1 reply; 17+ messages in thread
From: PG Doc comments form @ 2026-06-12 09:58 UTC (permalink / raw)
To: [email protected]; +Cc: [email protected]
The following documentation comment has been logged on the website:
Page: https://www.postgresql.org/docs/18/queries-table-expressions.html
Description:
I have a question regarding:
https://www.postgresql.org/docs/current/queries-table-expressions.html#QUERIES-FROM
Is the following sentence from the docu correct?
"Instead of writing ONLY before the table name, you can write * after the
table name to explicitly specify that descendant tables are included."
I read it like you can use "* after the table name" instead of "ONLY before
the table name" which seems wrong.
Thanks
Jochen
^ permalink raw reply [nested|flat] 17+ messages in thread
* Re: 7.2.1. The FROM Clause
2026-06-12 09:58 7.2.1. The FROM Clause PG Doc comments form <[email protected]>
@ 2026-06-14 20:09 ` Laurenz Albe <[email protected]>
2026-06-14 20:40 ` Re: 7.2.1. The FROM Clause Tom Lane <[email protected]>
0 siblings, 1 reply; 17+ messages in thread
From: Laurenz Albe @ 2026-06-14 20:09 UTC (permalink / raw)
To: [email protected]; [email protected]
On Fri, 2026-06-12 at 09:58 +0000, PG Doc comments form wrote:
> I have a question regarding:
> https://www.postgresql.org/docs/current/queries-table-expressions.html#QUERIES-FROM
> Is the following sentence from the docu correct?
> "Instead of writing ONLY before the table name, you can write * after the
> table name to explicitly specify that descendant tables are included."
>
> I read it like you can use "* after the table name" instead of "ONLY before
> the table name" which seems wrong.
The "instead" does not mean that "tab *" is a substitute for "ONLY tab",
but is meant to mean that you cannot use both at the same time, like "ONLY tab *".
But I understand your confusion. To be honest, I only learned about the syntax
"tab *" a few days ago. Digging through the history, this syntax has been
obsolete since 2000. I think we could remove both the paragraph that confuses
you and the asterisk from the syntax diagram. We can leave the obsolete
syntax to accomodate SQL code that hasn't changed for over 25 years, but I don't
see a reason to keep it in the documentation.
Yours,
Laurenz Albe
^ permalink raw reply [nested|flat] 17+ messages in thread
* Re: 7.2.1. The FROM Clause
2026-06-12 09:58 7.2.1. The FROM Clause PG Doc comments form <[email protected]>
2026-06-14 20:09 ` Re: 7.2.1. The FROM Clause Laurenz Albe <[email protected]>
@ 2026-06-14 20:40 ` Tom Lane <[email protected]>
2026-06-15 06:39 ` Re: 7.2.1. The FROM Clause Laurenz Albe <[email protected]>
2026-06-15 20:35 ` Re: 7.2.1. The FROM Clause Christoph Berg <[email protected]>
0 siblings, 2 replies; 17+ messages in thread
From: Tom Lane @ 2026-06-14 20:40 UTC (permalink / raw)
To: Laurenz Albe <[email protected]>; +Cc: [email protected]; [email protected]
Laurenz Albe <[email protected]> writes:
> But I understand your confusion. To be honest, I only learned about the syntax
> "tab *" a few days ago. Digging through the history, this syntax has been
> obsolete since 2000. I think we could remove both the paragraph that confuses
> you and the asterisk from the syntax diagram. We can leave the obsolete
> syntax to accomodate SQL code that hasn't changed for over 25 years, but I don't
> see a reason to keep it in the documentation.
I think we've discussed that before, and concluded that removing the
docs would be a disservice to users who are trying to read old code
that does this and don't know what it means. Maybe that argument
is too weak now to justify keeping the docs, but I'm unsure.
I'd be inclined to just rephrase this sentence in hopes of making
it less ambiguous.
regards, tom lane
^ permalink raw reply [nested|flat] 17+ messages in thread
* Re: 7.2.1. The FROM Clause
2026-06-12 09:58 7.2.1. The FROM Clause PG Doc comments form <[email protected]>
2026-06-14 20:09 ` Re: 7.2.1. The FROM Clause Laurenz Albe <[email protected]>
2026-06-14 20:40 ` Re: 7.2.1. The FROM Clause Tom Lane <[email protected]>
@ 2026-06-15 06:39 ` Laurenz Albe <[email protected]>
2026-06-15 15:05 ` Re: 7.2.1. The FROM Clause Tom Lane <[email protected]>
1 sibling, 1 reply; 17+ messages in thread
From: Laurenz Albe @ 2026-06-15 06:39 UTC (permalink / raw)
To: Tom Lane <[email protected]>; +Cc: [email protected]; [email protected]
On Sun, 2026-06-14 at 16:40 -0400, Tom Lane wrote:
> Laurenz Albe <[email protected]> writes:
> > To be honest, I only learned about the syntax
> > "tab *" a few days ago. Digging through the history, this syntax has been
> > obsolete since 2000. I think we could remove both the paragraph that confuses
> > you and the asterisk from the syntax diagram.
>
> I think we've discussed that before, and concluded that removing the
> docs would be a disservice to users who are trying to read old code
> that does this and don't know what it means. Maybe that argument
> is too weak now to justify keeping the docs, but I'm unsure.
> I'd be inclined to just rephrase this sentence in hopes of making
> it less ambiguous.
Fine by me; here is a patch.
I could not resist the temptation to remove the "now always" in
"searching descendant tables is now always the default". That sounds
too much like this was a recent change.
Yours,
Laurenz Albe
Attachments:
[text/x-patch] v1-0001-Reword-doc-for-asterisk-after-table-names.patch (1.8K, ../../[email protected]/2-v1-0001-Reword-doc-for-asterisk-after-table-names.patch)
download | inline diff:
From 2a3cfb32c7f3fd626617d075ba4f0f3e2818b4e4 Mon Sep 17 00:00:00 2001
From: Laurenz Albe <[email protected]>
Date: Mon, 15 Jun 2026 08:34:27 +0200
Subject: [PATCH v1] Reword doc for asterisk after table names
The syntax "tablename *" has been obsolete since 7.1, but we want
to retain it and its documentation for backward compatibility
reasons. However, the wording was confusing and could be understood
to mean that "tablename *" is the same as "ONLY tablename".
Reported-by: Jochen Bandhauer <[email protected]>
Author: Laurenz Albe <[email protected]>
Discussion: https://postgr.es/m/178125831604.1285960.8250607197280951685%40wrigleys.postgresql.org
---
doc/src/sgml/queries.sgml | 8 ++++----
1 file changed, 4 insertions(+), 4 deletions(-)
diff --git a/doc/src/sgml/queries.sgml b/doc/src/sgml/queries.sgml
index ec4ca01cd16..3096b986a09 100644
--- a/doc/src/sgml/queries.sgml
+++ b/doc/src/sgml/queries.sgml
@@ -143,10 +143,10 @@ FROM <replaceable>table_reference</replaceable> <optional>, <replaceable>table_r
</para>
<para>
- Instead of writing <literal>ONLY</literal> before the table name, you can write
- <literal>*</literal> after the table name to explicitly specify that descendant
- tables are included. There is no real reason to use this syntax any more,
- because searching descendant tables is now always the default behavior.
+ You can write <literal>*</literal> after the table name to explicitly
+ specify that descendant tables are included, which is the opposite of
+ <literal>ONLY</literal>. There is no real reason to use this syntax
+ any more, because searching descendant tables is the default behavior.
However, it is supported for compatibility with older releases.
</para>
--
2.54.0
^ permalink raw reply [nested|flat] 17+ messages in thread
* Re: 7.2.1. The FROM Clause
2026-06-12 09:58 7.2.1. The FROM Clause PG Doc comments form <[email protected]>
2026-06-14 20:09 ` Re: 7.2.1. The FROM Clause Laurenz Albe <[email protected]>
2026-06-14 20:40 ` Re: 7.2.1. The FROM Clause Tom Lane <[email protected]>
2026-06-15 06:39 ` Re: 7.2.1. The FROM Clause Laurenz Albe <[email protected]>
@ 2026-06-15 15:05 ` Tom Lane <[email protected]>
2026-06-15 15:24 ` Re: 7.2.1. The FROM Clause Laurenz Albe <[email protected]>
0 siblings, 1 reply; 17+ messages in thread
From: Tom Lane @ 2026-06-15 15:05 UTC (permalink / raw)
To: Laurenz Albe <[email protected]>; +Cc: [email protected]; [email protected]
Laurenz Albe <[email protected]> writes:
> I could not resist the temptation to remove the "now always" in
> "searching descendant tables is now always the default". That sounds
> too much like this was a recent change.
Hmm, phrasing that part that way sounds like it's always been so,
which is not only false but is contradicted by the surrounding text.
What do you think of saying
There is no real reason to use this syntax
any more, because searching descendant tables has been the default
behavior since PostgreSQL whatever-version-it-was.
I can look up the version where it changed, if this seems like the way
to go.
I'm also tempted to replace "to use this syntax" with "to write *",
just to be totally clear which syntax we are referring to. After
your rewrite of the prior sentence, someone might think the closest
antecedent for "this" is "ONLY".
regards, tom lane
^ permalink raw reply [nested|flat] 17+ messages in thread
* Re: 7.2.1. The FROM Clause
2026-06-12 09:58 7.2.1. The FROM Clause PG Doc comments form <[email protected]>
2026-06-14 20:09 ` Re: 7.2.1. The FROM Clause Laurenz Albe <[email protected]>
2026-06-14 20:40 ` Re: 7.2.1. The FROM Clause Tom Lane <[email protected]>
2026-06-15 06:39 ` Re: 7.2.1. The FROM Clause Laurenz Albe <[email protected]>
2026-06-15 15:05 ` Re: 7.2.1. The FROM Clause Tom Lane <[email protected]>
@ 2026-06-15 15:24 ` Laurenz Albe <[email protected]>
2026-06-15 17:14 ` Re: 7.2.1. The FROM Clause Tom Lane <[email protected]>
0 siblings, 1 reply; 17+ messages in thread
From: Laurenz Albe @ 2026-06-15 15:24 UTC (permalink / raw)
To: Tom Lane <[email protected]>; +Cc: [email protected]; [email protected]
On Mon, 2026-06-15 at 11:05 -0400, Tom Lane wrote:
> Laurenz Albe <[email protected]> writes:
> > I could not resist the temptation to remove the "now always" in
> > "searching descendant tables is now always the default". That sounds
> > too much like this was a recent change.
>
> Hmm, phrasing that part that way sounds like it's always been so,
> which is not only false but is contradicted by the surrounding text.
> What do you think of saying
>
> There is no real reason to use this syntax
> any more, because searching descendant tables has been the default
> behavior since PostgreSQL whatever-version-it-was.
>
> I can look up the version where it changed, if this seems like the way
> to go.
I did, and * became obsolete with 7.1. It's even in the release notes.
> I'm also tempted to replace "to use this syntax" with "to write *",
> just to be totally clear which syntax we are referring to. After
> your rewrite of the prior sentence, someone might think the closest
> antecedent for "this" is "ONLY".
I am fine with both your suggestions.
Yours,
Laurenz Albe
^ permalink raw reply [nested|flat] 17+ messages in thread
* Re: 7.2.1. The FROM Clause
2026-06-12 09:58 7.2.1. The FROM Clause PG Doc comments form <[email protected]>
2026-06-14 20:09 ` Re: 7.2.1. The FROM Clause Laurenz Albe <[email protected]>
2026-06-14 20:40 ` Re: 7.2.1. The FROM Clause Tom Lane <[email protected]>
2026-06-15 06:39 ` Re: 7.2.1. The FROM Clause Laurenz Albe <[email protected]>
2026-06-15 15:05 ` Re: 7.2.1. The FROM Clause Tom Lane <[email protected]>
2026-06-15 15:24 ` Re: 7.2.1. The FROM Clause Laurenz Albe <[email protected]>
@ 2026-06-15 17:14 ` Tom Lane <[email protected]>
2026-06-15 17:35 ` Re: 7.2.1. The FROM Clause Laurenz Albe <[email protected]>
0 siblings, 1 reply; 17+ messages in thread
From: Tom Lane @ 2026-06-15 17:14 UTC (permalink / raw)
To: Laurenz Albe <[email protected]>; +Cc: [email protected]; [email protected]
Laurenz Albe <[email protected]> writes:
> On Mon, 2026-06-15 at 11:05 -0400, Tom Lane wrote:
>> I can look up the version where it changed, if this seems like the way
>> to go.
> I did, and * became obsolete with 7.1. It's even in the release notes.
Well, not really. 7.1 changed this behavior to depend on the
sql_inheritance GUC. It wasn't till v10 when we removed that GUC
(see e13486eba) that you could really safely assume that an
undecorated table name includes child tables. So I think we should
say it's obsolete since v10 not 7.1.
Pushed with those changes.
regards, tom lane
^ permalink raw reply [nested|flat] 17+ messages in thread
* Re: 7.2.1. The FROM Clause
2026-06-12 09:58 7.2.1. The FROM Clause PG Doc comments form <[email protected]>
2026-06-14 20:09 ` Re: 7.2.1. The FROM Clause Laurenz Albe <[email protected]>
2026-06-14 20:40 ` Re: 7.2.1. The FROM Clause Tom Lane <[email protected]>
2026-06-15 06:39 ` Re: 7.2.1. The FROM Clause Laurenz Albe <[email protected]>
2026-06-15 15:05 ` Re: 7.2.1. The FROM Clause Tom Lane <[email protected]>
2026-06-15 15:24 ` Re: 7.2.1. The FROM Clause Laurenz Albe <[email protected]>
2026-06-15 17:14 ` Re: 7.2.1. The FROM Clause Tom Lane <[email protected]>
@ 2026-06-15 17:35 ` Laurenz Albe <[email protected]>
0 siblings, 0 replies; 17+ messages in thread
From: Laurenz Albe @ 2026-06-15 17:35 UTC (permalink / raw)
To: Tom Lane <[email protected]>; +Cc: [email protected]; [email protected]
On Mon, 2026-06-15 at 13:14 -0400, Tom Lane wrote:
> Pushed with those changes.
Thanks for improving PostgreSQL!
Laurenz Albe
^ permalink raw reply [nested|flat] 17+ messages in thread
* Re: 7.2.1. The FROM Clause
2026-06-12 09:58 7.2.1. The FROM Clause PG Doc comments form <[email protected]>
2026-06-14 20:09 ` Re: 7.2.1. The FROM Clause Laurenz Albe <[email protected]>
2026-06-14 20:40 ` Re: 7.2.1. The FROM Clause Tom Lane <[email protected]>
@ 2026-06-15 20:35 ` Christoph Berg <[email protected]>
1 sibling, 0 replies; 17+ messages in thread
From: Christoph Berg @ 2026-06-15 20:35 UTC (permalink / raw)
To: Tom Lane <[email protected]>; +Cc: Laurenz Albe <[email protected]>; [email protected]; [email protected]
Re: Tom Lane
> I think we've discussed that before, and concluded that removing the
> docs would be a disservice to users who are trying to read old code
> that does this and don't know what it means. Maybe that argument
> is too weak now to justify keeping the docs, but I'm unsure.
Fwiw, I saw that syntax somewhere some days back and then went looking
what it meant. I did find it in psql's "\h select" and in turn the
full SELECT documentation. I guess if the docs had not mentioned it, I
would have had to read the grammar, and looking for a non-string in
there sounds painful.
So it should definitely be kept. Thanks. :)
Christoph
^ permalink raw reply [nested|flat] 17+ messages in thread
* 66.6. Database Page Layout
@ 2026-07-08 10:43 PG Doc comments form <[email protected]>
2026-07-09 21:58 ` Re: 66.6. Database Page Layout Daniel Gustafsson <[email protected]>
0 siblings, 1 reply; 17+ messages in thread
From: PG Doc comments form @ 2026-07-08 10:43 UTC (permalink / raw)
To: [email protected]; +Cc: [email protected]
The following documentation comment has been logged on the website:
Page: https://www.postgresql.org/docs/18/storage-page-layout.html
Description:
> The second field contains the page checksum if -k are enabled.
-k -- This is enabled by default; use --no-data-checksums to disable
checksums.
Why does this need to be clarified?
^ permalink raw reply [nested|flat] 17+ messages in thread
* Re: 66.6. Database Page Layout
2026-07-08 10:43 66.6. Database Page Layout PG Doc comments form <[email protected]>
@ 2026-07-09 21:58 ` Daniel Gustafsson <[email protected]>
2026-07-10 06:33 ` Re: 66.6. Database Page Layout Laurenz Albe <[email protected]>
0 siblings, 1 reply; 17+ messages in thread
From: Daniel Gustafsson @ 2026-07-09 21:58 UTC (permalink / raw)
To: [email protected]; PostgreSQL-documentation <[email protected]>
> On 8 Jul 2026, at 12:43, PG Doc comments form <[email protected]> wrote:
>
> The following documentation comment has been logged on the website:
>
> Page: https://www.postgresql.org/docs/18/storage-page-layout.html
> Description:
>
>> The second field contains the page checksum if -k are enabled.
>
> -k -- This is enabled by default; use --no-data-checksums to disable
> checksums.
>
> Why does this need to be clarified?
I'm not entirely sure which part you are referring to, but I agree that the
current wording isn't very good.
"The second field contains the page checksum if -k are enabled."
I propose the attached patch which changes the sentence to "The second field
contains the page checksum if data checksums are enabled." with a link to the
Checksums chapter in the documentation instead.
--
Daniel Gustafsson
Attachments:
[application/octet-stream] page_layout_checksums.diff (783B, ../../[email protected]/2-page_layout_checksums.diff)
download | inline diff:
diff --git a/doc/src/sgml/storage.sgml b/doc/src/sgml/storage.sgml
index 6b6377503bf..19924b98d71 100644
--- a/doc/src/sgml/storage.sgml
+++ b/doc/src/sgml/storage.sgml
@@ -797,7 +797,7 @@ data. Empty in ordinary tables.</entry>
(<structname>PageHeaderData</structname>). Its format is detailed in <xref
linkend="pageheaderdata-table"/>. The first field tracks the most
recent WAL entry related to this page. The second field contains
- the page checksum if <xref linkend="app-initdb-data-checksums"/> are
+ the page checksum if <link linkend="checksums">data checksums</link> are
enabled. Next is a 2-byte field containing flag bits. This is followed
by three 2-byte integer fields (<structfield>pd_lower</structfield>,
<structfield>pd_upper</structfield>, and
^ permalink raw reply [nested|flat] 17+ messages in thread
* Re: 66.6. Database Page Layout
2026-07-08 10:43 66.6. Database Page Layout PG Doc comments form <[email protected]>
2026-07-09 21:58 ` Re: 66.6. Database Page Layout Daniel Gustafsson <[email protected]>
@ 2026-07-10 06:33 ` Laurenz Albe <[email protected]>
2026-07-15 13:17 ` Re: 66.6. Database Page Layout Daniel Gustafsson <[email protected]>
0 siblings, 1 reply; 17+ messages in thread
From: Laurenz Albe @ 2026-07-10 06:33 UTC (permalink / raw)
To: Daniel Gustafsson <[email protected]>; [email protected]; PostgreSQL-documentation <[email protected]>
On Thu, 2026-07-09 at 23:58 +0200, Daniel Gustafsson wrote:
>
> I propose the attached patch which changes the sentence to "The second field
> contains the page checksum if data checksums are enabled." with a link to the
> Checksums chapter in the documentation instead.
That patch looks good to me.
Yours,
Laurenz Albe
^ permalink raw reply [nested|flat] 17+ messages in thread
* Re: 66.6. Database Page Layout
2026-07-08 10:43 66.6. Database Page Layout PG Doc comments form <[email protected]>
2026-07-09 21:58 ` Re: 66.6. Database Page Layout Daniel Gustafsson <[email protected]>
2026-07-10 06:33 ` Re: 66.6. Database Page Layout Laurenz Albe <[email protected]>
@ 2026-07-15 13:17 ` Daniel Gustafsson <[email protected]>
2026-07-15 14:50 ` Re: 66.6. Database Page Layout Laurenz Albe <[email protected]>
0 siblings, 1 reply; 17+ messages in thread
From: Daniel Gustafsson @ 2026-07-15 13:17 UTC (permalink / raw)
To: Laurenz Albe <[email protected]>; +Cc: [email protected]; PostgreSQL-documentation <[email protected]>
> On 10 Jul 2026, at 08:33, Laurenz Albe <[email protected]> wrote:
>
> On Thu, 2026-07-09 at 23:58 +0200, Daniel Gustafsson wrote:
>>
>> I propose the attached patch which changes the sentence to "The second field
>> contains the page checksum if data checksums are enabled." with a link to the
>> Checksums chapter in the documentation instead.
>
> That patch looks good to me.
I took another look at this today to close the thread and found that there were
one more occurrence of this pattern stemming from 67846550dc6d which removed
the initdb xreflabels. The attached patches fix the other one as well as
changes the link in the amcheck docs to point to the main checksums page which
is more relevant than the (now default) initdb option. Patches for master down
to v18 attached.
--
Daniel Gustafsson
Attachments:
[application/octet-stream] vmaster-0001-doc-Fix-link-text-for-data-checksums.patch (3.4K, ../../[email protected]/2-vmaster-0001-doc-Fix-link-text-for-data-checksums.patch)
download | inline diff:
From 08bf966f47a85cc9ec291bea84d90ca53c090345 Mon Sep 17 00:00:00 2001
From: Daniel Gustafsson <[email protected]>
Date: Wed, 15 Jul 2026 15:02:51 +0200
Subject: [PATCH vmaster] doc: Fix link text for data checksums
Commit 67846550dc6d removed the xreflabels for initdb options, which
turned the sentence "The second field contains the page checksum if
data checksums are enabled" into "The second field contains the page
checksum if -k are enabled", as well "Only has effect if data checksums
are enabled" into "Only has effect if -k are enabled".
Fix by setting an explicit link text, and while there also change the
link to point to the data checksum page which has more information
than just the initdb option.
The original report was for one instance, further inspection turned
up quite a few more cases. Also redirect the link in the amcheck
docs which albeit was reading right, but will be more helpful if
linking to the main page on data checksums. Backpatch to v18 where
the xreflabels were removed.
Author: Daniel Gustafsson <[email protected]>
Reported-by: [email protected]
Reviewed-by: Laurenz Albe <[email protected]>
Discussion: https://postgr.es/m/[email protected]
Backpatch-through: 18
---
doc/src/sgml/amcheck.sgml | 5 ++---
doc/src/sgml/config.sgml | 2 +-
doc/src/sgml/storage.sgml | 2 +-
3 files changed, 4 insertions(+), 5 deletions(-)
diff --git a/doc/src/sgml/amcheck.sgml b/doc/src/sgml/amcheck.sgml
index 08006856579..13a6bb18897 100644
--- a/doc/src/sgml/amcheck.sgml
+++ b/doc/src/sgml/amcheck.sgml
@@ -421,9 +421,8 @@ SET client_min_messages = DEBUG1;
<para>
<filename>amcheck</filename> can be effective at detecting various types of
- failure modes that <link
- linkend="app-initdb-data-checksums"><application>data
- checksums</application></link> will fail to catch. These include:
+ failure modes that <link linkend="checksums">data checksums</link> will fail
+ to catch. These include:
<itemizedlist>
<listitem>
diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml
index 0848c18d329..1bc82182cd3 100644
--- a/doc/src/sgml/config.sgml
+++ b/doc/src/sgml/config.sgml
@@ -13229,7 +13229,7 @@ LOG: CleanUpLock: deleting: lock(0xb7acd844) id(24688,24696,0,0,0,1)
</term>
<listitem>
<para>
- Only has effect if <xref linkend="app-initdb-data-checksums"/> are enabled.
+ Only has effect if <link linkend="checksums">data checksums</link> are enabled.
</para>
<para>
Detection of a checksum failure during a read normally causes
diff --git a/doc/src/sgml/storage.sgml b/doc/src/sgml/storage.sgml
index 6b6377503bf..19924b98d71 100644
--- a/doc/src/sgml/storage.sgml
+++ b/doc/src/sgml/storage.sgml
@@ -797,7 +797,7 @@ data. Empty in ordinary tables.</entry>
(<structname>PageHeaderData</structname>). Its format is detailed in <xref
linkend="pageheaderdata-table"/>. The first field tracks the most
recent WAL entry related to this page. The second field contains
- the page checksum if <xref linkend="app-initdb-data-checksums"/> are
+ the page checksum if <link linkend="checksums">data checksums</link> are
enabled. Next is a 2-byte field containing flag bits. This is followed
by three 2-byte integer fields (<structfield>pd_lower</structfield>,
<structfield>pd_upper</structfield>, and
--
2.39.3 (Apple Git-146)
[application/octet-stream] v18-0001-doc-Fix-link-text-for-data-checksums.patch (3.4K, ../../[email protected]/3-v18-0001-doc-Fix-link-text-for-data-checksums.patch)
download | inline diff:
From f03ad3630831265bd5e1daf335cbbb7bf51f5461 Mon Sep 17 00:00:00 2001
From: Daniel Gustafsson <[email protected]>
Date: Wed, 15 Jul 2026 15:02:51 +0200
Subject: [PATCH v18] doc: Fix link text for data checksums
Commit 67846550dc6d removed the xreflabels for initdb options, which
turned the sentence "The second field contains the page checksum if
data checksums are enabled" into "The second field contains the page
checksum if -k are enabled", as well "Only has effect if data checksums
are enabled" into "Only has effect if -k are enabled".
Fix by setting an explicit link text, and while there also change the
link to point to the data checksum page which has more information
than just the initdb option.
The original report was for one instance, further inspection turned
up quite a few more cases. Also redirect the link in the amcheck
docs which albeit was reading right, but will be more helpful if
linking to the main page on data checksums. Backpatch to v18 where
the xreflabels were removed.
Author: Daniel Gustafsson <[email protected]>
Reported-by: [email protected]
Reviewed-by: Laurenz Albe <[email protected]>
Discussion: https://postgr.es/m/[email protected]
Backpatch-through: 18
---
doc/src/sgml/amcheck.sgml | 5 ++---
doc/src/sgml/config.sgml | 2 +-
doc/src/sgml/storage.sgml | 2 +-
3 files changed, 4 insertions(+), 5 deletions(-)
diff --git a/doc/src/sgml/amcheck.sgml b/doc/src/sgml/amcheck.sgml
index 0402172a5ff..747dc115f48 100644
--- a/doc/src/sgml/amcheck.sgml
+++ b/doc/src/sgml/amcheck.sgml
@@ -421,9 +421,8 @@ SET client_min_messages = DEBUG1;
<para>
<filename>amcheck</filename> can be effective at detecting various types of
- failure modes that <link
- linkend="app-initdb-data-checksums"><application>data
- checksums</application></link> will fail to catch. These include:
+ failure modes that <link linkend="checksums">data checksums</link> will fail
+ to catch. These include:
<itemizedlist>
<listitem>
diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml
index c688ed05f72..9ec0d56038d 100644
--- a/doc/src/sgml/config.sgml
+++ b/doc/src/sgml/config.sgml
@@ -12658,7 +12658,7 @@ LOG: CleanUpLock: deleting: lock(0xb7acd844) id(24688,24696,0,0,0,1)
</term>
<listitem>
<para>
- Only has effect if <xref linkend="app-initdb-data-checksums"/> are enabled.
+ Only has effect if <link linkend="checksums">data checksums</link> are enabled.
</para>
<para>
Detection of a checksum failure during a read normally causes
diff --git a/doc/src/sgml/storage.sgml b/doc/src/sgml/storage.sgml
index 61250799ec0..245f18c65c9 100644
--- a/doc/src/sgml/storage.sgml
+++ b/doc/src/sgml/storage.sgml
@@ -793,7 +793,7 @@ data. Empty in ordinary tables.</entry>
(<structname>PageHeaderData</structname>). Its format is detailed in <xref
linkend="pageheaderdata-table"/>. The first field tracks the most
recent WAL entry related to this page. The second field contains
- the page checksum if <xref linkend="app-initdb-data-checksums"/> are
+ the page checksum if <link linkend="checksums">data checksums</link> are
enabled. Next is a 2-byte field containing flag bits. This is followed
by three 2-byte integer fields (<structfield>pd_lower</structfield>,
<structfield>pd_upper</structfield>, and
--
2.39.3 (Apple Git-146)
[application/octet-stream] v19-0001-doc-Fix-link-text-for-data-checksums.patch (3.4K, ../../[email protected]/4-v19-0001-doc-Fix-link-text-for-data-checksums.patch)
download | inline diff:
From d8f036876661a67079b62c5415279a88ca19c26f Mon Sep 17 00:00:00 2001
From: Daniel Gustafsson <[email protected]>
Date: Wed, 15 Jul 2026 15:02:51 +0200
Subject: [PATCH v19] doc: Fix link text for data checksums
Commit 67846550dc6d removed the xreflabels for initdb options, which
turned the sentence "The second field contains the page checksum if
data checksums are enabled" into "The second field contains the page
checksum if -k are enabled", as well "Only has effect if data checksums
are enabled" into "Only has effect if -k are enabled".
Fix by setting an explicit link text, and while there also change the
link to point to the data checksum page which has more information
than just the initdb option.
The original report was for one instance, further inspection turned
up quite a few more cases. Also redirect the link in the amcheck
docs which albeit was reading right, but will be more helpful if
linking to the main page on data checksums. Backpatch to v18 where
the xreflabels were removed.
Author: Daniel Gustafsson <[email protected]>
Reported-by: [email protected]
Reviewed-by: Laurenz Albe <[email protected]>
Discussion: https://postgr.es/m/[email protected]
Backpatch-through: 18
---
doc/src/sgml/amcheck.sgml | 5 ++---
doc/src/sgml/config.sgml | 2 +-
doc/src/sgml/storage.sgml | 2 +-
3 files changed, 4 insertions(+), 5 deletions(-)
diff --git a/doc/src/sgml/amcheck.sgml b/doc/src/sgml/amcheck.sgml
index 08006856579..13a6bb18897 100644
--- a/doc/src/sgml/amcheck.sgml
+++ b/doc/src/sgml/amcheck.sgml
@@ -421,9 +421,8 @@ SET client_min_messages = DEBUG1;
<para>
<filename>amcheck</filename> can be effective at detecting various types of
- failure modes that <link
- linkend="app-initdb-data-checksums"><application>data
- checksums</application></link> will fail to catch. These include:
+ failure modes that <link linkend="checksums">data checksums</link> will fail
+ to catch. These include:
<itemizedlist>
<listitem>
diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml
index 45827687b9c..f4fb7d0ecfe 100644
--- a/doc/src/sgml/config.sgml
+++ b/doc/src/sgml/config.sgml
@@ -13182,7 +13182,7 @@ LOG: CleanUpLock: deleting: lock(0xb7acd844) id(24688,24696,0,0,0,1)
</term>
<listitem>
<para>
- Only has effect if <xref linkend="app-initdb-data-checksums"/> are enabled.
+ Only has effect if <link linkend="checksums">data checksums</link> are enabled.
</para>
<para>
Detection of a checksum failure during a read normally causes
diff --git a/doc/src/sgml/storage.sgml b/doc/src/sgml/storage.sgml
index 6b6377503bf..19924b98d71 100644
--- a/doc/src/sgml/storage.sgml
+++ b/doc/src/sgml/storage.sgml
@@ -797,7 +797,7 @@ data. Empty in ordinary tables.</entry>
(<structname>PageHeaderData</structname>). Its format is detailed in <xref
linkend="pageheaderdata-table"/>. The first field tracks the most
recent WAL entry related to this page. The second field contains
- the page checksum if <xref linkend="app-initdb-data-checksums"/> are
+ the page checksum if <link linkend="checksums">data checksums</link> are
enabled. Next is a 2-byte field containing flag bits. This is followed
by three 2-byte integer fields (<structfield>pd_lower</structfield>,
<structfield>pd_upper</structfield>, and
--
2.39.3 (Apple Git-146)
^ permalink raw reply [nested|flat] 17+ messages in thread
* Re: 66.6. Database Page Layout
2026-07-08 10:43 66.6. Database Page Layout PG Doc comments form <[email protected]>
2026-07-09 21:58 ` Re: 66.6. Database Page Layout Daniel Gustafsson <[email protected]>
2026-07-10 06:33 ` Re: 66.6. Database Page Layout Laurenz Albe <[email protected]>
2026-07-15 13:17 ` Re: 66.6. Database Page Layout Daniel Gustafsson <[email protected]>
@ 2026-07-15 14:50 ` Laurenz Albe <[email protected]>
2026-07-15 15:13 ` Re: 66.6. Database Page Layout Daniel Gustafsson <[email protected]>
0 siblings, 1 reply; 17+ messages in thread
From: Laurenz Albe @ 2026-07-15 14:50 UTC (permalink / raw)
To: Daniel Gustafsson <[email protected]>; +Cc: [email protected]; PostgreSQL-documentation <[email protected]>
On Wed, 2026-07-15 at 15:17 +0200, Daniel Gustafsson wrote:
> I took another look at this today to close the thread and found that there were
> one more occurrence of this pattern stemming from 67846550dc6d which removed
> the initdb xreflabels. The attached patches fix the other one as well as
> changes the link in the amcheck docs to point to the main checksums page which
> is more relevant than the (now default) initdb option. Patches for master down
> to v18 attached.
Referencing "checksums" rather than "app-initdb-data-checksums" is an improvement
in all these places, and the only other reference to "app-initdb-data-checksums"
in the documentation is good the way it is and should stay.
So the patches look good to me.
Yours,
Laurenz Albe
^ permalink raw reply [nested|flat] 17+ messages in thread
* Re: 66.6. Database Page Layout
2026-07-08 10:43 66.6. Database Page Layout PG Doc comments form <[email protected]>
2026-07-09 21:58 ` Re: 66.6. Database Page Layout Daniel Gustafsson <[email protected]>
2026-07-10 06:33 ` Re: 66.6. Database Page Layout Laurenz Albe <[email protected]>
2026-07-15 13:17 ` Re: 66.6. Database Page Layout Daniel Gustafsson <[email protected]>
2026-07-15 14:50 ` Re: 66.6. Database Page Layout Laurenz Albe <[email protected]>
@ 2026-07-15 15:13 ` Daniel Gustafsson <[email protected]>
0 siblings, 0 replies; 17+ messages in thread
From: Daniel Gustafsson @ 2026-07-15 15:13 UTC (permalink / raw)
To: Laurenz Albe <[email protected]>; +Cc: [email protected]; PostgreSQL-documentation <[email protected]>
> On 15 Jul 2026, at 16:50, Laurenz Albe <[email protected]> wrote:
>
> On Wed, 2026-07-15 at 15:17 +0200, Daniel Gustafsson wrote:
>> I took another look at this today to close the thread and found that there were
>> one more occurrence of this pattern stemming from 67846550dc6d which removed
>> the initdb xreflabels. The attached patches fix the other one as well as
>> changes the link in the amcheck docs to point to the main checksums page which
>> is more relevant than the (now default) initdb option. Patches for master down
>> to v18 attached.
>
> Referencing "checksums" rather than "app-initdb-data-checksums" is an improvement
> in all these places, and the only other reference to "app-initdb-data-checksums"
> in the documentation is good the way it is and should stay.
>
> So the patches look good to me.
Thanks for review!
--
Daniel Gustafsson
^ permalink raw reply [nested|flat] 17+ messages in thread
end of thread, other threads:[~2026-07-15 15:13 UTC | newest]
Thread overview: 17+ messages (download: mbox mbox.gz follow: Atom feed)
-- links below jump to the message on this page --
2025-10-16 08:30 [PATCH] doc: Use uppercase keywords in foreign key tutorial Erik Wienhold <[email protected]>
2025-10-16 08:30 [PATCH] doc: Use uppercase keywords in foreign key tutorial Erik Wienhold <[email protected]>
2026-06-12 09:58 7.2.1. The FROM Clause PG Doc comments form <[email protected]>
2026-06-14 20:09 ` Re: 7.2.1. The FROM Clause Laurenz Albe <[email protected]>
2026-06-14 20:40 ` Re: 7.2.1. The FROM Clause Tom Lane <[email protected]>
2026-06-15 06:39 ` Re: 7.2.1. The FROM Clause Laurenz Albe <[email protected]>
2026-06-15 15:05 ` Re: 7.2.1. The FROM Clause Tom Lane <[email protected]>
2026-06-15 15:24 ` Re: 7.2.1. The FROM Clause Laurenz Albe <[email protected]>
2026-06-15 17:14 ` Re: 7.2.1. The FROM Clause Tom Lane <[email protected]>
2026-06-15 17:35 ` Re: 7.2.1. The FROM Clause Laurenz Albe <[email protected]>
2026-06-15 20:35 ` Re: 7.2.1. The FROM Clause Christoph Berg <[email protected]>
2026-07-08 10:43 66.6. Database Page Layout PG Doc comments form <[email protected]>
2026-07-09 21:58 ` Re: 66.6. Database Page Layout Daniel Gustafsson <[email protected]>
2026-07-10 06:33 ` Re: 66.6. Database Page Layout Laurenz Albe <[email protected]>
2026-07-15 13:17 ` Re: 66.6. Database Page Layout Daniel Gustafsson <[email protected]>
2026-07-15 14:50 ` Re: 66.6. Database Page Layout Laurenz Albe <[email protected]>
2026-07-15 15:13 ` Re: 66.6. Database Page Layout Daniel Gustafsson <[email protected]>
This inbox is served by agora; see mirroring instructions
for how to clone and mirror all data and code used for this inbox