v8-0002-Add-data-layout-options-sub-section-in-installati.patch

From b539821835267e2c43f15eb7d0afa30918b00ce9 Mon Sep 17 00:00:00 2001
From: Samay Sharma <smilingsamay@gmail.com>
Date: Mon, 6 Feb 2023 16:09:42 -0800
Subject: [PATCH v8 2/5] Add data layout options sub-section in installation
 docs

This commit separates out blocksize, segsize and wal_blocksize
options into a separate Data layout options sub-section in both
the make and meson docs. They were earlier in a miscellaneous
section which included several unrelated options. This change
also helps reduce the repetition of the warnings that changing
these parameters breaks on-disk compatibility.
---
 doc/src/sgml/installation.sgml | 156 +++++++++++++++++++--------------
 1 file changed, 89 insertions(+), 67 deletions(-)

diff --git a/doc/src/sgml/installation.sgml b/doc/src/sgml/installation.sgml
index 97ee0a04a3..657330d368 100644
--- a/doc/src/sgml/installation.sgml
+++ b/doc/src/sgml/installation.sgml
@@ -1470,6 +1470,35 @@ build-postgresql:
        </listitem>
       </varlistentry>
 
+     </variablelist>
+
+   </sect3>
+
+   <sect3 id="configure-options-data-layout">
+    <title>Data layout Options</title>
+
+     <para>
+      These options affect how PostgreSQL lays out data on disk.
+      Note that changing these breaks on-disk database compatibility,
+      meaning you cannot use <command>pg_upgrade</command> to upgrade to
+      a build with different values of these options.
+     </para>
+
+     <variablelist>
+
+      <varlistentry id="configure-option-with-blocksize">
+       <term><option>--with-blocksize=<replaceable>BLOCKSIZE</replaceable></option></term>
+       <listitem>
+        <para>
+         Set the <firstterm>block size</firstterm>, in kilobytes.  This is the unit
+         of storage and I/O within tables.  The default, 8 kilobytes,
+         is suitable for most situations; but other values may be useful
+         in special cases.
+         The value must be a power of 2 between 1 and 32 (kilobytes).
+        </para>
+       </listitem>
+      </varlistentry>
+
       <varlistentry id="configure-option-with-segsize">
        <term><option>--with-segsize=<replaceable>SEGSIZE</replaceable></option></term>
        <listitem>
@@ -1488,25 +1517,6 @@ build-postgresql:
          also set limits on the usable file size.
          It is recommended, though not absolutely required, that this value
          be a power of 2.
-         Note that changing this value breaks on-disk database compatibility,
-         meaning you cannot use <command>pg_upgrade</command> to upgrade to
-         a build with a different segment size.
-        </para>
-       </listitem>
-      </varlistentry>
-
-      <varlistentry id="configure-option-with-blocksize">
-       <term><option>--with-blocksize=<replaceable>BLOCKSIZE</replaceable></option></term>
-       <listitem>
-        <para>
-         Set the <firstterm>block size</firstterm>, in kilobytes.  This is the unit
-         of storage and I/O within tables.  The default, 8 kilobytes,
-         is suitable for most situations; but other values may be useful
-         in special cases.
-         The value must be a power of 2 between 1 and 32 (kilobytes).
-         Note that changing this value breaks on-disk database compatibility,
-         meaning you cannot use <command>pg_upgrade</command> to upgrade to
-         a build with a different block size.
         </para>
        </listitem>
       </varlistentry>
@@ -1520,9 +1530,6 @@ build-postgresql:
          is suitable for most situations; but other values may be useful
          in special cases.
          The value must be a power of 2 between 1 and 64 (kilobytes).
-         Note that changing this value breaks on-disk database compatibility,
-         meaning you cannot use <command>pg_upgrade</command> to upgrade to
-         a build with a different WAL block size.
         </para>
        </listitem>
       </varlistentry>
@@ -2917,53 +2924,68 @@ ninja install
       </listitem>
      </varlistentry>
 
