Skip to content

Commit 625f5aa

Browse files
sfrostsfrost
committed
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
1 parent 1b4dd6a commit 625f5aa

File tree

6 files changed

+119
-0
lines changed

6 files changed

+119
-0
lines changed

‎doc/src/sgml/appendix-obsolete-pgreceivexlog.sgml

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
<!-- doc/src/sgml/obsolete-pgxlogdump.sgml -->
2+
<!--
3+
See doc/src/sgml/obsolete.sgml for why this file exists. Do not change the id attribute.
4+
-->
5+
6+
<sect1 id="app-pgreceivexlog" xreflabel="pg_receivexlog">
7+
<title><command>pg_receivexlog</command> renamed to <command>pg_receivewal</command></title>
8+
9+
<indexterm>
10+
<primary>pg_receivexlog</primary>
11+
<see>pg_receivewal</see>
12+
</indexterm>
13+
14+
<para>
15+
PostgreSQL 9.6 and below provided a command named
16+
<command>pg_receivexlog</command>
17+
<indexterm><primary>pg_receivexlog</primary></indexterm>
18+
to fetch write-ahead-log (WAL) files. This command was renamed to <command>pg_receivewal</command>, see
19+
<xref linkend="app-pgreceivewal"/> for documentation of <command>pg_receivewal</command> and see
20+
<link linkend="release-prior">the release notes for PostgreSQL 10</link> for details
21+
on this change.
22+
</para>
23+
24+
</sect1>

‎doc/src/sgml/appendix-obsolete-pgresetxlog.sgml

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
<!-- doc/src/sgml/obsolete-pgresetxlog.sgml -->
2+
<!--
3+
See doc/src/sgml/obsolete.sgml for why this file exists. Do not change the id attribute.
4+
-->
5+
6+
<sect1 id="app-pgresetxlog" xreflabel="pg_resetxlog">
7+
<title><command>pg_resetxlog</command> renamed to <command>pg_resetwal</command></title>
8+
9+
<indexterm>
10+
<primary>pg_resetxlog</primary>
11+
<see>pg_resetwal</see>
12+
</indexterm>
13+
14+
<para>
15+
PostgreSQL 9.6 and below provided a command named
16+
<command>pg_resetxlog</command>
17+
<indexterm><primary>pg_resetxlog</primary></indexterm>
18+
to reset the write-ahead-log (WAL) files. This command was renamed to <command>pg_resetwal</command>, see
19+
<xref linkend="app-pgresetwal"/> for documentation of <command>pg_resetwal</command> and see
20+
<link linkend="release-prior">the release notes for PostgreSQL 10</link> for details
21+
on this change.
22+
</para>
23+
24+
</sect1>

‎doc/src/sgml/appendix-obsolete-pgxlogdump.sgml

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
<!-- doc/src/sgml/obsolete-pgxlogdump.sgml -->
2+
<!--
3+
See doc/src/sgml/obsolete.sgml for why this file exists. Do not change the id attribute.
4+
-->
5+
6+
<sect1 id="pgxlogdump" xreflabel="pg_xlogdump">
7+
<title><command>pg_xlogdump</command> renamed to <command>pg_waldump</command></title>
8+
9+
<indexterm>
10+
<primary>pg_xlogdump</primary>
11+
<see>pg_waldump</see>
12+
</indexterm>
13+
14+
<para>
15+
PostgreSQL 9.6 and below provided a command named
16+
<command>pg_xlogdump</command>
17+
<indexterm><primary>pg_xlogdump</primary></indexterm>
18+
to read write-ahead-log (WAL) files. This command was renamed to <command>pg_waldump</command>, see
19+
<xref linkend="pgwaldump"/> for documentation of <command>pg_waldump</command> and see
20+
<link linkend="release-prior">the release notes for PostgreSQL 10</link> for details
21+
on this change.
22+
</para>
23+
24+
</sect1>

‎doc/src/sgml/appendix-obsolete.sgml

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
<!-- doc/src/sgml/obsolete.sgml -->
2+
3+
<appendix id="appendix-obsolete">
4+
<title>Obsolete or Renamed Features</title>
5+
6+
<para>
7+
Functionality is sometimes removed from PostgreSQL, feature, setting
8+
and file names sometimes change, or documentation moves to different
9+
places. This section directs users coming from old versions of the
10+
documentation or from external links to the appropriate new location
11+
for the information they need.
12+
</para>
13+
14+
<!--
15+
This section exists so that people following /current/ links to documentation
16+
don't get a 404 when we move or rename things. And users who find old versions
17+
of the docs in searches or old command names when checking the index can
18+
follow links to the new commands.
19+
20+
Each subsection here should retain the same <chapter>, <appendix> and/or
21+
<sect1> "id" attribute that was used for the relevant documentation before
22+
it was renamed or moved. Do not prepend "obsolete-" or anything, keep it
23+
exactly the same. These ids are used to determine the filenames for generated
24+
HTML docs so changing them will break links.
25+
26+
Each entry should also insert index terms redirecting from the old to new
27+
names. The recommended spelling is
28+
29+
<indexterm><primary>oldname</primary><see>newname</see></indexterm>
30+
31+
We don't bother with attempting to maintain down-version linking, e.g from
32+
pg_waldump to pg_xlogdump. Users of old versions should use old docs. There
33+
is no need to add index terms pointing from the new to old names.
34+
-->
35+
36+
&obsolete-pgxlogdump;
37+
&obsolete-pgresetxlog;
38+
&obsolete-pgreceivexlog;
39+
40+
</appendix>

‎doc/src/sgml/filelist.sgml

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -177,3 +177,9 @@
177177

178178
<!-- back matter -->
179179
<!ENTITY biblio SYSTEM "biblio.sgml">
180+
181+
<!-- Stubs for removed entries to preserve public links -->
182+
<!ENTITY obsolete SYSTEM "appendix-obsolete.sgml">
183+
<!ENTITY obsolete-pgxlogdump SYSTEM "appendix-obsolete-pgxlogdump.sgml">
184+
<!ENTITY obsolete-pgresetxlog SYSTEM "appendix-obsolete-pgresetxlog.sgml">
185+
<!ENTITY obsolete-pgreceivexlog SYSTEM "appendix-obsolete-pgreceivexlog.sgml">

‎doc/src/sgml/postgres.sgml

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -277,6 +277,7 @@
277277
&sourcerepo;
278278
&docguide;
279279
&acronyms;
280+
&obsolete;
280281

281282
</part>
282283

0 commit comments

Comments
 (0)