Add information on generating INSTALL and HISTORY from sgml sources.

1 files changed, 160 insertions, 48 deletions

diff --git a/doc/src/sgml/docguide.sgml b/doc/src/sgml/docguide.sgml
index af4e7b04641..ccdf85e6830 100644
--- a/doc/src/sgml/docguide.sgml
+++ b/doc/src/sgml/docguide.sgml
@@ -1,24 +1,12 @@
 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/docguide.sgml,v 1.16 1999/06/14 07:36:11 thomas Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/docguide.sgml,v 1.17 1999/06/23 06:19:36 thomas Exp $
 Documentation Guide
 Thomas Lockhart
 
-$Log: docguide.sgml,v $
-Revision 1.16  1999/06/14 07:36:11  thomas
-Minor updates for release.
-
 Revision 1.15  1999/05/27 15:49:07  thomas
 Markup fixes.
 Update for v6.5 release.
 
-Revision 1.14  1999/01/07 03:01:27  thomas
-Fix column formatting for a table. No content changes.
-
-Revision 1.13  1998/12/29 02:24:14  thomas
-Clean up to ensure tag completion as required by the newest versions
- of Norm's Modular Style Sheets and jade/docbook.
-From Vince Vielhaber <vev@michvhf.com>.
-
 Revision 1.12  1998/12/18 16:17:29  thomas
 Include more details on editing with Emacs.
 Remove mention of the old "migration" flat files.
@@ -31,22 +19,11 @@ Minor editing and markup changes as a result of preparing the Postscript
  documentation for v6.4.
 Bigger updates to the installation instructions (install and config).
 
-Revision 1.10  1998/10/25 00:25:30  thomas
-Update info on source files for v6.4.
-Should add/change ToDo list some more before release...
-
-Revision 1.9  1998/10/15 05:46:54  momjian
-SGML updates from post 6.3.2 manual changes.  Added pg_upgrade man page.
-
 Revision 1.8  1998/08/17 16:17:07  thomas
 Bring document list closer to up to day.
 Add a note on sgml-tools that they are now working with jade and so
  may become the toolset of choice in the future.
 
-Revision 1.7  1998/08/15 06:53:52  thomas
-Include working list of all documentation sources, with current status
- and plans for some of them.
-
 -->
 
 <appendix label="DG2" id="docguide">
@@ -115,27 +92,67 @@ Include working list of all documentation sources, with current status
      </thead>
 
      <tbody>
