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