Subject: add free space map link in pg_freespacemap page

From: Dong Wook Lee <[email-masked]>
Date: Sun, 6 Mar 2022 23:42:53 +0900

Hi,
I found that there is a link to `pg_freespacemap` in the `free space map`
page but there is no link to `free space map` in the `pg_freespacemap`
page.

diff --git a/doc/src/sgml/pgfreespacemap.sgml
b/doc/src/sgml/pgfreespacemap.sgml
index 5025498249..0ab3307e9c 100644
--- a/doc/src/sgml/pgfreespacemap.sgml
+++ b/doc/src/sgml/pgfreespacemap.sgml
@@ -9,7 +9,7 @@

  <para>
   The <filename>pg_freespacemap</filename> module provides a means for
examining the
-  free space map (FSM). It provides a function called
+  <link linkend="storage-fsm">free space map</link> (FSM). It provides a
function called
   <function>pg_freespace</function>, or two overloaded functions, to be
   precise. The functions show the value recorded in the free space map for
   a given page, or for all pages in the relation.

so I propose a patch to fix it.

---
Regards,
Lee Dong Wook.

---

From: Laurenz Albe <[email-masked]>
Date: Mon, 07 Mar 2022 11:08:16 +0100

On Sun, 2022-03-06 at 23:42 +0900, Dong Wook Lee wrote:
> Hi,
> I found that there is a link to `pg_freespacemap` in the `free space map` page but there is no link to `free space map` in the `pg_freespacemap` page. 
> 
> diff --git a/doc/src/sgml/pgfreespacemap.sgml b/doc/src/sgml/pgfreespacemap.sgml
>    The <filename>pg_freespacemap</filename> module provides a means for examining the
> +  <link linkend="storage-fsm">free space map</link> (FSM). It provides a function called

+1

Yours,
Laurenz Albe

---

From: Michael Paquier <[email-masked]>
Date: Mon, 7 Mar 2022 21:03:23 +0900

>> so I propose a patch to fix it.

Shouldn't you use an <acronym> here?  FSM is a term listed in the
section dedicated to acronyms.
--
Michael

---

From: Dong Wook Lee <[email-masked]>
Date: Tue, 8 Mar 2022 09:31:49 +0900

I don't know about it, so should I use <acronym> at FSM for all the
acronyms in the section dedicated to acronyms?

  <para>
   The <filename>pg_freespacemap</filename> module provides a means for
examining the
-  free space map (FSM). It provides a function called
+  <link linkend="storage-fsm">free space map</link>
(<acronym>FSM</acronym>). It provides a function called
   <function>pg_freespace</function>, or two overloaded functions, to be
   precise. The functions show the value recorded in the free space map for
   a given page, or for all pages in the relation.
@@ -36,7 +36,7 @@
     <listitem>
      <para>
       Returns the amount of free space on the page of the relation,
specified
-      by <literal>blkno</literal>, according to the FSM.
+      by <literal>blkno</literal>, according to the <acronym>FSM</acronym>.
      </para>
     </listitem>
    </varlistentry>
@@ -50,7 +50,7 @@
     <listitem>
      <para>
       Displays the amount of free space on each page of the relation,
-      according to the FSM. A set of <literal>(blkno bigint, avail
int2)</literal>
+      according to the <acronym>FSM</acronym>. A set of <literal>(blkno
bigint, avail int2)</literal>
       tuples is returned, one tuple for each page in the relation.
      </para>
     </listitem>

---

From: Michael Paquier <[email-masked]>
Date: Tue, 8 Mar 2022 15:17:00 +0900

> acronyms in the section dedicated to acronyms?

Yes, I would do that on consistency grounds.  Your idea to add a link
to the section describing what a FSM is from pgfreespacemap.sgml is
also a good one.

While looking around, I have also noticed some inconsistencies within
the contents of pageinspect and all that leads me to the patch
attached.  Does that look fine to you?
--
Michael
diff --git a/doc/src/sgml/pageinspect.sgml b/doc/src/sgml/pageinspect.sgml
index 24b5e463ed..55513cf522 100644
--- a/doc/src/sgml/pageinspect.sgml
+++ b/doc/src/sgml/pageinspect.sgml
@@ -31,9 +31,11 @@
       relation and returns a copy as a <type>bytea</type> value.  This allows a
       single time-consistent copy of the block to be obtained.
       <replaceable>fork</replaceable> should be <literal>'main'</literal> for