-      <row><entry>./COPYRIGHT</entry><entry>Copyright notice</entry></row>
-      <row><entry>./INSTALL</entry><entry>Installation instructions (text from sgml->rtf->text)</entry></row>
-      <row><entry>./README</entry><entry>Introductory info</entry></row>
-      <row><entry>./register.txt</entry><entry>Registration message during make</entry></row>
-      <row><entry>./doc/bug.template</entry><entry>Bug report template</entry></row>
-      <row><entry>./doc/postgres.tar.gz</entry><entry>Integrated docs (<acronym>HTML</acronym>)</entry></row>
-      <row><entry>./doc/programmer.ps.gz</entry><entry>Programmer's Guide (Postscript)</entry></row>
-      <row><entry>./doc/programmer.tar.gz</entry><entry>Programmer's Guide (<acronym>HTML</acronym>)</entry></row>
-      <row><entry>./doc/reference.ps.gz</entry><entry>Reference Manual (Postscript)</entry></row>
-      <row><entry>./doc/reference.tar.gz</entry><entry>Reference Manual (<acronym>HTML</acronym>)</entry></row>
-      <row><entry>./doc/tutorial.ps.gz</entry><entry>Introduction (Postscript)</entry></row>
-      <row><entry>./doc/tutorial.tar.gz</entry><entry>Introduction (<acronym>HTML</acronym>)</entry></row>
-      <row><entry>./doc/user.ps.gz</entry><entry>User's Guide (Postscript)</entry></row>
-      <row><entry>./doc/user.tar.gz</entry><entry>User's Guide (<acronym>HTML</acronym>)</entry></row>
+      <row>
+       <entry>./COPYRIGHT</entry><entry>Copyright notice</entry>
+      </row>
+      <row>
+       <entry>./INSTALL</entry>
+       <entry>Installation instructions (text from sgml->rtf->text)</entry>
+      </row>
+      <row>
+       <entry>./README</entry>
+       <entry>Introductory info</entry>
+      </row>
+      <row>
+       <entry>./register.txt</entry>
+       <entry>Registration message during make</entry>
+      </row>
+      <row>
+       <entry>./doc/bug.template</entry>
+       <entry>Bug report template</entry>
+      </row>
+      <row>
+       <entry>./doc/postgres.tar.gz</entry>
+       <entry>Integrated docs (<acronym>HTML</acronym>)</entry>
+      </row>
+      <row>
+       <entry>./doc/programmer.ps.gz</entry>
+       <entry>Programmer's Guide (Postscript)</entry>
+      </row>
+      <row>
+       <entry>./doc/programmer.tar.gz</entry>
+       <entry>Programmer's Guide (<acronym>HTML</acronym>)</entry>
+      </row>
+      <row>
+       <entry>./doc/reference.ps.gz</entry>
+       <entry>Reference Manual (Postscript)</entry>
+      </row>
+      <row>
+       <entry>./doc/reference.tar.gz</entry>
+       <entry>Reference Manual (<acronym>HTML</acronym>)</entry>
+      </row>
+      <row>
+       <entry>./doc/tutorial.ps.gz</entry>
+       <entry>Introduction (Postscript)</entry>
+      </row>
+      <row>
+       <entry>./doc/tutorial.tar.gz</entry>
+       <entry>Introduction (<acronym>HTML</acronym>)</entry>
+      </row>
+      <row>
+       <entry>./doc/user.ps.gz</entry>
+       <entry>User's Guide (Postscript)</entry></row>
+      <row>
+       <entry>./doc/user.tar.gz</entry>
+       <entry>User's Guide (<acronym>HTML</acronym>)</entry>
+      </row>
      </tbody>
     </tgroup>
    </table>
   </para>
 
   <para>
-   There are man pages available for installation, as well as a large number
+   There are man pages available, as well as a large number
    of plain-text README-type files throughout the <productname>Postgres</productname>
    source tree.
   </para>
@@ -166,9 +183,11 @@ Include working list of all documentation sources, with current status
 
   <para>
    See
-   <ulink url="http://nis-www.lanl.gov/~rosalia/mydocs/docbook-intro.html">Introduction to DocBook</ulink>
+   <ulink url="http://nis-www.lanl.gov/~rosalia/mydocs/docbook-intro.html">
+    Introduction to DocBook</ulink>
    for a nice "quickstart" summary of DocBook features.
-   <ulink url="http://www.ora.com/homepages/dtdparse/docbook/3.0/"> DocBook Elements</ulink>
+   <ulink url="http://www.ora.com/homepages/dtdparse/docbook/3.0/">
+    DocBook Elements</ulink>
    provides a powerful cross-reference for features of
    <productname>DocBook</productname>.
   </para>
@@ -176,9 +195,11 @@ Include working list of all documentation sources, with current status
   <para>
    This documentation set is constructed using several tools, including
    James Clark's 
-   <ulink url="http://www.jclark.com/jade/"> <productname>jade</productname></ulink>
+   <ulink url="http://www.jclark.com/jade/">
+    <productname>jade</productname></ulink>
    and Norm Walsh's 
-   <ulink url="http://www.nwalsh.com/docbook/dsssl/">Modular DocBook Stylesheets</ulink>.
+   <ulink url="http://www.nwalsh.com/docbook/dsssl/">
+    Modular DocBook Stylesheets</ulink>.
   </para>
 
   <para>
@@ -191,7 +212,7 @@ Include working list of all documentation sources, with current status
   <para>
    <ulink url="http://sunsite.unc.edu/pub/packages/TeX/systems/unix/">
     <productname>TeX</productname></ulink> is a supported format for
