--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,8 @@
+2010-12-06  Bruno Haible  <bruno@clisp.org>
+
+	Update internal documentation.
+	* m4/README: Document new idioms for AC_RUN_IFELSE invocations.
+
 2010-12-04  Bruno Haible  <bruno@clisp.org>
 
 	Put more information about failed tests into the test return codes.

--- a/m4/README
+++ b/m4/README
@@ -73,6 +73,47 @@
   be the autoconf macro that provides it. This is only an approximation; in
   general you should look at all preprocessor directives in lib/foo.c.
 
+- In AC_RUN_IFELSE invocations, try to put as much information about failed
+  tests as possible in the exit code. The exit code is 0 for success and any
+  value between 1 and 127 for failure. The exit code is printed in config.log;
+  therefore when an AC_RUN_IFELSE invocation failed, it is possible to analyze
+  the failure immediately if sufficient information is contained in the exit
+  code.
+
+  For a program that performs a single test, the typical idiom is:
+
+      if (do_test1 ())
+        return 1;
+      return 0;
+
+  For a test that performs a test with some preparation, the typical idiom is
+  to return an enumerated value:
+
+      if (prep1 ())
+        return 1;
+      else if (prep2 ())
+        return 2;
+      else if (prep3 ())
+        return 3;
+      else if (do_test1 ())
+        return 4;
+      return 0;
+
+  For multiple independent tests in a single program, you can return a bit
+  mask with up to 7 bits:
+
+      int result = 0;
+      if (do_test1 ())
+        result |= 1;
+      if (do_test2 ())
+        result |= 2;
+      if (do_test3 ())
+        result |= 4;
+      return result;
+
+  For more than 7 independent tests, you have to map some possible test
+  failures to same bit.
+
 - After ANY modifications of an m4 file, you should increment its serial
   number (in the first line). Also, if this first line features a particular
   release, _remove_ this release stamp. Example: Change