References/Links missing
The following documentation comment has been logged on the website:
Page: https://www.postgresql.org/docs/18/warm-standby.html
Description:
When crawling through this page:
https://www.postgresql.org/docs/current/warm-standby.html I found a lot of
references missing which makes it exhausting reading and working through the
text.
Is it worth to take the effort to add more/all references?
What are the rules? Only the first occurrence or all occurrences of a
keyword?
Examples:
* synchronous_standby_names: Only the first occurence is referenced (but I
am possibly reading other chapters?)
* archive_command: Is not referenced in Chapter 26.2.9 (but further up, but
I am possibly not reading the other chapter?)
* synchronous_commit: Is not referenced at all
(https://www.postgresql.org/docs/current/runtime-config-wal.html#GUC-SYNCHRONOUS-COMMIT)
* pg_receivewal: Is not referenced at all
(https://www.postgresql.org/docs/current/app-pgreceivewal.html)
* pg_backup_stop and pg_backup_start: Is not referenced at all
(https://www.postgresql.org/docs/current/functions-admin.html#FUNCTIONS-ADMIN-BACKUP)
On 31 Jul 2026, at 11:08, PG Doc comments form <noreply@postgresql.org> wrote:
Is it worth to take the effort to add more/all references?
What are the rules? Only the first occurrence or all occurrences of a
keyword?
Our style guide doesn't offer guidance on this topic, personally I can see
value in adding more links to make cross-referencing during reading easier.
Would you like to prepare a patch with your suggestions that we can discuss?
--
Daniel Gustafsson
Hi Daniel
Thanks for the feedback.
Yes I can try. One big patch or several small patches (one per chapter)?
To pgsql-hackers or pgsql-docs?
Regards,
Oli
On 01/08/2026 20:47, Daniel Gustafsson wrote:
On 31 Jul 2026, at 11:08, PG Doc comments form <noreply@postgresql.org> wrote:
Is it worth to take the effort to add more/all references?What are the rules? Only the first occurrence or all occurrences of a
keyword?Our style guide doesn't offer guidance on this topic, personally I can see
value in adding more links to make cross-referencing during reading easier.
Would you like to prepare a patch with your suggestions that we can discuss?--
Daniel Gustafsson
--
FromDual - Neutral and vendor independent MariaDB, MySQL and PostgreSQL services.
FromDual GmbH Rebenweg 6
CH - 8610 Uster
Oli Sennhauser CEO / Senior Consultant
Phone: +41 44 500 58 20 Mobile: +41 79 830 09 33
oli.sennhauser@fromdual.com https://www.fromdual.com
Twitter: fromdual
Attachments:
On 3 Aug 2026, at 09:20, Oli Sennhauser <oli.sennhauser@fromdual.com> wrote:
Yes I can try. One big patch or several small patches (one per chapter)?
I think a single patch is fine here.
To pgsql-hackers or pgsql-docs?
While there are many documentation threads on -hackers, I prefer to keep them
on -docs so let's continue here.
--
Daniel Gustafsson
I added some links now. It is not complete but time consuming... So
let's see if I get the patch through...
Please let me know if I should change anything or if I got it more or
less right.
Is attachment fine or is preference inline?
On 03/08/2026 15:49, Daniel Gustafsson wrote:
On 3 Aug 2026, at 09:20, Oli Sennhauser <oli.sennhauser@fromdual.com> wrote:
Yes I can try. One big patch or several small patches (one per chapter)?I think a single patch is fine here.
To pgsql-hackers or pgsql-docs?
While there are many documentation threads on -hackers, I prefer to keep them
on -docs so let's continue here.--
Daniel Gustafsson
--
FromDual - Neutral and vendor independent MariaDB, MySQL and PostgreSQL services.
FromDual GmbH Rebenweg 6
CH - 8610 Uster
Oli Sennhauser CEO / Senior Consultant
Phone: +41 44 500 58 20 Mobile: +41 79 830 09 33
oli.sennhauser@fromdual.com https://www.fromdual.com
Twitter: fromdual