Add a docs section for obsoleted and renamed functions and settings

The new appendix groups information on renamed or removed settings,
commands, etc into an out-of-the-way part of the docs.

The original id elements are retained in each subsection to ensure that
the same filenames are produced for HTML docs. This prevents /current/
links on the web from breaking, and allows users of the web docs
to follow links from old version pages to info on the changes in the
new version. Prior to this change, a link to /current/ for renamed
sections like the recovery.conf docs would just 404. Similarly if
someone searched for recovery.conf they would find the pg11 docs,
but there would be no /12/ or /current/ link, so they couldn't easily
find out that it was removed in pg12 or how to adapt.

Index entries are also added so that there's a breadcrumb trail for
users to follow when they know the old name, but not what we changed it
to. So a user who is trying to find out how to set standby_mode in
PostgreSQL 12+, or where pg_resetxlog went, now has more chance of
finding that information.

Craig Ringer and Stephen Frost
Reviewed-by: Euler Taveira
Discussion: https://postgr.es/m/CAGRY4nzPNOyYQ_1-pWYToUVqQ0ThqP5jdURnJMZPm539fdizOg%40mail.gmail.com
Backpatch-through: 10

diff --git a/doc/src/sgml/appendix-obsolete-pgreceivexlog.sgml b/doc/src/sgml/appendix-obsolete-pgreceivexlog.sgml
new file mode 100644 (file)
index 0000000..f74d0ae
--- /dev/null
+++ b/doc/src/sgml/appendix-obsolete-pgreceivexlog.sgml
@@ -0,0 +1,24 @@
+<!-- doc/src/sgml/obsolete-pgxlogdump.sgml -->
+<!--
+  See doc/src/sgml/obsolete.sgml for why this file exists. Do not change the id attribute.
+-->
+
+<sect1 id="app-pgreceivexlog" xreflabel="pg_receivexlog">
+  <title><command>pg_receivexlog</command> renamed to <command>pg_receivewal</command></title>
+
+   <indexterm>
+     <primary>pg_receivexlog</primary>
+     <see>pg_receivewal</see>
+   </indexterm>
+
+   <para>
+    PostgreSQL 9.6 and below provided a command named
+    <command>pg_receivexlog</command>
+    <indexterm><primary>pg_receivexlog</primary></indexterm>
+    to fetch write-ahead-log (WAL) files.  This command was renamed to <command>pg_receivewal</command>, see
+    <xref linkend="app-pgreceivewal"/> for documentation of <command>pg_receivewal</command> and see
+    <link linkend="release-prior">the release notes for PostgreSQL 10</link> for details
+    on this change.
+   </para>
+
+</sect1>

diff --git a/doc/src/sgml/appendix-obsolete-pgresetxlog.sgml b/doc/src/sgml/appendix-obsolete-pgresetxlog.sgml
new file mode 100644 (file)
index 0000000..7d99930
--- /dev/null
+++ b/doc/src/sgml/appendix-obsolete-pgresetxlog.sgml
@@ -0,0 +1,24 @@
+<!-- doc/src/sgml/obsolete-pgresetxlog.sgml -->
+<!--
+  See doc/src/sgml/obsolete.sgml for why this file exists. Do not change the id attribute.
+-->
+
+<sect1 id="app-pgresetxlog" xreflabel="pg_resetxlog">
+  <title><command>pg_resetxlog</command> renamed to <command>pg_resetwal</command></title>
+
+   <indexterm>
+     <primary>pg_resetxlog</primary>
+     <see>pg_resetwal</see>
+   </indexterm>
+
+   <para>
+    PostgreSQL 9.6 and below provided a command named
+    <command>pg_resetxlog</command>
+    <indexterm><primary>pg_resetxlog</primary></indexterm>
+    to reset the write-ahead-log (WAL) files.  This command was renamed to <command>pg_resetwal</command>, see
+    <xref linkend="app-pgresetwal"/> for documentation of <command>pg_resetwal</command> and see
+    <link linkend="release-prior">the release notes for PostgreSQL 10</link> for details
+    on this change.
+   </para>
+
+</sect1>