-     <varlistentry id="configure-segsize-meson">
-      <term><option>-Dsegsize=<replaceable>SEGSIZE</replaceable></option></term>
-      <listitem>
-       <para>
-        Set the <firstterm>segment size</firstterm>, in gigabytes.  Large tables are
-        divided into multiple operating-system files, each of size equal
-        to the segment size.  This avoids problems with file size limits
-        that exist on many platforms.  The default segment size, 1 gigabyte,
-        is safe on all supported platforms.  If your operating system has
-        <quote>largefile</quote> support (which most do, nowadays), you can use
-        a larger segment size.  This can be helpful to reduce the number of
-        file descriptors consumed when working with very large tables.
-        But be careful not to select a value larger than is supported
-        by your platform and the file systems you intend to use.  Other
-        tools you might wish to use, such as <application>tar</application>, could
-        also set limits on the usable file size.
-        It is recommended, though not absolutely required, that this value
-        be a power of 2.
-       </para>
-      </listitem>
-     </varlistentry>
+    </variablelist>
+   </sect3>
 
-     <varlistentry id="configure-blocksize-meson">
-      <term><option>-Dblocksize=<replaceable>BLOCKSIZE</replaceable></option></term>
-      <listitem>
-       <para>
-        Set the <firstterm>block size</firstterm>, in kilobytes.  This is the unit
-        of storage and I/O within tables.  The default, 8 kilobytes,
-        is suitable for most situations; but other values may be useful
-        in special cases.
-        The value must be a power of 2 between 1 and 32 (kilobytes).
-       </para>
-      </listitem>
-     </varlistentry>
+   <sect3 id="meson-options-data-layout">
+    <title>Data layout Options</title>
+
+     <para>
+      These options affect how PostgreSQL lays out data on disk.
+      Note that changing these breaks on-disk database compatibility,
+      meaning you cannot use <command>pg_upgrade</command> to upgrade to
+      a build with different values of these options.
+     </para>
+
+     <variablelist>
+      <varlistentry>
+       <term><option>-Dblocksize=<replaceable>BLOCKSIZE</replaceable></option></term>
+       <listitem>
+        <para>
+         Set the <firstterm>block size</firstterm>, in kilobytes.  This is the unit
+         of storage and I/O within tables.  The default, 8 kilobytes,
+         is suitable for most situations; but other values may be useful
+         in special cases.
+         The value must be a power of 2 between 1 and 32 (kilobytes).
+        </para>
+       </listitem>
+      </varlistentry>
+
+      <varlistentry>
+       <term><option>-Dsegsize=<replaceable>SEGSIZE</replaceable></option></term>
+       <listitem>
+        <para>
+         Set the <firstterm>segment size</firstterm>, in gigabytes.  Large tables are
+         divided into multiple operating-system files, each of size equal
+         to the segment size.  This avoids problems with file size limits
+         that exist on many platforms.  The default segment size, 1 gigabyte,
+         is safe on all supported platforms.  If your operating system has
+         <quote>largefile</quote> support (which most do, nowadays), you can use
+         a larger segment size.  This can be helpful to reduce the number of
+         file descriptors consumed when working with very large tables.
+         But be careful not to select a value larger than is supported
+         by your platform and the file systems you intend to use.  Other
+         tools you might wish to use, such as <application>tar</application>, could
+         also set limits on the usable file size.
+         It is recommended, though not absolutely required, that this value
+         be a power of 2.
+        </para>
+       </listitem>
+      </varlistentry>
+
+      <varlistentry>
+       <term><option>-Dwal_blocksize=<replaceable>BLOCKSIZE</replaceable></option></term>
+       <listitem>
+        <para>
+         Set the <firstterm>WAL block size</firstterm>, in kilobytes.  This is the unit
+         of storage and I/O within the WAL log.  The default, 8 kilobytes,
+         is suitable for most situations; but other values may be useful
+         in special cases.
+         The value must be a power of 2 between 1 and 64 (kilobytes).
+        </para>
+       </listitem>
+      </varlistentry>
 
-     <varlistentry id="configure-wal-blocksize-meson">
-      <term><option>-Dwal_blocksize=<replaceable>BLOCKSIZE</replaceable></option></term>
-      <listitem>
-       <para>
-        Set the <firstterm>WAL block size</firstterm>, in kilobytes.  This is the unit
-        of storage and I/O within the WAL log.  The default, 8 kilobytes,
-        is suitable for most situations; but other values may be useful
-        in special cases.
-        The value must be a power of 2 between 1 and 64 (kilobytes).
-       </para>
-      </listitem>
-     </varlistentry>
     </variablelist>
    </sect3>
 
-- 
2.38.1