5 files changed, 41 insertions, 20 deletions
diff --git a/doc/src/sgml/custom-rmgr.sgml b/doc/src/sgml/custom-rmgr.sgml
index 0d982292951..3032b2dc0d2 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 3fb0709f5df..38ec362d8f4 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 a028856d2eb..41f97ad7dc8 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 e9a350234e7..ec9f90e283e 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 00000000000..4c4fb29dd19
--- /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>