Add some real documentation about TOAST (finally). Combine this with

the old 'page' chapter and the recently added 'filelayout' chapter to
make a coherent chapter about PostgreSQL's physical storage layout.

Author: tglsfdc

doc/src/sgml/diskusage.sgml

@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/diskusage.sgml,v 1.13 2004/12/28 19:08:58 tgl Exp $
+$PostgreSQL: pgsql/doc/src/sgml/diskusage.sgml,v 1.14 2005/01/10 00:04:38 tgl Exp $
 -->
 
 <chapter id="diskusage">
@@ -22,12 +22,12 @@ $PostgreSQL: pgsql/doc/src/sgml/diskusage.sgml,v 1.13 2004/12/28 19:08:58 tgl Ex
    stored. If the table has any columns with potentially-wide values,
    there is also a <acronym>TOAST</> file associated with the table,
    which is used to store values too wide to fit comfortably in the main
-   table.  There will be one index on the
+   table (see <xref linkend="storage-toast">).  There will be one index on the
    <acronym>TOAST</> table, if present. There may also be indexes associated
    with the base table.  Each table and index is stored in a separate disk
    file &mdash; possibly more than one file, if the file would exceed one
    gigabyte.  Naming conventions for these files are described in <xref
-   linkend="file-layout">.
+   linkend="storage-file-layout">.
   </para>
 
   <para>

doc/src/sgml/filelayout.sgml

@@ -1,4 +1,4 @@
-<!-- $PostgreSQL: pgsql/doc/src/sgml/filelist.sgml,v 1.40 2004/12/03 05:50:18 momjian Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/filelist.sgml,v 1.41 2005/01/10 00:04:38 tgl Exp $ -->
 
 <!entity history    SYSTEM "history.sgml">
 <!entity info       SYSTEM "info.sgml">
@@ -75,15 +75,14 @@
 <!entity arch-dev   SYSTEM "arch-dev.sgml">
 <!entity bki        SYSTEM "bki.sgml">
 <!entity catalogs   SYSTEM "catalogs.sgml">
-<!entity filelayout SYSTEM "filelayout.sgml">
 <!entity geqo       SYSTEM "geqo.sgml">
 <!entity gist       SYSTEM "gist.sgml">
 <!entity indexcost  SYSTEM "indexcost.sgml">
 <!entity nls        SYSTEM "nls.sgml">
-<!entity page       SYSTEM "page.sgml">
 <!entity plhandler  SYSTEM "plhandler.sgml">
 <!entity protocol   SYSTEM "protocol.sgml">
 <!entity sources    SYSTEM "sources.sgml">
+<!entity storage    SYSTEM "storage.sgml">
 
 <!-- appendixes -->
 <!entity contacts   SYSTEM "contacts.sgml">

doc/src/sgml/filelist.sgml

@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/lobj.sgml,v 1.35 2005/01/08 22:13:33 tgl Exp $
+$PostgreSQL: pgsql/doc/src/sgml/lobj.sgml,v 1.36 2005/01/10 00:04:38 tgl Exp $
 -->
 
  <chapter id="largeObjects">
@@ -51,9 +51,11 @@ $PostgreSQL: pgsql/doc/src/sgml/lobj.sgml,v 1.35 2005/01/08 22:13:33 tgl Exp $
    </para>
 
    <para>
-    <indexterm><primary>TOAST</></>
-    <indexterm><primary>sliced bread</><see>TOAST</></indexterm>
-    <productname>PostgreSQL 7.1</productname> introduced a mechanism
+    <indexterm>
+     <primary>TOAST</primary>
+     <secondary>versus large objects</secondary>
+    </indexterm>
+    <productname>PostgreSQL</productname> 7.1 introduced a mechanism
     (nicknamed <quote><acronym>TOAST</acronym></quote>) that allows
     data values to be much larger than single pages.  This
     makes the large object facility partially obsolete.  One