--- old-cabal/doc/Cabal.xml	2005-08-19 22:11:45.000000000 -0700
+++ new-cabal/doc/Cabal.xml	2005-08-19 22:36:54.000000000 -0700
@@ -842,14 +842,33 @@
         <listitem>
           <para>If the package root directory contains a file called
             <filename>configure</filename>, the configure step will
-            run that.  This <filename>configure</filename> program may
+            run that. This <filename>configure</filename> program may
             be a script produced by the <command>autoconf</command>
-            system, or may be hand-written.  This program typically
+            system, or may be hand-written. This program typically
             discovers information about the system and records it for
-            later steps, e.g. by generating system-dependent header files
-            for inclusion in C source files and preprocessed Haskell
-            source files.  (Clearly this won't work for Windows without
-            MSYS or Cygwin: other ideas are needed.)</para>
+            later steps, e.g. by generating system-dependent header
+            files for inclusion in C source files and preprocessed
+            Haskell source files. (Clearly this won't work for Windows
+            without MSYS or Cygwin: other ideas are needed.) N.B.:
+            Although <literal>defaultMain</literal> doesn't always
+            check for a file named <filename>configure</filename>, if
+            one such file does exist, it should always be run by
+            <filename>Setup.hs</filename> rather than vice-versa. So
+            if you are a generic packaging tool, and you see a file
+            named <filename>Setup.hs</filename> or
+            <filename>Setup.lhs</filename> as well as a file named
+            <filename>configure</filename>, then you should invoke
+            Cabal via <filename>Setup.[l]hs</filename> and not
+            <command>autoconf</command> via
+            <filename>configure</filename>. Likewise, if you are a
+            programmer putting together a Cabal package, and need to
+            do <command>autoconf</command> configuration, you should
+            do it through Cabal using e.g.
+            <literal>defaultMainWithHooks</literal>, and ask the user
+            to invoke everything through
+            <filename>Setup.lhs</filename> - rather than telling the
+            user to run <command>./configure</command> first and, say,
+            using that to generate a Cabal file.</para>
         </listitem>
 
         <listitem>