Readd test/regress/README file, this time with a well-defined and simple

petere · petere · commit 4e77b4a5487c · 2001-09-21T18:37:05.000Z
rule to remake it when necessary.
diff --git a/doc/src/sgml/Makefile b/doc/src/sgml/Makefile
@@ -8,7 +8,7 @@
 #
 #
 # IDENTIFICATION
-#    $Header: /cvsroot/pgsql/doc/src/sgml/Makefile,v 1.39 2001/09/18 12:08:26 petere Exp $
+#    $Header: /cvsroot/pgsql/doc/src/sgml/Makefile,v 1.40 2001/09/21 18:37:05 petere Exp $
 #
 #----------------------------------------------------------------------------
 
@@ -148,10 +148,10 @@ $(addsuffix .tex, $(ALLBOOKS)): %.tex: %.sgml $(ALLSGML) stylesheet.dsl
 
 JADE.text = $(JADE) $(JADEFLAGS) $(SGMLINCLUDE) -c $(CATALOG) -d stylesheet.dsl -i output-text -t sgml
 
-INSTALL HISTORY: % : %.html
+INSTALL HISTORY regress_README: % : %.html
 	@echo "|";\
-	 echo "| You should now take \`$<', save it as a text file in Netscape,";\
-	 echo "| and put it in place of the existing \`$@' file.";\
+	 echo "| You should now take '$<', save it as a text file in Netscape,";\
+	 echo "| and put it in place of the existing '$@' file.";\
 	 echo "|"
 
 INSTALL.html: standalone-install.sgml installation.sgml
@@ -163,6 +163,13 @@ HISTORY.html: release.sgml
 	$(JADE.text) -V nochunks tempfile_HISTORY.sgml >$@
 	rm tempfile_HISTORY.sgml
 
+regress_README.html: regress.sgml
+	( echo '<!doctype chapter PUBLIC "-//OASIS//DTD DocBook V3.1//EN" ['; \
+	  echo '<!entity % standalone-ignore "IGNORE"> ]>'; \
+	  cat $< ) >tempfile_regress_README.sgml
+	$(JADE.text) -V nochunks tempfile_regress_README.sgml >$@
+	rm tempfile_regress_README.sgml
+
 
 ##
 ## Check
diff --git a/doc/src/sgml/docguide.sgml b/doc/src/sgml/docguide.sgml
@@ -1,4 +1,4 @@
-<!-- $Header: /cvsroot/pgsql/doc/src/sgml/docguide.sgml,v 1.33 2001/09/13 15:55:22 petere Exp $ -->
+<!-- $Header: /cvsroot/pgsql/doc/src/sgml/docguide.sgml,v 1.34 2001/09/21 18:37:05 petere Exp $ -->
 
 <appendix label="DG2" id="docguide">
  <title>Documentation</title>
@@ -901,21 +901,9 @@ exit
 
    <para>
     The file <filename>HISTORY</filename> can be created similarly,
-    using the command <userinput>gmake HISTORY</userinput>.  The table
-    of contents should be removed manually from the resulting text
-    file.
-   </para>
-
-   <para>
-    Since it does not change very often, the generation of the file
-    <filename>src/test/regress/README</filename> is not fully
-    automated.  After building the <acronym>HTML</acronym> version of
-    the <citetitle>Administrator's Guide</citetitle>, convert the
-    resulting files <filename>regress.html</filename> and
-    <filename>regress-platform.html</filename> to text, using
-    <productname>Netscape</productname>.  Then paste the text files
-    together and edit them to taste (e.g., remove the navigation
-    bars, remove the references to other chapters).
+    using the command <userinput>gmake HISTORY</userinput>.  For the
+    file <filename>src/test/regress/README</filename> the command is
+    <userinput>gmake regress_README</userinput>.
    </para>
 
 <!--
diff --git a/doc/src/sgml/filelist.sgml b/doc/src/sgml/filelist.sgml
@@ -1,4 +1,4 @@
-<!-- $Header: /cvsroot/pgsql/doc/src/sgml/filelist.sgml,v 1.15 2001/09/02 23:27:49 petere Exp $ -->
+<!-- $Header: /cvsroot/pgsql/doc/src/sgml/filelist.sgml,v 1.16 2001/09/21 18:37:05 petere Exp $ -->
 
 <!entity history    SYSTEM "history.sgml">
 <!entity info       SYSTEM "info.sgml">
@@ -100,6 +100,11 @@
 <!entity sources    SYSTEM "sources.sgml">
 <!entity nls        SYSTEM "nls.sgml">
 
