From 3b427f860b36037a43203eab89c382c6f0297331 Mon Sep 17 00:00:00 2001 From: Stephen Frost Date: Sun, 28 Mar 2021 11:46:33 -0400 Subject: [PATCH] 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 --- .../sgml/appendix-obsolete-pgreceivexlog.sgml | 24 +++++++++++ .../sgml/appendix-obsolete-pgresetxlog.sgml | 24 +++++++++++ .../sgml/appendix-obsolete-pgxlogdump.sgml | 24 +++++++++++ doc/src/sgml/appendix-obsolete.sgml | 40 +++++++++++++++++++ doc/src/sgml/filelist.sgml | 6 +++ doc/src/sgml/postgres.sgml | 1 + 6 files changed, 119 insertions(+) create mode 100644 doc/src/sgml/appendix-obsolete-pgreceivexlog.sgml create mode 100644 doc/src/sgml/appendix-obsolete-pgresetxlog.sgml create mode 100644 doc/src/sgml/appendix-obsolete-pgxlogdump.sgml create mode 100644 doc/src/sgml/appendix-obsolete.sgml diff --git a/doc/src/sgml/appendix-obsolete-pgreceivexlog.sgml b/doc/src/sgml/appendix-obsolete-pgreceivexlog.sgml new file mode 100644 index 0000000000..4a293b6490 --- /dev/null +++ b/doc/src/sgml/appendix-obsolete-pgreceivexlog.sgml @@ -0,0 +1,24 @@ + + + + + <command>pg_receivexlog</command> renamed to <command>pg_receivewal</command> + + + pg_receivexlog + pg_receivewal + + + + PostgreSQL 9.6 and below provided a command named + pg_receivexlog + pg_receivexlog + to fetch write-ahead-log (WAL) files. This command was renamed to pg_receivewal, see + for documentation of pg_receivewal and see + the release notes for PostgreSQL 10 for details + on this change. + + + diff --git a/doc/src/sgml/appendix-obsolete-pgresetxlog.sgml b/doc/src/sgml/appendix-obsolete-pgresetxlog.sgml new file mode 100644 index 0000000000..a17cbce563 --- /dev/null +++ b/doc/src/sgml/appendix-obsolete-pgresetxlog.sgml @@ -0,0 +1,24 @@ + + + + + <command>pg_resetxlog</command> renamed to <command>pg_resetwal</command> + + + pg_resetxlog + pg_resetwal + + + + PostgreSQL 9.6 and below provided a command named + pg_resetxlog + pg_resetxlog + to reset the write-ahead-log (WAL) files. This command was renamed to pg_resetwal, see + for documentation of pg_resetwal and see + the release notes for PostgreSQL 10 for details + on this change. + + + diff --git a/doc/src/sgml/appendix-obsolete-pgxlogdump.sgml b/doc/src/sgml/appendix-obsolete-pgxlogdump.sgml new file mode 100644 index 0000000000..28e004edea --- /dev/null +++ b/doc/src/sgml/appendix-obsolete-pgxlogdump.sgml @@ -0,0 +1,24 @@ + + + + + <command>pg_xlogdump</command> renamed to <command>pg_waldump</command> + + + pg_xlogdump + pg_waldump + + + + PostgreSQL 9.6 and below provided a command named + pg_xlogdump + pg_xlogdump + to read write-ahead-log (WAL) files. This command was renamed to pg_waldump, see + for documentation of pg_waldump and see + the release notes for PostgreSQL 10 for details + on this change. + + + diff --git a/doc/src/sgml/appendix-obsolete.sgml b/doc/src/sgml/appendix-obsolete.sgml new file mode 100644 index 0000000000..548297e2d3 --- /dev/null +++ b/doc/src/sgml/appendix-obsolete.sgml @@ -0,0 +1,40 @@ + + + + Obsolete or Renamed Features + + + 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. + + + + + &obsolete-pgxlogdump; + &obsolete-pgresetxlog; + &obsolete-pgreceivexlog; + + diff --git a/doc/src/sgml/filelist.sgml b/doc/src/sgml/filelist.sgml index 8afe1a6b40..2f9d192c41 100644 --- a/doc/src/sgml/filelist.sgml +++ b/doc/src/sgml/filelist.sgml @@ -178,6 +178,12 @@ + + + + + +