diff options
Diffstat (limited to 'doc/src')
| -rw-r--r-- | doc/src/sgml/Makefile | 15 | ||||
| -rw-r--r-- | doc/src/sgml/docguide.sgml | 20 | ||||
| -rw-r--r-- | doc/src/sgml/filelist.sgml | 13 | ||||
| -rw-r--r-- | doc/src/sgml/installation.sgml | 36 | ||||
| -rw-r--r-- | doc/src/sgml/regress.sgml | 35 | ||||
| -rw-r--r-- | doc/src/sgml/standalone-install.sgml | 6 |
6 files changed, 65 insertions, 60 deletions
diff --git a/doc/src/sgml/Makefile b/doc/src/sgml/Makefile index bf3c70f8538..3e7c0a8bc3a 100644 --- 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 index 1c295a1a118..3d12e4e2e2b 100644 --- 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 index 7f81f6cdca6..6761d59f289 100644 --- 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 index 3aee49adf7c..49bb5c2dcc1 100644 --- 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 index bdeadfb9bf0..ab36ff87e30 100644 --- 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,9 +99,9 @@ </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> @@ -107,6 +109,7 @@ 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 index 88914cb5a71..2e657acb93a 100644 --- 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 |