References/Links missing

Started by PG Bug reporting form4 months ago5 messagesdocs
Jump to latest
#1PG Bug reporting form
noreply@postgresql.org

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)

#2Daniel Gustafsson
daniel@yesql.se
In reply to: PG Bug reporting form (#1)
Re: References/Links missing

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

#3Oli Sennhauser
oli.sennhauser@fromdual.com
In reply to: Daniel Gustafsson (#2)
Re: References/Links missing

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:

OpenPGP_0xB58CF11D3C9DDEA9.ascapplication/pgp-keys; name=OpenPGP_0xB58CF11D3C9DDEA9.ascDownload
#4Daniel Gustafsson
daniel@yesql.se
In reply to: Oli Sennhauser (#3)
Re: References/Links missing

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

#5Oli Sennhauser
oli.sennhauser@fromdual.com
In reply to: Daniel Gustafsson (#4)
Re: References/Links missing

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

Attachments:

t253267_5
0001-some-references-on-variables-and-functions-added.patchtext/x-patch; charset=UTF-8; name=0001-some-references-on-variables-and-functions-added.patchDownload+25-25
OpenPGP_0xB58CF11D3C9DDEA9.ascapplication/pgp-keys; name=OpenPGP_0xB58CF11D3C9DDEA9.ascDownload