diff --git a/doc/src/sgml/appendix-obsolete-pgxlogdump.sgml b/doc/src/sgml/appendix-obsolete-pgxlogdump.sgml
new file mode 100644 (file)
index 0000000..4173fee
--- /dev/null
+++ b/doc/src/sgml/appendix-obsolete-pgxlogdump.sgml
@@ -0,0 +1,24 @@
+<!-- doc/src/sgml/obsolete-pgxlogdump.sgml -->
+<!--
+  See doc/src/sgml/obsolete.sgml for why this file exists. Do not change the id attribute.
+-->
+
+<sect1 id="pgxlogdump" xreflabel="pg_xlogdump">
+  <title><command>pg_xlogdump</command> renamed to <command>pg_waldump</command></title>
+
+   <indexterm>
+     <primary>pg_xlogdump</primary>
+     <see>pg_waldump</see>
+   </indexterm>
+
+   <para>
+    PostgreSQL 9.6 and below provided a command named
+    <command>pg_xlogdump</command>
+    <indexterm><primary>pg_xlogdump</primary></indexterm>
+    to read write-ahead-log (WAL) files.  This command was renamed to <command>pg_waldump</command>, see
+    <xref linkend="pgwaldump"/> for documentation of <command>pg_waldump</command> and see
+    <link linkend="release-prior">the release notes for PostgreSQL 10</link> for details
+    on this change.
+   </para>
+
+</sect1>

diff --git a/doc/src/sgml/appendix-obsolete-recovery-config.sgml b/doc/src/sgml/appendix-obsolete-recovery-config.sgml
new file mode 100644 (file)
index 0000000..77c4289
--- /dev/null
+++ b/doc/src/sgml/appendix-obsolete-recovery-config.sgml
@@ -0,0 +1,58 @@
+<!-- doc/src/sgml/obsolete-recovery-config.sgml -->
+<!--
+  See doc/src/sgml/obsolete.sgml for why this file exists. Do not change the id attribute.
+-->
+
+<sect1 id="recovery-config" xreflabel="recovery.conf">
+  <title><filename>recovery.conf</filename> file merged into <filename>postgresql.conf</filename></title>
+
+   <indexterm>
+     <primary><filename>recovery.conf</filename></primary>
+   </indexterm>
+
+   <para>
+    PostgreSQL 11 and below used a configuration file named
+    <filename>recovery.conf</filename>
+    <indexterm><primary>recovery.conf</primary></indexterm>
+    to manage replicas and standbys. Support for this file was removed in PostgreSQL 12. See
+    <link linkend="release-prior">the release notes for PostgreSQL 12</link> for details
+    on this change.
+   </para>
+
+   <para>
+    On PostgreSQL 12 and above,
+    <link linkend="continuous-archiving">archive recovery, streaming replication, and PITR</link>
+    are configured using
+    <link linkend="runtime-config-replication-standby">normal server configuration parameters</link>.
+    These are set in <filename>postgresql.conf</filename> or via
+    <link linkend="sql-altersystem">ALTER SYSTEM</link>
+    like any other parameter.
+   </para>
+
+   <para>
+    The server will not start if a <filename>recovery.conf</filename> exists.
+   </para>
+
+   <para>
+    The
+    <literal>trigger_file</literal>
+    <indexterm>
+     <primary>trigger_file</primary>
+     <see>promote_trigger_file</see>
+    </indexterm>
+    setting has been renamed to
+    <xref linkend="guc-promote-trigger-file"/>.
+   </para>
+
+   <para>
+    The
+    <literal>standby_mode</literal>
+    <indexterm>
+     <primary>standby_mode</primary>
+     <see>standby.signal</see>
+    </indexterm>
+    setting has been removed. A <filename>standby.signal</filename> file in the data directory
+    is used instead. See <xref linkend="standby-server-operation"/> for details.
+   </para>
+
+</sect1>

