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..4a293b6
--- /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..a17cbce
--- /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..28e004e
--- /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.sgml b/doc/src/sgml/appendix-obsolete.sgml
new file mode 100644 (file)
index 0000000..548297e
--- /dev/null
+++ b/doc/src/sgml/appendix-obsolete.sgml
@@ -0,0 +1,40 @@
+<!-- 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-pgxlogdump;
+ &obsolete-pgresetxlog;
+ &obsolete-pgreceivexlog;
+
+</appendix>

diff --git a/doc/src/sgml/filelist.sgml b/doc/src/sgml/filelist.sgml
index 8afe1a6b400a6dd8b8c8d10a22cc80e9bb7cd53a..2f9d192c410e8f45eef7d906c48d7d235950353d 100644 (file)
--- a/doc/src/sgml/filelist.sgml
+++ b/doc/src/sgml/filelist.sgml
@@ -178,6 +178,12 @@
 <!-- back matter -->
 <!ENTITY biblio     SYSTEM "biblio.sgml">
 
+<!-- Stubs for removed entries to preserve public links -->
+<!ENTITY obsolete SYSTEM "appendix-obsolete.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">
+
 <!--
  Some parts of the documentation are also source for some plain-text
  files used during installation.  To selectively ignore or include

diff --git a/doc/src/sgml/postgres.sgml b/doc/src/sgml/postgres.sgml
index 8a3bfc9b0d3cc331db55f7b708026b4810f2a599..0eba39d17a046d82b7232dbda63d3ad6737bedba 100644 (file)
--- a/doc/src/sgml/postgres.sgml
+++ b/doc/src/sgml/postgres.sgml
@@ -273,6 +273,7 @@
   &sourcerepo;
   &docguide;
   &acronyms;
+  &obsolete;
 
  </part>