-      the main data fork, <literal>'fsm'</literal> for the free space map,
-      <literal>'vm'</literal> for the visibility map, or <literal>'init'</literal>
-      for the initialization fork.
+      the main data fork, <literal>'fsm'</literal> for the
+      <link linkend="storage-fsm">free space map</link>,
+      <literal>'vm'</literal> for the
+      <link linkend="storage-vm">visibility map</link>, or
+      <literal>'init'</literal> for the initialization fork.
      </para>
     </listitem>
    </varlistentry>
@@ -136,7 +138,7 @@ test=# SELECT page_checksum(get_raw_page('pg_class', 0), 0);
     <listitem>
      <para>
       <function>fsm_page_contents</function> shows the internal node structure
-      of an FSM page.  For example:
+      of an <acronym>FSM</acronym> page.  For example:
 <screen>
 test=# SELECT fsm_page_contents(get_raw_page('pg_class', 'fsm', 0));
 </screen>
@@ -147,7 +149,7 @@ test=# SELECT fsm_page_contents(get_raw_page('pg_class', 'fsm', 0));
      </para>
      <para>
       See <filename>src/backend/storage/freespace/README</filename> for more
-      information on the structure of an FSM page.
+      information on the structure of an <acronym>FSM</acronym> page.
      </para>
     </listitem>
    </varlistentry>
diff --git a/doc/src/sgml/pgfreespacemap.sgml b/doc/src/sgml/pgfreespacemap.sgml
index 5025498249..1f7867d9b9 100644
--- a/doc/src/sgml/pgfreespacemap.sgml
+++ b/doc/src/sgml/pgfreespacemap.sgml
@@ -9,10 +9,10 @@
 
  <para>
   The <filename>pg_freespacemap</filename> module provides a means for examining the
-  free space map (FSM). It provides a function called
-  <function>pg_freespace</function>, or two overloaded functions, to be
-  precise. The functions show the value recorded in the free space map for
-  a given page, or for all pages in the relation.
+  <link linkend="storage-fsm">free space map</link> (<acronym>FSM</acronym>).
+  It provides a function called <function>pg_freespace</function>, or two
+  overloaded functions, to be precise. The functions show the value recorded in
+  the free space map for a given page, or for all pages in the relation.
  </para>
 
  <para>
@@ -36,7 +36,7 @@
     <listitem>
      <para>
       Returns the amount of free space on the page of the relation, specified
-      by <literal>blkno</literal>, according to the FSM.
+      by <literal>blkno</literal>, according to the <acronym>FSM</acronym>.
      </para>
     </listitem>
    </varlistentry>
@@ -50,7 +50,8 @@
     <listitem>
      <para>
       Displays the amount of free space on each page of the relation,
-      according to the FSM. A set of <literal>(blkno bigint, avail int2)</literal>
+      according to the <acronym>FSM</acronym>. A set of
+      <literal>(blkno bigint, avail int2)</literal>
       tuples is returned, one tuple for each page in the relation.
      </para>
     </listitem>
@@ -112,8 +113,8 @@ postgres=# SELECT * FROM pg_freespace('foo', 7);
 
   <para>
    Original version by Mark Kirkwood <email>[email-masked]</email>.
-   Rewritten in version 8.4 to suit new FSM implementation by Heikki
-   Linnakangas <email>[email-masked]</email>
+   Rewritten in version 8.4 to suit new <acronym>FSM</acronym> implementation
+   by Heikki Linnakangas <email>[email-masked]</email>
   </para>
  </sect2>
 
diff --git a/doc/src/sgml/storage.sgml b/doc/src/sgml/storage.sgml
index 7136bbe7a3..f4b9f66589 100644
--- a/doc/src/sgml/storage.sgml
+++ b/doc/src/sgml/storage.sgml
@@ -603,10 +603,11 @@ tuple would otherwise be too big.
 
 <para>
 Each heap and index relation, except for hash indexes, has a Free Space Map
-(FSM) to keep track of available space in the relation. It's stored
-alongside the main relation data in a separate relation fork, named after the
-filenode number of the relation, plus a <literal>_fsm</literal> suffix. For example,
-if the filenode of a relation is 12345, the FSM is stored in a file called
+(<acronym>FSM</acronym>) to keep track of available space in the relation.
+It's stored alongside the main relation data in a separate relation fork,
+named after the filenode number of the relation, plus a <literal>_fsm</literal>
+suffix. For example, if the filenode of a relation is 12345, the
+<acronym>FSM</acronym> is stored in a file called
 <filename>12345_fsm</filename>, in the same directory as the main relation file.
 </para>

---

From: Dong Wook Lee <[email-masked]>
Date: Tue, 8 Mar 2022 18:34:34 +0900

Patch looks good to me.

---

From: Michael Paquier <[email-masked]>
Date: Wed, 9 Mar 2022 10:45:18 +0900

> Patch looks good to me.

Okay, applied then.
--
Michael