Document SOURCE pragma; clarify TH behavior for mutually-recurive modules (Trac #1012)

2 files changed, 21 insertions, 5 deletions

diff --git a/docs/users_guide/glasgow_exts.xml b/docs/users_guide/glasgow_exts.xml
index de69b60063..26fff9a046 100644
--- a/docs/users_guide/glasgow_exts.xml
+++ b/docs/users_guide/glasgow_exts.xml
@@ -5000,9 +5000,13 @@ Type splices are not implemented, and neither are pattern splices or quotations.
    </para></listitem>
 
    <listitem><para>
-   Furthermore, you can only run a function at compile time if it is imported
+   You can only run a function at compile time if it is imported
    from another module <emphasis>that is not part of a mutually-recursive group of modules
-   that includes the module currently being compiled</emphasis>.  For example, when compiling module A,
+   that includes the module currently being compiled</emphasis>.  Furthermore, all of the modules of 
+   the mutually-recursive group must be reachable by non-SOURCE imports from the module where the
+   splice is to be run.</para>
+   <para>
+   For example, when compiling module A,
    you can only run Template Haskell functions imported from B if B does not import A (directly or indirectly).
    The reason should be clear: to run B we must compile and run A, but we are currently type-checking A.
    </para></listitem>
@@ -6374,14 +6378,14 @@ data T = T {-# UNPACK #-} !(Int,Int)
 
       <para>will store the two <literal>Int</literal>s directly in the
       <function>T</function> constructor, by flattening the pair.
-      Multi-level unpacking is also supported:</para>
+      Multi-level unpacking is also supported:
 
 <programlisting>
 data T = T {-# UNPACK #-} !S
 data S = S {-# UNPACK #-} !Int {-# UNPACK #-} !Int
 </programlisting>
 
-      <para>will store two unboxed <literal>Int&num;</literal>s
+      will store two unboxed <literal>Int&num;</literal>s
       directly in the <function>T</function> constructor.  The
       unpacker can see through newtypes, too.</para>
 
@@ -6395,6 +6399,15 @@ data S = S {-# UNPACK #-} !Int {-# UNPACK #-} !Int
       constructor field.</para>
     </sect2>
 
+    <sect2 id="source-pragma">
+      <title>SOURCE pragma</title>
+
+      <indexterm><primary>SOURCE</primary></indexterm>
+     <para>The <literal>{-# SOURCE #-}</literal> pragma is used only in <literal>import</literal> declarations,
+     to break a module loop.  It is described in detail in <xref linkend="mutual-recursion"/>.
+     </para>
+</sect2>
+
 </sect1>
 
 <!--  ======================= REWRITE RULES ======================== -->
diff --git a/docs/users_guide/separate_compilation.xml b/docs/users_guide/separate_compilation.xml
index fc22fbdef3..1bdb0c5344 100644
--- a/docs/users_guide/separate_compilation.xml
+++ b/docs/users_guide/separate_compilation.xml
@@ -702,7 +702,10 @@ module B where
       <literal>hi-boot</literal> files</primary></indexterm>
 Here <filename>A</filename> imports <filename>B</filename>, but <filename>B</filename> imports
 <filename>A</filename> with a <literal>{-# SOURCE #-}</literal> pragma, which breaks the
-circular dependency.  For every module <filename>A.hs</filename> that is <literal>{-# SOURCE #-}</literal>-imported
+circular dependency.  Every loop in the module import graph must be broken by a <literal>{-# SOURCE #-}</literal> import;
+or, equivalently, the module import graph must be acyclic if <literal>{-# SOURCE #-}</literal> imports are ignored.
+</para>
+<para>For every module <filename>A.hs</filename> that is <literal>{-# SOURCE #-}</literal>-imported
 in this way there must exist a source file <literal>A.hs-boot</literal>.  This file contains an abbreviated
 version of <filename>A.hs</filename>, thus:
 <programlisting>