From be1ac8d7945668d5e31cb2c8aeabe879bfb9f86e Mon Sep 17 00:00:00 2001
From: "David G. Johnston" <David.G.Johnston@Gmail.com>
Date: Wed, 26 Mar 2025 17:12:57 -0700
Subject: [PATCH] doc: Explain use of symbolic linking for pg_wal

---
 doc/src/sgml/ref/initdb.sgml | 15 ++++++++++++++-
 doc/src/sgml/wal.sgml        |  2 ++
 2 files changed, 16 insertions(+), 1 deletion(-)

diff --git a/doc/src/sgml/ref/initdb.sgml b/doc/src/sgml/ref/initdb.sgml
index 0026318485..fa25e2662d 100644
--- a/doc/src/sgml/ref/initdb.sgml
+++ b/doc/src/sgml/ref/initdb.sgml
@@ -413,6 +413,7 @@ PostgreSQL documentation
        <para>
         This option specifies the directory where the write-ahead log
         should be stored.
+        See <xref linkend="app-initdb-notes"/> for more information.
        </para>
       </listitem>
      </varlistentry>
@@ -661,13 +662,25 @@ PostgreSQL documentation
 
  </refsect1>
 
- <refsect1>
+ <refsect1 id="app-initdb-notes" xreflabel="Notes">
   <title>Notes</title>
 
   <para>
    <command>initdb</command> can also be invoked via
    <command>pg_ctl initdb</command>.
   </para>
+
+  <para>
+   The <filename>pg_wal</filename> subdirectory will always exist within the
+   data directory.  This is where <productname>PostgreSQL</productname>
+   sends its write-ahead log (<acronym>WAL</acronym>) files.
+   Specifying the <option>--waldir</option> option turns this subdirectory entry
+   into a symbolic link. In general, this is only useful if the remote location
+   is on a different physical device.  An existing directory must be empty and
+   should not be a mount point.  The directory will be created
+   (including missing parents) if necessary.
+  </para>
+
  </refsect1>
 
  <refsect1>
diff --git a/doc/src/sgml/wal.sgml b/doc/src/sgml/wal.sgml
index f3b86b26be..bd45df0a3b 100644
--- a/doc/src/sgml/wal.sgml
+++ b/doc/src/sgml/wal.sgml
@@ -897,6 +897,8 @@
    <filename>pg_wal</filename> directory to another location (while the server
    is shut down, of course) and creating a symbolic link from the
    original location in the main data directory to the new location.
+   <application><xref linkend="app-initdb"/></application> will do this during
+   bootstrap if the <option>--waldir</option> option is specified.
   </para>
 
   <para>
-- 
2.34.1