Update SGML docs with some changes I made to test/regress/README

many moons ago, but forgot to put here.

Author: tglsfdc

doc/src/sgml/regress.sgml

@@ -82,15 +82,15 @@ The runtime path is /usr/local/pgsql (other paths are possible).
 </Para>
 
 <Para>
-  The postmaster should be invoked with the system time zone set for
-  Berkeley, California. This is done automatically by the regression
-test script. However, it does require machine support for the PST8PDT
-time zone.
-</Para>
-
-<Para>
-To verify that your machine does have this support, type
-the following:
+  It was formerly necessary to run the postmaster with system time zone
+  set to PST, but this is no longer required.  You can run the regression
+  tests under your normal postmaster configuration.  The test script will
+  set the PGTZ environment variable to ensure that timezone-dependent tests
+  produce the expected results.  However, your system must provide
+  library support for the PST8PDT time zone, or the timezone-dependent
+  tests will fail.
+  To verify that your machine does have this support, type
+  the following:
 <ProgramListing>
     setenv TZ PST8PDT
     date
@@ -147,36 +147,15 @@ the following:
       like <FileName>ps</FileName> and <FileName>tar</FileName> vary wildly on what options you should use on each
       platform. <Emphasis>Use common sense</Emphasis> before typing in these commands.
     </Para>
-    
-    <Procedure>
-      <Title><ProductName>Postgres</ProductName> Regression Configuration</Title>
 
       <Para>
 	For a fresh install or upgrading from previous releases of
 	<ProductName>Postgres</ProductName>:
       </Para>
-      
-      <Step Performance="required">
-	<Para>
-	  Build the regression test. Type
-	  <ProgramListing>
-	    cd /usr/src/pgsql/src/test/regress
-	    gmake all
-	  </ProgramListing>
-	</Para>
-      </Step>
-      
-      <Step Performance="optional">
-	<Para>
-	  If you have prevously invoked the regression test, clean up the
-	  working directory with:
-	  
-	  <ProgramListing>
-	    cd /usr/src/pgsql/src/test/regress
-	    make clean
-	  </ProgramListing>
-	</para>
-      </step>
+    
+    <Procedure>
+      <Title><ProductName>Postgres</ProductName> Regression Configuration</Title>
+
       <Step Performance="required">
 	<Para>
 	  The file /usr/src/pgsql/src/test/regress/README has detailed
@@ -210,21 +189,41 @@ the following:
 	</Para>
       </Step>
 
-      <Step Performance="required">
+      <Step Performance="optional">
 	<Para>
-	  Run the regression tests.  Type
+	  If you have previously invoked the regression test, clean up the
+	  working directory with:
 
 	  <ProgramListing>
 	    cd /usr/src/pgsql/src/test/regress
-	    gmake runtest
+	    gmake clean
 	  </ProgramListing>
-	</Para>
-	
+	</para>
 	<Para>
-	  
 	  You do not need to type "gmake clean" if this is the first time you
 	  are running the tests.
 	</Para>
+      </step>
+
+      
+      <Step Performance="required">
+	<Para>
+	  Build the regression test. Type
+	  <ProgramListing>
+	    cd /usr/src/pgsql/src/test/regress
+	    gmake all
+	  </ProgramListing>
+	</Para>
+      </Step>
+      
+      <Step Performance="required">
+	<Para>
+	  Run the regression tests.  Type
+	  <ProgramListing>
+	    cd /usr/src/pgsql/src/test/regress
+	    gmake runtest
+	  </ProgramListing>
+	</Para>
       </Step>
 
       <Step Performance="required">
@@ -245,61 +244,44 @@ the following:
 
       <Step Performance="required">
 	<Para>
-	  After running the tests, type
+	  After running the tests and examining the results, type
 	  <ProgramListing>
 	    destroydb regression
 	    cd /usr/src/pgsql/src/test/regress
 	    gmake clean
 	  </ProgramListing>
+	  to recover the temporary disk space used by the tests.
 	</Para>
       </Step>
     </procedure>
   </Sect1>
 
   <Sect1>
     <Title>Regression Analysis</Title>
-    
-    <Para>
-      <Quote>Failed</Quote> tests may have failed due to slightly different error messages,
-      math libraries, or output formatting.
+
+     <Para>
+       The results are in files in the ./results directory. These results
+       can be compared with results in the ./expected directory using 'diff'.
+       (The test script does this for you, and leaves the differences
+       in ./regression.diffs.)
+     </Para>
+
+     <Para>
+       The files might not compare exactly.  The test script will report
+       any difference as a "failure", but the difference might be due
+       to small cross-system differences in error message wording,
+       math library behavior, etc.
       "Failures" of this type do not indicate a problem with
       <ProductName>Postgres</ProductName>.
     </Para>
 
     <Para>