-<!-- see standalone-install.sgml about these -->
-<!entity % flattext-install-ignore  "INCLUDE">
-<!entity % flattext-install-include "IGNORE">
+<!--
+ Some parts of the documentation are also source for some plain-text
+ files used during installation.  To selectively ignore or include
+ some parts (e.g., external xref's) when generating these files we use
+ these parameter entities.  See also standalone-install.sgml.
+ -->
+<!entity % standalone-ignore  "INCLUDE">
+<!entity % standalone-include "IGNORE">
diff --git a/doc/src/sgml/installation.sgml b/doc/src/sgml/installation.sgml
@@ -1,7 +1,7 @@
-<!-- $Header: /cvsroot/pgsql/doc/src/sgml/installation.sgml,v 1.56 2001/09/16 16:11:09 petere Exp $ -->
+<!-- $Header: /cvsroot/pgsql/doc/src/sgml/installation.sgml,v 1.57 2001/09/21 18:37:05 petere Exp $ -->
 
 <chapter id="installation">
- <title><![%flattext-install-include[<productname>PostgreSQL</>]]>
+ <title><![%standalone-include[<productname>PostgreSQL</>]]>
   Installation Instructions</title>
 
  <indexterm zone="installation">
@@ -27,8 +27,8 @@ su - postgres
 /usr/local/pgsql/bin/psql test
 </synopsis>
    The long version is the rest of this
-   <![%flattext-install-include;[document.]]>
-   <![%flattext-install-ignore;[chapter.]]>
+   <![%standalone-include;[document.]]>
+   <![%standalone-ignore;[chapter.]]>
   </para>
  </sect1>
 
@@ -156,7 +156,7 @@ su - postgres
   </para>
  </sect1>
 
-<![%flattext-install-ignore;[
+<![%standalone-ignore;[
  <sect1 id="install-getsource">
   <title>Getting The Source</title>
 
@@ -221,8 +221,8 @@ su - postgres
      foreign keys), then use the <option>-o</option> option when running
      <command>pg_dumpall</>.  <command>pg_dumpall</command> does not
      save large objects.  Check
-     <![%flattext-install-include[the <citetitle>Administrator's Guide</>]]>
-     <![%flattext-install-ignore[<xref linkend="backup-dump-caveats">]]>
+     <![%standalone-include[the <citetitle>Administrator's Guide</>]]>
+     <![%standalone-ignore[<xref linkend="backup-dump-caveats">]]>
      if you need to do this.
     </para>
 
@@ -290,8 +290,8 @@ su - postgres
   <para>
    You can also install the new version in parallel with the old one
    to decrease the downtime. These topics are discussed at length in
-   <![%flattext-install-include[the <citetitle>Administrator's Guide</>,]]>
-   <![%flattext-install-ignore[<xref linkend="migration">,]]>
+   <![%standalone-include[the <citetitle>Administrator's Guide</>,]]>
+   <![%standalone-ignore[<xref linkend="migration">,]]>
    which you are encouraged
    to read in any case.
   </para>
@@ -531,8 +531,8 @@ su - postgres
        <listitem>
         <para>
          Enables single-byte character set recode support. See
-         <![%flattext-install-include[the <citetitle>Administrator's Guide</citetitle>]]>
-         <![%flattext-install-ignore[<xref linkend="recode">]]> about this feature.
+         <![%standalone-include[the <citetitle>Administrator's Guide</citetitle>]]>
+         <![%standalone-ignore[<xref linkend="recode">]]> about this feature.
         </para>
        </listitem>
       </varlistentry>
@@ -544,8 +544,8 @@ su - postgres
          Allows the use of multibyte character encodings. This is
          primarily for languages like Japanese, Korean, and Chinese.
          Read 
-         <![%flattext-install-include[the <citetitle>Administrator's Guide</citetitle>]]>
-         <![%flattext-install-ignore[<xref linkend="multibyte">]]>
+         <![%standalone-include[the <citetitle>Administrator's Guide</citetitle>]]>
+         <![%standalone-ignore[<xref linkend="multibyte">]]>
          for details.
         </para>
        </listitem>
@@ -902,10 +902,10 @@ All of PostgreSQL is successfully made. Ready to install.
 </screen>
     It is possible that some tests fail, due to differences in error
     message wording or floating point results.
-    <![%flattext-install-include[The file
+    <![%standalone-include[The file
     <filename>src/test/regress/README</> and the
     <citetitle>Administrator's Guide</citetitle> contain]]>
-    <![%flattext-install-ignore[<xref linkend="regress"> contains]]>
+    <![%standalone-ignore[<xref linkend="regress"> contains]]>
     detailed information about interpreting the test results. You can
     repeat this test at any later time by issuing the same command.
    </para>
@@ -1127,7 +1127,7 @@ MANPATH=$MANPATH:/usr/local/pgsql/man
  </sect1>
 
 
-<![%flattext-install-include;[
+<![%standalone-include;[
  <sect1 id="install-getting-started">
   <title>Getting Started</title>
 
@@ -1634,8 +1634,8 @@ gunzip -c user.ps.gz \
       <entry>2001-03-26, Magnus Hagander (<email>mha@sollentuna.net</email>)</entry>
       <entry>
        client-side libraries (<application>libpq</> and <application>psql</>) or ODBC/JDBC, no server-side;
-<![%flattext-install-include[see Administrator's Guide]]>
-<![%flattext-install-ignore[see <xref linkend="install-win32">]]>
+<![%standalone-include[see Administrator's Guide]]>
+<![%standalone-ignore[see <xref linkend="install-win32">]]>
        for instructions
       </entry>
      </row>
diff --git a/doc/src/sgml/regress.sgml b/doc/src/sgml/regress.sgml
@@ -1,13 +1,10 @@
-<!-- $Header: /cvsroot/pgsql/doc/src/sgml/regress.sgml,v 1.20 2001/09/11 02:24:52 ishii Exp $ -->
+<!-- $Header: /cvsroot/pgsql/doc/src/sgml/regress.sgml,v 1.21 2001/09/21 18:37:05 petere Exp $ -->
 
  <chapter id="regress">
   <title id="regress-title">Regression Tests</title>
 
-  <abstract>
-   <para>
-    Regression test instructions and analysis
-   </para>
-  </abstract>
+  <sect1 id="regress-intro">
+   <title>Introduction</title>
 
   <para>
    The regression tests are a comprehensive set of tests for the SQL
@@ -20,6 +17,11 @@
    the regression tests are current for every official release.
   </para>
 
+  </sect1>
+
+  <sect1 id="regress-run">
+   <title>Running the Tests</title>
+
   <para>
    The regression test can be run against an already installed and
    running server, or using a temporary installation within the build
@@ -97,16 +99,17 @@
   </tip>
 
   <para>
-   To run the tests after installation (see <xref
-   linkend="installation">), initialize a data area and start the
-   server, as explained in <xref linkend="runtime">, then type
+   To run the tests after installation<![%standalone-ignore;[ (see <xref linkend="installation">)]]>,
+   initialize a data area and start the
+   server, <![%standalone-ignore;[as explained in <xref linkend="runtime">, ]]> then type
 <screen>
 <prompt>$ </prompt><userinput>gmake installcheck</userinput>
 </screen>
    The tests will expect to contact the server at the local host and the
    default port number, unless directed otherwise by <envar>PGHOST</envar> and <envar>PGPORT</envar>
    environment variables.
   </para>
+  </sect1>
 
   <sect1 id="regress-evaluation">
    <title>Test Evaluation</title> 
@@ -255,7 +258,7 @@ PGTZ='PST8PDT7,M04.01.0,M10.05.03'; export PGTZ
       
     <para>
      Several of the tests involve operations on geographic data about
-     the Oakland/Berkeley, CA street map. The map data is expressed as
+     the Oakland/Berkeley, California street map. The map data is expressed as
      polygons whose vertices are represented as pairs of <type>double
      precision</type> numbers (decimal latitude and
      longitude). Initially, some tables are created and loaded with
@@ -277,15 +280,15 @@ SELECT * from iexit;
    </sect2>
 
    <sect2>
-    <title>Tuple ordering differences</title>
+    <title>Row ordering differences</title>
       
     <para>
-You might see differences in which the same tuples are output in a
+You might see differences in which the same rows are output in a
 different order than what appears in the expected file.  In most cases
 this is not, strictly speaking, a bug.  Most of the regression test
 scripts are not so pedantic as to use an ORDER BY for every single
-SELECT, and so their result tuple orderings are not well-defined
-according to the letter of the SQL spec.  In practice, since we are
+SELECT, and so their result row orderings are not well-defined
+according to the letter of the SQL specification.  In practice, since we are
 looking at the same queries being executed on the same data by the same
 software, we usually get the same result ordering on all platforms, and
 so the lack of ORDER BY isn't a problem.  Some queries do exhibit
@@ -325,12 +328,13 @@ diff results/random.out expected/random.out
      not worry unless the random test always fails in repeated
      attempts.  (On the other hand, if the random test is
      <emphasis>never</emphasis> reported to fail even in many trials
-     of the regress tests, you probably <emphasis>should</emphasis>
+     of the regression tests, you probably <emphasis>should</emphasis>
      worry.)
     </para>
    </sect2>
   </sect1>
 
+<![%standalone-ignore;[
 <!-- We might want to move the following section into the developer's guide. -->
   <sect1 id="regress-platform">
    <title>Platform-specific comparison files</title>
@@ -384,6 +388,7 @@ horology/hppa=horology-no-DST-before-1970
    </para>
     
   </sect1>
+]]>
   
 </chapter>
 
diff --git a/doc/src/sgml/standalone-install.sgml b/doc/src/sgml/standalone-install.sgml
@@ -1,4 +1,4 @@
-<!-- $Header: /cvsroot/pgsql/doc/src/sgml/standalone-install.sgml,v 2.2 2000/11/30 21:44:07 petere Exp $ -->
+<!-- $Header: /cvsroot/pgsql/doc/src/sgml/standalone-install.sgml,v 2.3 2001/09/21 18:37:05 petere Exp $ -->
 
 <!--
 This file helps in generating the INSTALL text file that lives in the
@@ -32,8 +32,8 @@ equivalent of C's #ifdef and friends. The other end of this is in
 installation.sgml.
 -->
 
- <!entity % flattext-install-ignore  "IGNORE">
- <!entity % flattext-install-include "INCLUDE">
+ <!entity % standalone-ignore  "IGNORE">
+ <!entity % standalone-include "INCLUDE">
 
 <!--
 When you're building the Administrator's Guide, you want to flip the
diff --git a/src/test/regress/README b/src/test/regress/README