-   <application>jade</application> output, but was not used at this time
+   <application>jade</application> output, but is not used at this time
    for several reasons, including the inability to make minor format
    fixes before committing to hardcopy and generally inadequate table
    support in the <productname>TeX</productname>
@@ -999,7 +1020,97 @@ by typing
 -->
 
   <sect2>
-   <title><acronym>RTF</acronym> Cleanup Procedure</title>
+   <title>Text Hardcopy</title>
+
+   <para>
+    <filename>INSTALL</filename> and <filename>HISTORY</filename> are
+    updated for each release. For historical reasons, these files are
+    in plain text, but are derived from the newer
+    <acronym>SGML</acronym> sources.
+   </para>
+
+   <procedure>
+    <title>Plain Text Generation</title>
+
+    <para>
+     Both <filename>INSTALL</filename> and
+     <filename>HISTORY</filename> are generated from existing
+     <acronym>SGML</acronym> sources. They are extracted from the same 
+     intermediate <acronym>RTF</acronym> file.
+    </para>
+
+    <step performance="required">
+     <para>
+      Generate <acronym>RTF</acronym> by typing:
+      <programlisting>
+% cd doc/src/sgml
+% make installation.rtf
+      </programlisting>
+     </para>
+    </step>
+      
+    <step performance="required">
+     <para>
+      Import <filename>installation.rtf</filename> into
+      <productname>Applix Words</productname>.
+     </para>
+    </step>
+
+    <step performance="required">
+     <para>
+      Set the page width and margins.
+     </para>
+
+     <substeps>
+      <step performance="required">
+       <para>
+	Adjust the page width in File.PageSetup to 10 inches.
+       </para>
+      </step>
+
+      <step performance="required">
+       <para>
+	Select all text.
+	Adjust the right margin using the ruler to 9.5 inches. This
+	will give a maximum column width of 79 characters, within the
+	80 columns upper limit goal.
+       </para>
+      </step>
+     </substeps>
+    </step>
+
+    <step performance="required">
+     <para>
+      Lop off the parts of the document which are not needed.
+     </para>
+
+     <para>
+      For <filename>INSTALL</filename>, remove all release notes from
+      the end of the text, except for those from the current release.
+      For <filename>HISTORY</filename>, remove all text up to the
+      release notes, preserving and modifying the title and ToC.
+     </para>
+    </step>
+
+    <step performance="required">
+     <para>
+      Export the result as <quote>ASCII Layout</quote>.
+     </para>
+    </step>
+
+    <step performance="required">
+     <para>
+      Using emacs or vi, clean up the tabular information in
+      <filename>INSTALL</filename>. Remove the <quote>mailto</quote>
+      <acronym>URLs</acronym> for the porting contributors to shrink
+      the column heights.
+     </para>
+    </step>
+   </procedure>
+  </sect2>
+
+  <sect2>
+   <title>Postscript Hardcopy</title>
 
    <para>
     Several items must be addressed in generating Postscript
@@ -1018,7 +1129,7 @@ by typing
 
     <step performance="required">
      <para>
-      Generate the <acronym>RTF</acronym> input by typing
+      Generate the <acronym>RTF</acronym> input by typing (for example):
       <programlisting>
 % cd doc/src/sgml
 % make tutorial.rtf
@@ -1048,7 +1159,7 @@ by typing
      <para>
       Not all documents have figures.
       You can grep the <acronym>SGML</acronym> source files for
-      the string <quote>Graphic</quote> to identify those parts of the
+      the string <quote>graphic</quote> to identify those parts of the
       documentation which may have figures. A few figures are replicated in
       various parts of the documentation.
      </para>
@@ -1093,7 +1204,8 @@ by typing
 
     <step performance="required">
      <para>
-      Export the document to a file in Postscript format.
+      <quote>Print</quote> the document
+      to a file in Postscript format.
      </para>
     </step>