diff --git a/doc/src/sgml/appendix-obsolete.sgml b/doc/src/sgml/appendix-obsolete.sgml
new file mode 100644 (file)
index 0000000..ffd7d40
--- /dev/null
+++ b/doc/src/sgml/appendix-obsolete.sgml
@@ -0,0 +1,41 @@
+<!-- doc/src/sgml/obsolete.sgml -->
+
+<appendix id="appendix-obsolete">
+ <title>Obsolete or Renamed Features</title>
+
+ <para>
+   Functionality is sometimes removed from PostgreSQL, feature, setting
+   and file names sometimes change, or documentation moves to different
+   places. This section directs users coming from old versions of the
+   documentation or from external links to the appropriate new location
+   for the information they need.
+ </para>
+
+ <!--
+  This section exists so that people following /current/ links to documentation
+  don't get a 404 when we move or rename things. And users who find old versions
+  of the docs in searches or old command names when checking the index can
+  follow links to the new commands.
+
+  Each subsection here should retain the same <chapter>, <appendix> and/or
+  <sect1> "id" attribute that was used for the relevant documentation before
+  it was renamed or moved. Do not prepend "obsolete-" or anything, keep it
+  exactly the same. These ids are used to determine the filenames for generated
+  HTML docs so changing them will break links.
+
+  Each entry should also insert index terms redirecting from the old to new
+  names. The recommended spelling is
+
+      <indexterm><primary>oldname</primary><see>newname</see></indexterm>
+
+  We don't bother with attempting to maintain down-version linking, e.g from
+  pg_waldump to pg_xlogdump. Users of old versions should use old docs. There
+  is no need to add index terms pointing from the new to old names.
+ -->
+
+ &obsolete-recovery-config;
+ &obsolete-pgxlogdump;
+ &obsolete-pgresetxlog;
+ &obsolete-pgreceivexlog;
+
+</appendix>

diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml
index dd2778611f826dd16bc2c2dbdf18634cbc7e3547..28fd0670f763d385b9128d8289ea1dc4596fe439 100644 (file)
--- a/doc/src/sgml/config.sgml
+++ b/doc/src/sgml/config.sgml
@@ -4196,8 +4196,9 @@ ANY <replaceable class="parameter">num_sync</replaceable> ( <replaceable class="
      <title>Standby Servers</title>
 
      <para>
-      These settings control the behavior of a standby server that is
-      to receive replication data.  Their values on the master server
+      These settings control the behavior of a
+      <link linkend="standby-server-operation">standby server</link>
+      that is to receive replication data.  Their values on the master server
       are irrelevant.
      </para>
 

diff --git a/doc/src/sgml/filelist.sgml b/doc/src/sgml/filelist.sgml
index 68179f71cdbdec03ce62b4d445f96c80a77b1a40..6c8b12376ed78db11d620b21f2fa96e3b16f400a 100644 (file)
--- a/doc/src/sgml/filelist.sgml
+++ b/doc/src/sgml/filelist.sgml
@@ -182,3 +182,10 @@
 
 <!-- back matter -->
 <!ENTITY biblio     SYSTEM "biblio.sgml">
+
+<!-- Stubs for removed entries to preserve public links -->
+<!ENTITY obsolete SYSTEM "appendix-obsolete.sgml">
+<!ENTITY obsolete-recovery-config SYSTEM "appendix-obsolete-recovery-config.sgml">
+<!ENTITY obsolete-pgxlogdump SYSTEM "appendix-obsolete-pgxlogdump.sgml">
+<!ENTITY obsolete-pgresetxlog SYSTEM "appendix-obsolete-pgresetxlog.sgml">
+<!ENTITY obsolete-pgreceivexlog SYSTEM "appendix-obsolete-pgreceivexlog.sgml">

diff --git a/doc/src/sgml/high-availability.sgml b/doc/src/sgml/high-availability.sgml
index 2e7fa4a92e5e1976f5ebdfaff6d8a51b87833e46..37c44396f85b072d73cb82d953a2b6faed866fd9 100644 (file)
--- a/doc/src/sgml/high-availability.sgml
+++ b/doc/src/sgml/high-availability.sgml
@@ -615,9 +615,17 @@ protocol to make nodes agree on a serializable transactional order.
 
   </sect2>
 
-  <sect2 id="standby-server-operation">
+  <sect2 id="standby-server-operation" xreflabel="Standby Server Operation">
    <title>Standby Server Operation</title>
 
+   <para>
+    A server enters standby mode if a
+    <anchor id="file-standby-signal" xreflabel="standby.signal"/>
+    <filename>standby.signal</filename>
+    <indexterm><primary><filename>standby.signal</filename></primary></indexterm>
+    file exists in the data directory when the server is started.
+   </para>
+
    <para>
     In standby mode, the server continuously applies WAL received from the
     master server. The standby server can read WAL from a WAL archive
@@ -691,7 +699,8 @@ protocol to make nodes agree on a serializable transactional order.
    <para>
     To set up the standby server, restore the base backup taken from primary
     server (see <xref linkend="backup-pitr-recovery"/>). Create a file
-    <filename>standby.signal</filename> in the standby's cluster data
+    <link linkend="file-standby-signal"><filename>standby.signal</filename></link><indexterm><primary>standby.signal</primary></indexterm>
+    in the standby's cluster data
     directory. Set <xref linkend="guc-restore-command"/> to a simple command to copy files from
     the WAL archive. If you plan to have multiple standby servers for high
     availability purposes, make sure that <varname>recovery_target_timeline</varname> is set to
@@ -2114,7 +2123,8 @@ if (!triggered)
 
    <para>
     If <varname>hot_standby</varname> is <literal>on</literal> in <filename>postgresql.conf</filename>
-    (the default value) and there is a <filename>standby.signal</filename>
+    (the default value) and there is a
+    <link linkend="file-standby-signal"><filename>standby.signal</filename></link><indexterm><primary>standby.signal</primary><secondary>for hot standby</secondary></indexterm>
     file present, the server will run in Hot Standby mode.
     However, it may take some time for Hot Standby connections to be allowed,
     because the server will not accept connections until it has completed

diff --git a/doc/src/sgml/postgres.sgml b/doc/src/sgml/postgres.sgml
index c41ce9499be42f54422732be8a8194aa2b42d5b7..763941e1e17b733a5c373fa98260d5dd39623099 100644 (file)
--- a/doc/src/sgml/postgres.sgml
+++ b/doc/src/sgml/postgres.sgml
@@ -288,6 +288,7 @@ break is not needed in a wider output rendering.
   &acronyms;
   &glossary;
   &color;
+  &obsolete;
 
  </part>
 

diff --git a/doc/src/sgml/ref/pg_basebackup.sgml b/doc/src/sgml/ref/pg_basebackup.sgml
index 03f31b2879d2f0bffe1ae4bade5766383f155cfa..ac442b81a5d5d6b89c09a7f5c4f1a403d3485006 100644 (file)
--- a/doc/src/sgml/ref/pg_basebackup.sgml
+++ b/doc/src/sgml/ref/pg_basebackup.sgml
@@ -199,7 +199,10 @@ PostgreSQL documentation
       <listitem>
 
        <para>
-        Creates a <filename>standby.signal</filename> file and appends
+        Creates a
+        <link linkend="file-standby-signal"><filename>standby.signal</filename></link>
+        <indexterm><primary><filename>standby.signal</filename></primary><secondary>pg_basebackup --write-recovery-conf</secondary></indexterm>
+        file and appends
         connection settings to the <filename>postgresql.auto.conf</filename>
         file in the target directory (or within the base archive file when
         using tar format).  This eases setting up a standby server using the