agora inbox for pgsql-docs@postgresql.org
help / color / mirror / Atom feedReferences/Links missing
5+ messages / 3 participants
[nested] [flat]
* References/Links missing
@ 2026-07-31 09:08 PG Doc comments form <noreply@postgresql.org>
0 siblings, 1 reply; 5+ messages in thread
From: PG Doc comments form @ 2026-07-31 09:08 UTC (permalink / raw)
To: pgsql-docs@lists.postgresql.org; +Cc: oli.sennhauser@fromdual.com
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)
^ permalink raw reply [nested|flat] 5+ messages in thread
* Re: References/Links missing
@ 2026-08-01 18:47 Daniel Gustafsson <daniel@yesql.se>
parent: PG Doc comments form <noreply@postgresql.org>
0 siblings, 1 reply; 5+ messages in thread
From: Daniel Gustafsson @ 2026-08-01 18:47 UTC (permalink / raw)
To: oli.sennhauser@fromdual.com; pgsql-docs@lists.postgresql.org
> 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
^ permalink raw reply [nested|flat] 5+ messages in thread
* Re: References/Links missing
@ 2026-08-03 07:20 Oli Sennhauser <oli.sennhauser@fromdual.com>
parent: Daniel Gustafsson <daniel@yesql.se>
0 siblings, 1 reply; 5+ messages in thread
From: Oli Sennhauser @ 2026-08-03 07:20 UTC (permalink / raw)
To: Daniel Gustafsson <daniel@yesql.se>; pgsql-docs@lists.postgresql.org
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:
[application/pgp-keys] OpenPGP_0xB58CF11D3C9DDEA9.asc (1.7K, ../../f3825566-330c-4ffb-95fb-4200590e00af@fromdual.com/2-OpenPGP_0xB58CF11D3C9DDEA9.asc)
download
[application/pgp-signature] OpenPGP_signature.asc (494B, ../../f3825566-330c-4ffb-95fb-4200590e00af@fromdual.com/3-OpenPGP_signature.asc)
download
^ permalink raw reply [nested|flat] 5+ messages in thread
* Re: References/Links missing
@ 2026-08-03 13:49 Daniel Gustafsson <daniel@yesql.se>
parent: Oli Sennhauser <oli.sennhauser@fromdual.com>
0 siblings, 1 reply; 5+ messages in thread
From: Daniel Gustafsson @ 2026-08-03 13:49 UTC (permalink / raw)
To: Oli Sennhauser <oli.sennhauser@fromdual.com>; +Cc: pgsql-docs@lists.postgresql.org
> 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
^ permalink raw reply [nested|flat] 5+ messages in thread
* Re: References/Links missing
@ 2026-08-06 08:12 Oli Sennhauser <oli.sennhauser@fromdual.com>
parent: Daniel Gustafsson <daniel@yesql.se>
0 siblings, 0 replies; 5+ messages in thread
From: Oli Sennhauser @ 2026-08-06 08:12 UTC (permalink / raw)
To: Daniel Gustafsson <daniel@yesql.se>; +Cc: pgsql-docs@lists.postgresql.org
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:
[text/x-patch] 0001-some-references-on-variables-and-functions-added.patch (11.3K, ../../bc3ce420-7e9e-4ef6-8096-6051a579be3d@fromdual.com/2-0001-some-references-on-variables-and-functions-added.patch)
download | inline diff:
From 503d963ce05654de14dd82fd53dcc99fdefa2b0c Mon Sep 17 00:00:00 2001
From: shinguz <oli.sennhauser@bluewin.ch>
Date: Thu, 6 Aug 2026 10:06:05 +0200
Subject: [PATCH] some references on variables and functions added
---
doc/src/sgml/func/func-admin.sgml | 6 ++--
doc/src/sgml/high-availability.sgml | 43 +++++++++++++++--------------
2 files changed, 25 insertions(+), 24 deletions(-)
diff --git a/doc/src/sgml/func/func-admin.sgml b/doc/src/sgml/func/func-admin.sgml
index 0eae1c1f616..a14497e32de 100644
--- a/doc/src/sgml/func/func-admin.sgml
+++ b/doc/src/sgml/func/func-admin.sgml
@@ -403,7 +403,7 @@ LOG: Grand total: 1651920 bytes in 201 blocks; 622360 free (88 chunks); 1029560
</row>
<row>
- <entry role="func_table_entry"><para role="func_signature">
+ <entry id="pg-backup-start" role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>pg_backup_start</primary>
</indexterm>
@@ -430,7 +430,7 @@ LOG: Grand total: 1651920 bytes in 201 blocks; 622360 free (88 chunks); 1029560
</row>
<row>
- <entry role="func_table_entry"><para role="func_signature">
+ <entry id="pg-backup-stop" role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>pg_backup_stop</primary>
</indexterm>
@@ -491,7 +491,7 @@ LOG: Grand total: 1651920 bytes in 201 blocks; 622360 free (88 chunks); 1029560
</row>
<row>
- <entry role="func_table_entry"><para role="func_signature">
+ <entry id="pg-switch-wal" role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>pg_switch_wal</primary>
</indexterm>
diff --git a/doc/src/sgml/high-availability.sgml b/doc/src/sgml/high-availability.sgml
index fd338ab1540..91dfe8cd13d 100644
--- a/doc/src/sgml/high-availability.sgml
+++ b/doc/src/sgml/high-availability.sgml
@@ -1091,7 +1091,7 @@ primary_slot_name = 'node_a_slot'
standby servers. This extends that standard level of durability
offered by a transaction commit. This level of protection is referred
to as 2-safe replication in computer science theory, and group-1-safe
- (group-safe and 1-safe) when <varname>synchronous_commit</varname> is set to
+ (group-safe and 1-safe) when <xref linkend="guc-synchronous-commit"/> is set to
<literal>remote_write</literal>.
</para>
@@ -1124,7 +1124,7 @@ primary_slot_name = 'node_a_slot'
replication stream consumer that knows how to send the appropriate
feedback messages. Besides the built-in physical and logical replication
systems, this includes special programs such
- as <command>pg_receivewal</command> and <command>pg_recvlogical</command>
+ as <xref linkend="app-pgreceivewal"/> and <xref linkend="app-pgrecvlogical"/>
as well as some third-party replication systems and custom programs.
Check the respective documentation for details on synchronous replication
support.
@@ -1137,14 +1137,14 @@ primary_slot_name = 'node_a_slot'
Once streaming replication has been configured, configuring synchronous
replication requires only one additional configuration step:
<xref linkend="guc-synchronous-standby-names"/> must be set to
- a non-empty value. <varname>synchronous_commit</varname> must also be set to
+ a non-empty value. <xref linkend="guc-synchronous-commit"/> must also be set to
<literal>on</literal>, but since this is the default value, typically no change is
required. (See <xref linkend="runtime-config-wal-settings"/> and
<xref linkend="runtime-config-replication-primary"/>.)
This configuration will cause each commit to wait for
confirmation that the standby has written the commit record to durable
storage.
- <varname>synchronous_commit</varname> can be set by individual
+ <xref linkend="guc-synchronous-commit"/> can be set by individual
users, so it can be configured in the configuration file, for particular
users or databases, or dynamically by applications, in order to control
the durability guarantee on a per-transaction basis.
@@ -1155,11 +1155,11 @@ primary_slot_name = 'node_a_slot'
WAL record is then sent to the standby. The standby sends reply
messages each time a new batch of WAL data is written to disk, unless
<varname>wal_receiver_status_interval</varname> is set to zero on the standby.
- In the case that <varname>synchronous_commit</varname> is set to
+ In the case that <xref linkend="guc-synchronous-commit"/> is set to
<literal>remote_apply</literal>, the standby sends reply messages when the commit
record is replayed, making the transaction visible.
If the standby is chosen as a synchronous standby, according to the setting
- of <varname>synchronous_standby_names</varname> on the primary, the reply
+ of <xref linkend="guc-synchronous-standby-names"/> on the primary, the reply
messages from that standby will be considered along with those from other
synchronous standbys to decide when to release transactions waiting for
confirmation that the commit record has been received. These parameters
@@ -1171,7 +1171,7 @@ primary_slot_name = 'node_a_slot'
</para>
<para>
- Setting <varname>synchronous_commit</varname> to <literal>remote_write</literal> will
+ Setting <xref linkend="guc-synchronous-commit"/> to <literal>remote_write</literal> will
cause each commit to wait for confirmation that the standby has received
the commit record and written it out to its own operating system, but not
for the data to be flushed to disk on the standby. This
@@ -1185,7 +1185,7 @@ primary_slot_name = 'node_a_slot'
</para>
<para>
- Setting <varname>synchronous_commit</varname> to <literal>remote_apply</literal> will
+ Setting <xref linkend="guc-synchronous-commit"/> to <literal>remote_apply</literal> will
cause each commit to wait until the current synchronous standbys report
that they have replayed the transaction, making it visible to user
queries. In simple cases, this allows for load balancing with causal
@@ -1211,7 +1211,7 @@ primary_slot_name = 'node_a_slot'
transactions will wait until all the standby servers which are considered
as synchronous confirm receipt of their data. The number of synchronous
standbys that transactions must wait for replies from is specified in
- <varname>synchronous_standby_names</varname>. This parameter also specifies
+ <xref linkend="guc-synchronous-standby-names"/>. This parameter also specifies
a list of standby names and the method (<literal>FIRST</literal> and
<literal>ANY</literal>) to choose synchronous standbys from the listed ones.
</para>
@@ -1227,7 +1227,7 @@ primary_slot_name = 'node_a_slot'
next-highest-priority standby.
</para>
<para>
- An example of <varname>synchronous_standby_names</varname> for
+ An example of <xref linkend="guc-synchronous-standby-names"/> for
a priority-based multiple synchronous standbys is:
<programlisting>
synchronous_standby_names = 'FIRST 2 (s1, s2, s3)'
@@ -1248,7 +1248,7 @@ synchronous_standby_names = 'FIRST 2 (s1, s2, s3)'
synchronous standbys in the list.
</para>
<para>
- An example of <varname>synchronous_standby_names</varname> for
+ An example of <xref linkend="guc-synchronous-standby-names"/> for
a quorum-based multiple synchronous standbys is:
<programlisting>
synchronous_standby_names = 'ANY 2 (s1, s2, s3)'
@@ -1310,9 +1310,9 @@ synchronous_standby_names = 'ANY 2 (s1, s2, s3)'
<title>Planning for High Availability</title>
<para>
- <varname>synchronous_standby_names</varname> specifies the number and
+ <xref linkend="guc-synchronous-standby-names"/> specifies the number and
names of synchronous standbys that transaction commits made when
- <varname>synchronous_commit</varname> is set to <literal>on</literal>,
+ <xref linkend="guc-synchronous-commit"/> is set to <literal>on</literal>,
<literal>remote_apply</literal> or <literal>remote_write</literal> will wait for
responses from. Such transaction commits may never be completed
if any one of the synchronous standbys should crash.
@@ -1321,7 +1321,7 @@ synchronous_standby_names = 'ANY 2 (s1, s2, s3)'
<para>
The best solution for high availability is to ensure you keep as many
synchronous standbys as requested. This can be achieved by naming multiple
- potential synchronous standbys using <varname>synchronous_standby_names</varname>.
+ potential synchronous standbys using <xref linkend="guc-synchronous-standby-names"/>.
</para>
<para>
@@ -1369,7 +1369,7 @@ synchronous_standby_names = 'ANY 2 (s1, s2, s3)'
If you really cannot keep as many synchronous standbys as requested
then you should decrease the number of synchronous standbys that
transaction commits must wait for responses from
- in <varname>synchronous_standby_names</varname> (or disable it) and
+ in <xref linkend="guc-synchronous-standby-names"/> (or disable it) and
reload the configuration file on the primary server.
</para>
@@ -1380,9 +1380,9 @@ synchronous_standby_names = 'ANY 2 (s1, s2, s3)'
<para>
If you need to re-create a standby server while transactions are
- waiting, make sure that the functions <function>pg_backup_start()</function>
- and <function>pg_backup_stop()</function> are run in a session with
- <varname>synchronous_commit</varname> = <literal>off</literal>, otherwise those
+ waiting, make sure that the functions <link linkend="pg-backup-start"><function>pg_backup_start()</function></link>
+ and <link linkend="pg-backup-stop"><function>pg_backup_stop()</function></link> are run in a session with
+ <xref linkend="guc-synchronous-commit"/> = <literal>off</literal>, otherwise those
requests will wait forever for the standby to appear.
</para>
@@ -1459,10 +1459,10 @@ postgres=# WAIT FOR LSN '0/306EE20';
to <literal>always</literal>, and the standby will call the archive
command for every WAL segment it receives, whether it's by restoring
from the archive or by streaming replication. The shared archive can
- be handled similarly, but the <varname>archive_command</varname> or <varname>archive_library</varname> must
+ be handled similarly, but the <xref linkend="guc-archive-command"/> or <xref linkend="guc-archive-library"/> must
test if the file being archived exists already, and if the existing file
has identical contents. This requires more care in the
- <varname>archive_command</varname> or <varname>archive_library</varname>, as it must
+ <xref linkend="guc-archive-command"/> or <xref linkend="guc-archive-library"/>, as it must
be careful to not overwrite an existing file with different contents,
but return success if the exactly same file is archived twice. And
all that must be done free of race conditions, if two servers attempt
@@ -2238,7 +2238,8 @@ HINT: You can then restart the server after making the necessary configuration
<para>
WAL file control commands will not work during recovery,
- e.g., <function>pg_backup_start</function>, <function>pg_switch_wal</function> etc.
+ e.g., <link linkend="pg-backup-start"><function>pg_backup_start()</function></link>,
+ <link linkend="pg-switch-wal"><function>pg_switch_wal()</function></link> etc.
</para>
<para>
--
2.47.3
[application/pgp-keys] OpenPGP_0xB58CF11D3C9DDEA9.asc (1.7K, ../../bc3ce420-7e9e-4ef6-8096-6051a579be3d@fromdual.com/3-OpenPGP_0xB58CF11D3C9DDEA9.asc)
download
[application/pgp-signature] OpenPGP_signature.asc (494B, ../../bc3ce420-7e9e-4ef6-8096-6051a579be3d@fromdual.com/4-OpenPGP_signature.asc)
download
^ permalink raw reply [nested|flat] 5+ messages in thread
end of thread, other threads:[~2026-08-06 08:12 UTC | newest]
Thread overview: 5+ messages (download: mbox mbox.gz follow: Atom feed)
-- links below jump to the message on this page --
2026-07-31 09:08 References/Links missing PG Doc comments form <noreply@postgresql.org>
2026-08-01 18:47 ` Daniel Gustafsson <daniel@yesql.se>
2026-08-03 07:20 ` Oli Sennhauser <oli.sennhauser@fromdual.com>
2026-08-03 13:49 ` Daniel Gustafsson <daniel@yesql.se>
2026-08-06 08:12 ` Oli Sennhauser <oli.sennhauser@fromdual.com>
This inbox is served by agora; see mirroring instructions
for how to clone and mirror all data and code used for this inbox