[commit: ghc] master: Fix #9871 by clarifying documentation. (b06908b)

[git at git.haskell.org]

Repository : ssh://git@git.haskell.org/ghc

On branch  : master
Link       : http://ghc.haskell.org/trac/ghc/changeset/b06908b5a120ed56df5416019c38576aadcd21e2/ghc

>---------------------------------------------------------------

commit b06908b5a120ed56df5416019c38576aadcd21e2
Author: Richard Eisenberg <eir at cis.upenn.edu>
Date:   Mon Dec 8 10:59:48 2014 -0500

    Fix #9871 by clarifying documentation.


>---------------------------------------------------------------

b06908b5a120ed56df5416019c38576aadcd21e2
 docs/users_guide/glasgow_exts.xml | 33 +++++++++++++++++++++++----------
 1 file changed, 23 insertions(+), 10 deletions(-)

diff --git a/docs/users_guide/glasgow_exts.xml b/docs/users_guide/glasgow_exts.xml
index 18809fd..2c6cb6a 100644
--- a/docs/users_guide/glasgow_exts.xml
+++ b/docs/users_guide/glasgow_exts.xml
@@ -9174,21 +9174,29 @@ f n = \ [haskell|y|] -> y+n
 	      </para>
 	    </listitem>
 	    <listitem>
-	      <para>
-		The type environment seen by <literal>reify</literal> includes
-		all the top-level declaration up to the end of the immediately
-		preceding <emphasis>declaration group</emphasis>, but no more.
+              <para>
+		Top-level declaration splices break up a source file into
+		<emphasis>delcaration groups</emphasis>. A
+		<emphasis>declaration group</emphasis> is the group of
+		declarations created by a top-level declaration splice, plus
+		those following it, down to but not including the next
+		top-level declaration splice. The first declaration group in a
+		module includes all top-level definitions down to but not
+		including the first top-level declaration splice.
 	      </para>
 
 	      <para>
-		A <emphasis>declaration group</emphasis> is the group of
-		declarations created by a top-level declaration splice, plus
-		those following it, down to but not including the next top-level
-		declaration splice. The first declaration group in a module
-		includes all top-level definitions down to but not including the
-		first top-level declaration splice.
+		Each declaration group is mutually recursive only within
+		the group. Declaration groups can refer to definitions within
+		previous groups, but not later ones.
 	      </para>
 
+	      <para>
+		Accordingly, the type environment seen by
+		<literal>reify</literal> includes all the top-level
+		declarations up to the end of the immediately preceding
+		declaration group, but no more.
+	      </para>
 
 	      <para>
 		Concretely, consider the following code
@@ -9206,6 +9214,11 @@ module M where
               <orderedlist>
 		<listitem>
 		  <para>
+		    The body of <literal>h</literal> would be unable to refer
+		    to the function <literal>w</literal>.
+		  </para>
+
+		  <para>
 		    A <literal>reify</literal> inside the splice <literal>$(th1
 		    ..)</literal> would see the definition of
 		    <literal>f</literal>.