Date: Tue, 8 Mar 2022 15:17:00 +0900
From: Michael Paquier <michael@paquier.xyz>
To: Dong Wook Lee <sh95119@gmail.com>
Cc: pgsql-docs@lists.postgresql.org
Subject: Re: add free space map link in pg_freespacemap page
Message-ID: <Yib03PN9cJyNSul8@paquier.xyz>
References: 
 <CAAcBya+=F=HaHxJ7tGjAM1r=A=+bDbimpsex8Vqrb4GjqFDYsQ@mail.gmail.com>
 <14aeba35c06421ae40c96f3fc31ce998d50dad41.camel@cybertec.at>
 <YiX0i/5mKRAJgOdU@paquier.xyz>
 <CAAcByaKeBsP=k-zp_JHcS8mc2+-0TC72kb7XXWqqQoCh9VEdoA@mail.gmail.com>
MIME-Version: 1.0
Content-Type: multipart/signed; micalg=pgp-sha512;
	protocol="application/pgp-signature"; boundary="tWiDxdC4NL5LAZie"
Content-Disposition: inline
In-Reply-To: 
 <CAAcByaKeBsP=k-zp_JHcS8mc2+-0TC72kb7XXWqqQoCh9VEdoA@mail.gmail.com>
Archived-At: 
 <https://www.postgresql.org/message-id/Yib03PN9cJyNSul8%40paquier.xyz>
Precedence: bulk


--tWiDxdC4NL5LAZie
Content-Type: multipart/mixed; boundary="do24wp4/f4dos+Dd"
Content-Disposition: inline


--do24wp4/f4dos+Dd
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline

On Tue, Mar 08, 2022 at 09:31:49AM +0900, Dong Wook Lee wrote:
> I don't know about it, so should I use <acronym> at FSM for all the
> 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

--do24wp4/f4dos+Dd
Content-Type: text/x-diff; charset=us-ascii
Content-Disposition: attachment; filename="fsm-vm-docs.patch"
Content-Transfer-Encoding: quoted-printable

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 all=
ows 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=3D"storage-fsm">free space map</link>,
+      <literal>'vm'</literal> for the
+      <link linkend=3D"storage-vm">visibility map</link>, or
+      <literal>'init'</literal> for the initialization fork.
      </para>
     </listitem>
    </varlistentry>
@@ -136,7 +138,7 @@ test=3D# SELECT page_checksum(get_raw_page('pg_class', =
0), 0);
     <listitem>
      <para>
       <function>fsm_page_contents</function> shows the internal node struc=
ture
-      of an FSM page.  For example:
+      of an <acronym>FSM</acronym> page.  For example:
 <screen>
 test=3D# SELECT fsm_page_contents(get_raw_page('pg_class', 'fsm', 0));
 </screen>
@@ -147,7 +149,7 @@ test=3D# SELECT fsm_page_contents(get_raw_page('pg_clas=
s', 'fsm', 0));
      </para>
      <para>
       See <filename>src/backend/storage/freespace/README</filename> for mo=
re
-      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=
=2Esgml
index 5025498249..1f7867d9b9 100644
--- a/doc/src/sgml/pgfreespacemap.sgml
+++ b/doc/src/sgml/pgfreespacemap.sgml
@@ -9,10 +9,10 @@
=20
  <para>
   The <filename>pg_freespacemap</filename> module provides a means for exa=
mining 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=3D"storage-fsm">free space map</link> (<acronym>FSM</acron=
ym>).
+  It provides a function called <function>pg_freespace</function>, or two
+  overloaded functions, to be precise. The functions show the value record=
ed in
+  the free space map for a given page, or for all pages in the relation.
  </para>
=20
  <para>
@@ -36,7 +36,7 @@
     <listitem>
      <para>
       Returns the amount of free space on the page of the relation, specif=
ied
-      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=3D# SELECT * FROM pg_freespace('foo', 7);
=20
   <para>
    Original version by Mark Kirkwood <email>markir@paradise.net.nz</email>.
-   Rewritten in version 8.4 to suit new FSM implementation by Heikki
-   Linnakangas <email>heikki@enterprisedb.com</email>
+   Rewritten in version 8.4 to suit new <acronym>FSM</acronym> implementat=
ion
+   by Heikki Linnakangas <email>heikki@enterprisedb.com</email>
   </para>
  </sect2>
=20
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.
=20
 <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. Fo=
r 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</lit=
eral>
+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>
=20

--do24wp4/f4dos+Dd--

--tWiDxdC4NL5LAZie
Content-Type: application/pgp-signature; name="signature.asc"

-----BEGIN PGP SIGNATURE-----

iQIzBAABCgAdFiEEG72nH6vTowiyblFKnvQgOdbyQH0FAmIm9NwACgkQnvQgOdby
QH0fpg/+IWxF/FDvPdoBoGHquPkLEGsLQRiA63cz2QZ+UdNLssrTUNLoM+nc9xIM
mx/85hvCPlJYxoCZWpI02F5lTOgVkMS8WJzxMnZ+tfeMMnRe/QQPk/gl31JWa3PT
iAV1BsusEAXUdFwhPTX/BTexyTC3zASodGBR9i9cOQbAHD8o3Y3kAy9uIiaSCQ9r
TAyc+vWbgsOT7bRG0ep/QJb4IQzZ9MfngbLGG3CHMCuE0vc/pJhJJ1Ysfkkbp0a+
tUv98WvMEYtLguGJkFpCajDWbzesUSTzLZKvqJy33ah2dr+R2H8ULC0l/WH4cbQO
5fcP4I7p/6UMrXxbE6xUq2iwHRiAJ/S+Rn5FxBSgwjR4ZQU9QaKfTXblgaItRvFw
2NoDYcKvNqerzpvuvtlA5Mbi+J8RoIKmGicAS6IbQM50aZMZA5nf1m902lN3saCE
9HKSjcLai29BeokJ9RMSiqMzRsVTefen4SeODquywN7FK7JAB8aD3Wr2zzxhi/V2
q+lpADy1F2FTrDoRuJnayVqxY8pK5H++lFxV6rWOxsbuqQvE2arvmh+DF86qHT/5
YWpNvXzXF07ve2SEaS3D7mCAKmNrpyv6Kfg+EeG70JzzOqQpGXylsLhACcKtUmSw
KpTreYOnnghe6uQ88DH/b+G0mKtVsDRiTTw5CLj92lZUilX9eb8=
=79f6
-----END PGP SIGNATURE-----

--tWiDxdC4NL5LAZie--