-      For a i686/Linux-ELF platform, no tests failed since this is the
-      v6.2.1 regression testing reference platform.
-    </Para>
-    
-    <Para>
-      For the SPARC/Linux-ELF platform, using the 970525 beta version of
-      <ProductName>Postgres</ProductName> v6.2 the following tests "failed":
-      float8 and geometry "failed" due to minor precision differences in
-      floating point numbers.  select_views produces massively different output,
-      but the differences are due to minor floating point differences.
-    </Para>
-    
-    <Para>
-      Conclusion?  If you do see failures, try to understand the nature of
-      the differences and then decide if those differences will affect your
-      intended use of <ProductName>Postgres</ProductName>.  However, keep in mind that this is likely
-      to be the most solid release of <ProductName>Postgres</ProductName> to date, incorporating many
-      bug fixes from v6.1, and that previous versions of <ProductName>Postgres</ProductName> have been
-      in use successfully for some time now.
+      Thus, it is necessary to examine the actual differences for each
+      "failed" test to determine whether there is really a problem.
+      The following paragraphs attempt to provide some guidance in
+      determining whether a difference is significant or not.
     </Para>
 
-    <Sect2>
-      <Title>Comparing expected/actual output</Title>
-
-      <Para>
-	The results are in files in the ./results directory. These results
-	can be compared with results in the ./expected directory using 'diff'.
-	The files might not compare exactly. The following paragraphs attempt
-	to explain the differences.
-      </Para>
-      
-    </Sect2>
-    
     <Sect2>
       <Title>Error message differences</Title>
 
@@ -337,18 +319,24 @@ the following:
       <Title>Date and time differences</Title>
 
       <Para>
-	On many supported platforms, you can force PostgreSQL to believe that it
-	is running in the same time zone as Berkeley, California. See details in
-	the section on how to run the regression tests.
-	
-	If you do not explicitly set your time zone environment to PST8PDT, then
-	most of the date and time results will reflect your local time zone and
-	will fail the regression testing.
-	
-	There appears to be some systems which do not accept the recommended syntax
-	for explicitly setting the local time zone rules. Some systems using the
-	public domain time zone package exhibit minor problems with pre-1970 PDT
-	times, representing them in PST instead.
+  Most of the date and time results are dependent on timezone environment.
+  The reference files are generated for timezone PST8PDT (Berkeley,
+  California) and there will be apparent failures if the tests are not
+  run with that timezone setting.  The regression test driver sets
+  environment variable PGTZ to PST8PDT to ensure proper results.
+      </Para>
+
+      <Para>
+  There appear to be some systems which do not accept the recommended syntax
+  for explicitly setting the local time zone rules; you may need to use
+  a different PGTZ setting on such machines.
+      </Para>
+
+      <Para>
+  Some systems using older timezone libraries fail to apply daylight-savings
+  corrections to pre-1970 dates, causing pre-1970 PDT times to be displayed
+  in PST instead.  This will result in localized differences in the test
+  results.
       </Para>
 
     </Sect2>
@@ -357,17 +345,17 @@ the following:
       <Title>Floating point differences</Title>
 
       <Para>
-	Some of the tests involve computing 64-bit (<Type>float8</Type>) number from table
+	Some of the tests involve computing 64-bit (<Type>float8</Type>) numbers from table
 	columns. Differences in results involving mathematical functions of
-	<Type>float8</Type> columns have been observed. These differences occur where
-	different operating systems are used on the same platform ie:
-	BSDI and SOLARIS on Intel/86, and where the same operating system is
-	used used on different platforms, ie: SOLARIS on SPARC and Intel/86.
-	
+	<Type>float8</Type> columns have been observed.  The float8
+	and geometry tests are particularly prone to small differences
+	across platforms.
 	Human eyeball comparison is needed to determine the real significance
 	of these differences which are usually 10 places to the right of
 	the decimal point.
-	
+      </Para>
+
+      <Para>
 	Some systems signal errors from pow() and exp() differently from
 	the mechanism expected by the current Postgres code.
       </Para>
@@ -403,7 +391,8 @@ the following:
 
       <Para>
 	There is at least one test case in random.out which is intended to produce
-	random results. This causes random to fail the regression testing.
+	random results. This causes random to fail the regression testing
+	once in a while.
 	Typing
 	<ProgramListing>
 	  diff results/random.out expected/random.out