Improve documentation of pageinspect

michaelpq · michaelpq · commit 292ae8af79b4 · 2019-08-23T20:41:06.000+09:00
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
diff --git 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>
 
