From 1c99d8186fbf3a55de4d7b6dd03a1a0ba4ed8997 Mon Sep 17 00:00:00 2001
From: Michael Paquier <michael@paquier.xyz>
Date: Wed, 20 Nov 2024 14:21:17 +0900
Subject: [PATCH] doc: Fix section of functions age(xid) and mxid_age(xid)

In 17~, age(xid) and mxid_age(xid) were listed as deprecated.  Based on
the discussion that led to 48b5aa3143, this is not intentional as this
could break many existing monitoring queries.  Note that vacuumdb also
uses both of them.

In 16, both functions were listed under "Control Data Functions", which
is incorrect, so let's move them to the list of functions related to
transaction IDs and snapshots.

Author: Bertrand Drouvot
Discussion: https://postgr.es/m/Zzr2zZFyeFKXWe8a@ip-10-97-1-34.eu-west-3.compute.internal
Discussion: https://postgr.es/m/20231114013224.4z6oxa6p6va33rxr@awork3.anarazel.de
Backpatch-through: 16
---
 doc/src/sgml/func.sgml | 58 ++++++++++++++++++++++--------------------
 1 file changed, 30 insertions(+), 28 deletions(-)

diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index 51fcfc26c9..042b225b92 100644
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -25365,6 +25365,34 @@ SELECT collation for ('foo' COLLATE "de_DE");
      </thead>
 
      <tbody>
+      <row>
+       <entry role="func_table_entry"><para role="func_signature">
+        <indexterm>
+         <primary>age</primary>
+        </indexterm>
+        <function>age</function>  ( <type>xid</type> )
+        <returnvalue>integer</returnvalue>
+       </para>
+       <para>
+        Returns the number of transactions between the supplied
+        transaction id and the current transaction counter.
+       </para></entry>
+      </row>
+
+      <row>
+       <entry role="func_table_entry"><para role="func_signature">
+        <indexterm>
+         <primary>mxid_age</primary>
+        </indexterm>
+        <function>mxid_age</function>  ( <type>xid</type> )
+        <returnvalue>integer</returnvalue>
+       </para>
+       <para>
+        Returns the number of multixacts IDs between the supplied
+        multixact ID and the current multixacts counter.
+       </para></entry>
+      </row>
+
       <row>
        <entry role="func_table_entry"><para role="func_signature">
         <indexterm>
@@ -25509,7 +25537,8 @@ SELECT collation for ('foo' COLLATE "de_DE");
    <para>
     The internal transaction ID type <type>xid</type> is 32 bits wide and
     wraps around every 4 billion transactions.  However,
-    the functions shown in <xref linkend="functions-pg-snapshot"/> use a
+    the functions shown in <xref linkend="functions-pg-snapshot"/>, except
+    <function>age</function> and <function>mxid_age</function>, use a
     64-bit type <type>xid8</type> that does not wrap around during the life
     of an installation and can be converted to <type>xid</type> by casting if
     required;  see <xref linkend="transaction-id"/> for details.
@@ -25806,33 +25835,6 @@ SELECT collation for ('foo' COLLATE "de_DE");
      </thead>
 
      <tbody>
-      <row>
-       <entry role="func_table_entry"><para role="func_signature">
-        <indexterm>
-         <primary>age</primary>
-        </indexterm>
-        <function>age</function>  ( <type>xid</type> )
-        <returnvalue>integer</returnvalue>
-       </para>
-       <para>
-        Returns the number of transactions between the supplied
-        transaction id and the current transaction counter.
-       </para></entry>
-      </row>
-
-      <row>
-       <entry role="func_table_entry"><para role="func_signature">
-        <indexterm>
-         <primary>mxid_age</primary>
-        </indexterm>
-        <function>mxid_age</function>  ( <type>xid</type> )
-        <returnvalue>integer</returnvalue>
-       </para>
-       <para>
-        Returns the number of multixacts IDs between the supplied
-        multixact ID and the current multixacts counter.
-       </para></entry>
-      </row>
 
       <row>
        <entry role="func_table_entry"><para role="func_signature">