--- a/man/ChangeLog	Fri Aug 16 08:15:42 2002 +0000
+++ b/man/ChangeLog	Fri Aug 16 12:37:45 2002 +0000
@@ -1,3 +1,9 @@
+2002-08-15  Stephen J. Turnbull  <stephen@xemacs.org>
+ 
+	* internals/internals.texi (GCPROing): Add comment on GCPRO.
+	(Regression Testing XEmacs): New node.
+	(Modules for Regression Testing): New node.
+
 2002-08-12  Simon Josefsson  <jas@extundo.com>
 
 	* lispref/building.texi (Pure Storage): purecopy is a no-op.

--- a/man/internals/internals.texi	Fri Aug 16 08:15:42 2002 +0000
+++ b/man/internals/internals.texi	Fri Aug 16 12:37:45 2002 +0000
@@ -118,6 +118,7 @@
 * How Lisp Objects Are Represented in C::
 * Major Textual Changes::
 * Rules When Writing New C Code::
+* Regression Testing XEmacs::
 * CVS Techniques::
 * A Summary of the Various XEmacs Modules::
 * Allocation of Objects in XEmacs Lisp::
@@ -174,6 +175,8 @@
 
 * Merging a Branch into the Trunk::
 
+Regression Testing XEmacs
+
 A Summary of the Various XEmacs Modules
 
 * Low-Level Modules::
@@ -188,6 +191,7 @@
 * Modules for Interfacing with the Operating System::
 * Modules for Interfacing with X Windows::
 * Modules for Internationalization::
+* Modules for Regression Testing::
 
 Allocation of Objects in XEmacs Lisp
 
@@ -2175,7 +2179,7 @@
 gr '_Itext' _CHARPTR $files
 @end example
 
-@node Rules When Writing New C Code, CVS Techniques, Major Textual Changes, Top
+@node Rules When Writing New C Code, Regression Testing XEmacs, Major Textual Changes, Top
 @chapter Rules When Writing New C Code
 @cindex writing new C code, rules when
 @cindex C code, rules when writing new
@@ -3432,7 +3436,74 @@
 add an INIT_LRECORD_IMPLEMENTATION call to @code{syms_of_@var{foo}.c}
 @end enumerate
 
-@node CVS Techniques, A Summary of the Various XEmacs Modules, Rules When Writing New C Code, Top
+@node Regression Testing XEmacs, CVS Techniques, Rules When Writing New C Code, Top
+@chapter Regression Testing XEmacs
+@cindex testing, regression
+
+The source directory @file{tests/automated} contains XEmacs' automated
+test suite.  The usual way of running all the tests is running
+@code{make check} from the top-level build directory.
+
+The test suite is unfinished and it's still lacking some essential
+features.  It is nevertheless recommended that you run the tests to
+confirm that XEmacs behaves correctly.
+
+If you want to run a specific test case, you can do it from the
+command-line like this:
+
+@example
+$ xemacs -batch -l test-harness.elc -f batch-test-emacs TEST-FILE
+@end{example}
+
+If something goes wrong, you can run the test suite interactively by
+loading @file{test-harness.el} into a running XEmacs and typing
+@kbd{M-x test-emacs-test-file RET <filename> RET}.  You will see a log of
+passed and failed tests, which should allow you to investigate the
+source of the error and ultimately fix the bug.
+
+Adding a new test file is trivial: just create a new file here and it
+will be run.  There is no need to byte-compile any of the files in
+this directory---the test-harness will take care of any necessary
+byte-compilation.
+
+Look at the existing test cases for the examples of coding test cases.
+It all boils down to your imagination and judicious use of the macros
+@code{Assert}, @code{Check-Error}, @code{Check-Error-Message}, and
+@code{Check-Message}.
+
+Here's a simple example checking case-sensitive and case-insensitive
+comparisons from @file{case-tests.el}.
+
+@example
+(with-temp-buffer
+  (insert "Test Buffer")
+  (let ((case-fold-search t))
+    (goto-char (point-min))
+    (Assert (eq (search-forward "test buffer" nil t) 12))
+    (goto-char (point-min))
+    (Assert (eq (search-forward "Test buffer" nil t) 12))
+    (goto-char (point-min))
+    (Assert (eq (search-forward "Test Buffer" nil t) 12))
+
+    (setq case-fold-search nil)
+    (goto-char (point-min))
+    (Assert (not (search-forward "test buffer" nil t)))
+    (goto-char (point-min))
+    (Assert (not (search-forward "Test buffer" nil t)))
+    (goto-char (point-min))
+    (Assert (eq (search-forward "Test Buffer" nil t) 12))))
+@end{example}
+
+This example could be inserted in a file in @file{tests/automated}, and
+it would be a complete test, automatically executed when you run
+@kbd{make check} after building XEmacs.  More complex tests may require
+substantial temporary scaffolding to create the environment that elicits
+the bugs, but the top-level Makefile and @file{test-harness.el} handle
+the running and collection of results from the @code{Assert},
+@code{Check-Error}, @code{Check-Error-Message}, and @code{Check-Message}
+macros.
+
+@node CVS Techniques, A Summary of the Various XEmacs Modules, Regression Testing XEmacs, Top
 @chapter CVS Techniques
 @cindex CVS techniques
 
