From 09d9800e52822ed20d69d98aaa39d3fb10769c44 Mon Sep 17 00:00:00 2001
From: Robert Haas <rhaas@postgresql.org>
Date: Mon, 15 Apr 2024 15:46:19 -0400
Subject: [PATCH] docs: Consolidate into new "WAL for Extensions" chapter.

Previously, we had consecutive, very short chapters called "Generic
WAL" and "Custom WAL Resource Managers," explaining different approaches
to the same problem. Merge them into a single chapter. Explain most
of the differences between the approaches in the chapter's
introductory text, rather than in the individual sections.

Discussion: http://postgr.es/m/46ac50c1-6b2a-404f-a683-b67af6ab56e9@eisentraut.org
---
 doc/src/sgml/custom-rmgr.sgml        | 11 ++++------
 doc/src/sgml/filelist.sgml           |  1 +
 doc/src/sgml/generic-wal.sgml        | 14 +++---------
 doc/src/sgml/postgres.sgml           |  3 +--
 doc/src/sgml/wal-for-extensions.sgml | 32 ++++++++++++++++++++++++++++
 5 files changed, 41 insertions(+), 20 deletions(-)
 create mode 100644 doc/src/sgml/wal-for-extensions.sgml

diff --git a/doc/src/sgml/custom-rmgr.sgml b/doc/src/sgml/custom-rmgr.sgml
index 0d98229295..3032b2dc0d 100644
--- a/doc/src/sgml/custom-rmgr.sgml
+++ b/doc/src/sgml/custom-rmgr.sgml
@@ -1,10 +1,10 @@
 <!-- doc/src/sgml/custom-rmgr.sgml -->
 
-<chapter id="custom-rmgr">
+<sect1 id="custom-rmgr">
  <title>Custom WAL Resource Managers</title>
 
  <para>
-  This chapter explains the interface between the core
+  This section explains the interface between the core
   <productname>PostgreSQL</productname> system and custom WAL resource
   managers, which enable extensions to integrate directly with the <link
   linkend="wal"><acronym>WAL</acronym></link>.
@@ -13,10 +13,7 @@
   An extension, especially a <link linkend="tableam">Table Access
   Method</link> or <link linkend="indexam">Index Access Method</link>, may
   need to use WAL for recovery, replication, and/or <link
-  linkend="logicaldecoding">Logical Decoding</link>. Custom resource managers
-  are a more flexible alternative to <link linkend="generic-wal">Generic
-  WAL</link> (which does not support logical decoding), but more complex for
-  an extension to implement.
+  linkend="logicaldecoding">Logical Decoding</link>.
  </para>
  <para>
   To create a new custom WAL resource manager, first define an
@@ -102,4 +99,4 @@ extern void RegisterCustomRmgr(RmgrId rmid, const RmgrData *rmgr);
     the custom WAL records, which may prevent the server from starting.
    </para>
  </note>
-</chapter>
+</sect1>
diff --git a/doc/src/sgml/filelist.sgml b/doc/src/sgml/filelist.sgml
index 3fb0709f5d..38ec362d8f 100644
--- a/doc/src/sgml/filelist.sgml
+++ b/doc/src/sgml/filelist.sgml
@@ -107,6 +107,7 @@
 <!ENTITY storage    SYSTEM "storage.sgml">
 <!ENTITY transaction     SYSTEM "xact.sgml">
 <!ENTITY tablesample-method SYSTEM "tablesample-method.sgml">
+<!ENTITY wal-for-extensions SYSTEM "wal-for-extensions.sgml">
 <!ENTITY generic-wal SYSTEM "generic-wal.sgml">
 <!ENTITY custom-rmgr SYSTEM "custom-rmgr.sgml">
 <!ENTITY backup-manifest SYSTEM "backup-manifest.sgml">
diff --git a/doc/src/sgml/generic-wal.sgml b/doc/src/sgml/generic-wal.sgml
index a028856d2e..41f97ad7dc 100644
--- a/doc/src/sgml/generic-wal.sgml
+++ b/doc/src/sgml/generic-wal.sgml
@@ -1,20 +1,12 @@
 <!-- doc/src/sgml/generic-wal.sgml -->
 
-<chapter id="generic-wal">
+<sect1 id="generic-wal">
  <title>Generic WAL Records</title>
 
   <para>
    Although all built-in WAL-logged modules have their own types of WAL
    records, there is also a generic WAL record type, which describes changes
-   to pages in a generic way. This is useful for extensions that provide
-   custom access methods.
-  </para>
-
-  <para>
-   In comparison with <link linkend="custom-rmgr">Custom WAL Resource
-   Managers</link>, Generic WAL is simpler for an extension to implement and
-   does not require the extension library to be loaded in order to apply the
-   records.
+   to pages in a generic way.
   </para>
 
   <note>
@@ -171,4 +163,4 @@
     </listitem>
    </itemizedlist>
   </para>
-</chapter>
+</sect1>
diff --git a/doc/src/sgml/postgres.sgml b/doc/src/sgml/postgres.sgml
index e9a350234e..ec9f90e283 100644
--- a/doc/src/sgml/postgres.sgml
+++ b/doc/src/sgml/postgres.sgml
@@ -256,8 +256,7 @@ break is not needed in a wider output rendering.
   &geqo;
   &tableam;
   &indexam;
-  &generic-wal;
-  &custom-rmgr;
+  &wal-for-extensions;
   &indextypes;
   &storage;
   &transaction;
diff --git a/doc/src/sgml/wal-for-extensions.sgml b/doc/src/sgml/wal-for-extensions.sgml
new file mode 100644
index 0000000000..4c4fb29dd1
--- /dev/null
+++ b/doc/src/sgml/wal-for-extensions.sgml
@@ -0,0 +1,32 @@
+<!-- doc/src/sgml/wal-for-extensions.sgml -->
+
+<chapter id="wal-for-extensions">
+ <title>Write Ahead Logging for Extensions</title>
+
+  <para>
+   Certain extensions, principally extensions that implement custom access
+   methods, may need to perform write-ahead logging in order to ensure
+   crash-safety. <productname>PostgreSQL</productname> provides two ways
+   for extensions to achieve this goal.
+  </para>
+
+  <para>
+   First, extensions can choose to use <link linkend="generic-wal">generic
+   WAL</link>, a special type of WAL record which describes changes to pages
+   in a generic way. This method is simple to implement and does not require
+   that an extension library be loaded in order to apply the records. However,
+   generic WAL records will be ignored when performing logical decoding.
+  </para>
+
+  <para>
+   Second, extensions can choose to use a <link linkend="custom-rmgr">custom
+   resource manager</link>. This method is more flexible, supports logical
+   decoding, and can sometimes generate much smaller write-ahead log records
+   than would be possible with generic WAL. However, it is more complex for an
+   extension to implement.
+  </para>
+
+&generic-wal;
+&custom-rmgr;
+
+</chapter>