Minor editorialization on storage.sgml's documentation of free space

maps.

doc/src/sgml/storage.sgml

-<!-- $PostgreSQL: pgsql/doc/src/sgml/storage.sgml,v 1.27 2009/04/23 10:20:27 heikki Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/storage.sgml,v 1.28 2009/05/16 22:03:53 tgl Exp $ -->
 
 <chapter id="storage">
 
@@ -131,12 +131,12 @@ there.
 Each table and index is stored in a separate file, named after the table
 or index's <firstterm>filenode</> number, which can be found in
 <structname>pg_class</>.<structfield>relfilenode</>. In addition to the
-main file (aka. main fork), a <firstterm>free space map</> (see
-<xref linkend="storage-fsm">) that stores information about free space
-available in the relation, is stored in a file named after the filenode
-number, with the <literal>_fsm</> suffix.  Tables also have a visibility map
-fork, with the <literal>_vm</> suffix, to track which pages are known to have
-no dead tuples and therefore need no vacuuming.
+main file (a/k/a main fork), each table and index has a <firstterm>free space
+map</> (see <xref linkend="storage-fsm">), which stores information about free
+space available in the relation.  The free space map is stored in a file named
+with the filenode number plus the suffix <literal>_fsm</>.  Tables also have a
+visibility map fork, with the suffix <literal>_vm</>, to track which pages are
+known to have no dead tuples and therefore need no vacuuming.
 </para>
 
 <caution>
@@ -157,6 +157,8 @@ This arrangement avoids problems on platforms that have file size limitations.
 (Actually, 1 GB is just the default segment size.  The segment size can be
 adjusted using the configuration option <option>--with-segsize</option>
 when building <productname>PostgreSQL</>.)
+In principle, free space map and visibility map forks could require multiple
+segments as well, though this is unlikely to happen in practice.
 The contents of tables and indexes are discussed further in
 <xref linkend="storage-page-layout">.
 </para>
@@ -193,7 +195,7 @@ if a tablespace other than <literal>pg_default</> is specified for them.
 The name of a temporary file has the form
 <filename>pgsql_tmp<replaceable>PPP</>.<replaceable>NNN</></filename>,
 where <replaceable>PPP</> is the PID of the owning backend and
-<replaceable>NNN</> distinguishes different files of that backend.
+<replaceable>NNN</> distinguishes different temporary files of that backend.
 </para>
 
 </sect1>
@@ -377,24 +379,24 @@ comparison table, in which all the HTML pages were cut down to 7 kB to fit.
 
 <title>Free Space Map</title>
 
-    <indexterm>
+<indexterm>
  <primary>Free Space Map</primary>
-    </indexterm>
-    <indexterm><primary>FSM</><see>Free Space Map</></indexterm>
+</indexterm>
+<indexterm><primary>FSM</><see>Free Space Map</></indexterm>
 
 <para>
-A Free Space Map is stored with every heap and index relation, except for
-hash indexes, to keep track of available space in the relation. It's stored
-along the main relation data, in a separate FSM relation fork, named after
-relfilenode of the relation, but with a <literal>_fsm</> suffix. For example,
-if the relfilenode of a relation is 12345, the FSM is stored in a file called
+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</> suffix. For example,
+if the filenode of a relation is 12345, the FSM is stored in a file called
 <filename>12345_fsm</>, in the same directory as the main relation file.
 </para>
 
 <para>
 The Free Space Map is organized as a tree of <acronym>FSM</> pages. The
-bottom level <acronym>FSM</> pages stores the free space available on every
-heap (or index) page, using one byte to represent each heap page. The upper
+bottom level <acronym>FSM</> pages store the free space available on each
+heap (or index) page, using one byte to represent each such page. The upper
 levels aggregate information from the lower levels.
 </para>
 
@@ -409,8 +411,8 @@ at the root.
 <para>
 See <filename>src/backend/storage/freespace/README</> for more details on
 how the <acronym>FSM</> is structured, and how it's updated and searched.
-<xref linkend="pgfreespacemap"> contrib module can be used to view the
-information stored in free space maps.
+The <filename>contrib/pg_freespacemap</> module can be used to examine the
+information stored in free space maps (see <xref linkend="pgfreespacemap">).
 </para>
 
 </sect1>