@@ -3541,6 +3612,7 @@
 * Modules for Interfacing with the Operating System::
 * Modules for Interfacing with X Windows::
 * Modules for Internationalization::
+* Modules for Regression Testing::
 @end menu
 
 @node Low-Level Modules
@@ -5205,6 +5277,36 @@
 
 
 
+@node Modules for Regression Testing
+@section Modules for Regression Testing
+@cindex modules for regression testing
+@cindex regression testing, modules for
+
+@example
+test-harness.el
+base64-tests.el
+byte-compiler-tests.el
+case-tests.el
+ccl-tests.el
+c-tests.el
+database-tests.el
+extent-tests.el
+hash-table-tests.el
+lisp-tests.el
+md5-tests.el
+mule-tests.el
+regexp-tests.el
+symbol-tests.el
+syntax-tests.el
+@end example
+
+@file{test-harness.el} defines the macros @code{Assert},
+@code{Check-Error}, @code{Check-Error-Message}, and
+@code{Check-Message}.  The other files are test files, testing various
+XEmacs facilities.
+
+
+
 @node Allocation of Objects in XEmacs Lisp, Dumping, A Summary of the Various XEmacs Modules, Top
 @chapter Allocation of Objects in XEmacs Lisp
 @cindex allocation of objects in XEmacs Lisp
@@ -5472,6 +5574,10 @@
 different section of code.
 @end enumerate
 
+If you don't understand whether to @code{GCPRO} in a particular
+instance, ask on the mailing lists.  A general hint is that @code{prog1}
+is the canonical example
+
 @cindex garbage collection, conservative
 @cindex conservative garbage collection
   Given the extremely error-prone nature of the @code{GCPRO} scheme, and

--- a/man/xemacs/packages.texi	Fri Aug 16 08:15:42 2002 +0000
+++ b/man/xemacs/packages.texi	Fri Aug 16 12:37:45 2002 +0000
@@ -95,9 +95,9 @@
 subdirectory @file{packages}.  Package file names follow
 the naming convention @file{<package-name>-<version>-pkg.tar.gz}.
 
-If you have EFS @ref{(EFS)}, packages can be installed over the network.
-Alternatively, if you have copies of the packages locally, you can
-install packages from a local disk or CDROM.
+If you have @ref{Top, EFS, , efs}, packages can be installed over the
+network.  Alternatively, if you have copies of the packages locally, you
+can install packages from a local disk or CDROM.
 
 The file @file{etc/PACKAGES} in the core distribution contains a list of
 the @ref{Available Packages} at the time of the XEmacs release.