From 6472d7ad5d70690438385bb90460a1e84553c6d9 Mon Sep 17 00:00:00 2001
From: Michael Paquier <michael@paquier.xyz>
Date: Fri, 23 Aug 2019 20:41:18 +0900
Subject: [PATCH] Improve documentation of pageinspect

This adds a section for heap-related functions.  These were previously
mixed with functions having a more general purpose, leading to
confusion.  While on it, add a query example for fsm_page_contents.

Backpatch down to 10, where b5e3942 introduced the subsections for
function types in pageinspect documentation.

Author: Masahiko Sawada
Discussion: https://postgr.es/m/CAD21AoDyM7E1+cK3-aWejxKTGC-wVVP2B+RnJhN6inXyeRmqzw@mail.gmail.com
Backpatch-through: 10
---
 doc/src/sgml/pageinspect.sgml | 56 +++++++++++++++++++++--------------
 1 file changed, 33 insertions(+), 23 deletions(-)

diff --git a/doc/src/sgml/pageinspect.sgml b/doc/src/sgml/pageinspect.sgml
index 8d81f8894e..cb08c7632b 100644
--- a/doc/src/sgml/pageinspect.sgml
+++ b/doc/src/sgml/pageinspect.sgml
@@ -125,6 +125,39 @@ test=# SELECT page_checksum(get_raw_page('pg_class', 0), 0);
     </listitem>
    </varlistentry>
 
+   <varlistentry>
+    <term>
+     <function>fsm_page_contents(page bytea) returns text</function>
+     <indexterm>
+      <primary>fsm_page_contents</primary>
+     </indexterm>
+    </term>
+
+    <listitem>
+     <para>
+      <function>fsm_page_contents</function> shows the internal node structure
+      of a FSM page.  For example:
+<screen>
+test=# SELECT fsm_page_contents(get_raw_page('pg_class', 'fsm', 0));
+</screen>
+      The output is a multiline string, with one line per node in the binary
+      tree within the page.  Only those nodes that are not zero are printed.
+      The so-called "next" pointer, which points to the next slot to be
+      returned from the page, is also printed.
+     </para>
+     <para>
+      See <filename>src/backend/storage/freespace/README</filename> for more
+      information on the structure of an FSM page.
+     </para>
+    </listitem>
+   </varlistentry>
+  </variablelist>
+ </sect2>
+
+ <sect2>
+  <title>Heap Functions</title>
+
+  <variablelist>
    <varlistentry>
     <term>
      <function>heap_page_items(page bytea) returns setof record</function>
@@ -203,29 +236,6 @@ test=# SELECT * FROM heap_page_item_attrs(get_raw_page('pg_class', 0), 'pg_class
      </para>
     </listitem>
    </varlistentry>
-
-   <varlistentry>
-    <term>
-     <function>fsm_page_contents(page bytea) returns text</function>
-     <indexterm>
-      <primary>fsm_page_contents</primary>
-     </indexterm>
-    </term>
-
-    <listitem>
-     <para>
-      <function>fsm_page_contents</function> shows the internal node structure
-      of a FSM page. The output is a multiline string, with one line per
-      node in the binary tree within the page. Only those nodes that are not
-      zero are printed. The so-called "next" pointer, which points to the
-      next slot to be returned from the page, is also printed.
-     </para>
-     <para>
-      See <filename>src/backend/storage/freespace/README</filename> for more
-      information on the structure of an FSM page.
-     </para>
-    </listitem>
-   </varlistentry>
   </variablelist>
  </sect2>