Doc patch: improve testsuite docs (v3)

[Nathanael Nerode]

Take three.  I *still* think the distinction between c-torture and dg 
is artificial and poorly maintained, but this is just a documentation
patch.  I haven't deleted anything from the README because I'm not quite
sure what is redundant, and a little redundancy never hurt anyone.  I'll
do that once the manual is in much better shape.

	* sourcebuild.texi (Test Suites): Improve.

Index: sourcebuild.texi
===================================================================
RCS file: /cvs/gcc/gcc/gcc/doc/sourcebuild.texi,v
retrieving revision 1.10
diff -u -r1.10 sourcebuild.texi
--- sourcebuild.texi	4 Sep 2002 16:09:30 -0000	1.10
+++ sourcebuild.texi	5 Oct 2002 22:06:44 -0000
@@ -824,6 +824,10 @@
 @code{static} to call @code{abort ()} (although redeclaring a function
 as static may not work on all targets).
 
+All testcases must be portable.  Target-specific testcases must have
+appropriate code to avoid causing failures on unsupported systems;
+unfortunately, the mechanisms for this differ by directory.
+
 FIXME: discuss non-C test suites here.
 
 @node C Tests
@@ -833,6 +837,42 @@
 @file{gcc/testsuite} directory:
 
 @table @file
+@item gcc.dg
+This contains tests of particular features of the C compiler, using the 
+more modern @samp{dg} harness.  Correctness tests for various compiler
+features should go here if possible.
+
+Magic comments determine whether the file 
+is preprocessed, compiled, linked or run.  In these tests, error and warning 
+message texts are compared against expected texts or regular expressions 
+given in comments.  These tests are run with the options @samp{-ansi -pedantic}
+unless other options are given in the test.  Except as noted below they
+are not run with multiple optimization options.
+@item gcc.dg/cpp
+This subdirectory contains tests of the preprocessor.
+@item gcc.dg/debug
+This subdirectory contains tests for debug formats.  Tests in this
+subdirectory are run for each debug format that the compiler supports.
+@item gcc.dg/format
+This subdirectory contains tests of the @option{-Wformat} format
+checking.  Tests in this directory are run with and without
+@option{-DWIDE}.
+@item gcc.dg/noncompile
+This subdirectory contains tests of code that should not compile and
+does not need any special compilation options.  They are run with
+multiple optimization options, since sometimes invalid code crashes
+the compiler with optimization.
+@item gcc.dg/special
+FIXME: describe this.
+
+@item gcc.c-torture
+This contains particlar code fragments which have historically broken easily.
+These tests are run with multiple optimization options, so tests for features
+which only break at some optimization levels belong here.  This also contains
+tests to check that certain optimizations occur.  It might be worthwhile to 
+separate the correctness tests cleanly from the code quality tests, but
+it hasn't been done yet.
+
 @item gcc.c-torture/compat
 FIXME: describe this.
 
@@ -850,34 +890,12 @@
 @item gcc.c-torture/execute
 This test suite contains test cases that should compile, link and run;
 otherwise the same comments as for @file{gcc.c-torture/compile} apply.
+@item gcc.c-torture/execute/ieee
+This contains tests which are specific to IEEE floating point.
 @item gcc.c-torture/unsorted
 FIXME: describe this.
 
 This directory should probably not be used for new tests.
-@item gcc.dg
-This test suite contains tests using the more modern @samp{dg} harness.
-Magic comments determine whether the file is preprocessed, compiled,
-linked or run.  In these tests, error and warning message texts are
-compared against expected texts or regular expressions given in
-comments.  These tests are run with the options @samp{-ansi -pedantic}
-unless other options are given in the test.  Except as noted below they
-are not run with multiple optimization options.
-@item gcc.dg/cpp
-This subdirectory contains tests of the preprocessor.
-@item gcc.dg/debug
-This subdirectory contains tests for debug formats.  Tests in this
-subdirectory are run for each debug format that the compiler supports.
-@item gcc.dg/format
-This subdirectory contains tests of the @option{-Wformat} format
-checking.  Tests in this directory are run with and without
-@option{-DWIDE}.
-@item gcc.dg/noncompile
-This subdirectory contains tests of code that should not compile and
-does not need any special compilation options.  They are run with
-multiple optimization options, since sometimes invalid code crashes
-the compiler with optimization.
-@item gcc.dg/special
-FIXME: describe this.
 @item gcc.c-torture/misc-tests
 FIXME: describe this, when it should be used for new tests and when it
 shouldn't.