X-Git-Url: http://git.megacz.com/?a=blobdiff_plain;f=ghc%2Fdocs%2Fusers_guide%2Fglasgow_exts.xml;h=a25d42e89712e066a786d6f5cda416e9ea96dd2b;hb=8e14697c6e2cccc0a632233ffe95505765db2eef;hp=93237d0ebbeff615a07d2fdc05cb20b052810fb6;hpb=766c499e75fa1aa178694dc1a74d1ecbabef0332;p=ghc-hetmet.git

diff --git a/ghc/docs/users_guide/glasgow_exts.xml b/ghc/docs/users_guide/glasgow_exts.xml
index 93237d0..a25d42e 100644
--- a/ghc/docs/users_guide/glasgow_exts.xml
+++ b/ghc/docs/users_guide/glasgow_exts.xml
@@ -1731,7 +1731,7 @@ means
 <sect2 id="instance-decls">
 <title>Instance declarations</title>
 
-<sect3>
+<sect3 id="instance-overlap">
 <title>Overlapping instances</title>
 <para>
 In general, <emphasis>GHC requires that that it be unambiguous which instance
@@ -1787,6 +1787,11 @@ So GHC rejects the program.  If you add the flag <option>-fallow-incoherent-inst
 GHC will instead pick (C), without complaining about 
 the problem of subsequent instantiations.
 </para>
+<para>
+Because overlaps are checked and reported lazily, as described above, you need
+the <option>-fallow-overlapping-instances</option> in the module that <emphasis>calls</emphasis> 
+the overloaded function, rather than in the module that <emphasis>defines</emphasis> it.</para>
+
 </sect3>
 
 <sect3>
@@ -2673,22 +2678,19 @@ for rank-2 types.
 </title>
 
 <para>
-A <emphasis>pattern type signature</emphasis> can introduce a <emphasis>scoped type
-variable</emphasis>.  For example
-</para>
-
-<para>
-
+A <emphasis>lexically scoped type variable</emphasis> can be bound by:
+<itemizedlist>
+<listitem><para>A declaration type signature (<xref linkend="decl-type-sigs"/>)</para></listitem>
+<listitem><para>A pattern type signature (<xref linkend="pattern-type-sigs"/>)</para></listitem>
+<listitem><para>A result type signature (<xref linkend="result-type-sigs"/>)</para></listitem>
+</itemizedlist>
+For example:
 <programlisting>
 f (xs::[a]) = ys ++ ys
            where
               ys :: [a]
               ys = reverse xs
 </programlisting>
-
-</para>
-
-<para>
 The pattern <literal>(xs::[a])</literal> includes a type signature for <varname>xs</varname>.
 This brings the type variable <literal>a</literal> into scope; it scopes over
 all the patterns and right hand sides for this equation for <function>f</function>.
@@ -2696,8 +2698,6 @@ In particular, it is in scope at the type signature for <varname>y</varname>.
 </para>
 
 <para>
- Pattern type signatures are completely orthogonal to ordinary, separate
-type signatures.  The two can be used independently or together.
 At ordinary type signatures, such as that for <varname>ys</varname>, any type variables
 mentioned in the type signature <emphasis>that are not in scope</emphasis> are
 implicitly universally quantified.  (If there are no type variables in
@@ -2720,10 +2720,10 @@ So much for the basic idea.  Here are the details.
 </para>
 
 <sect3>
-<title>What a pattern type signature means</title>
+<title>What a scoped type variable means</title>
 <para>
-A type variable brought into scope by a pattern type signature is simply
-the name for a type.   The restriction they express is that all occurrences
+A lexically-scoped type variable is simply
+the name for a type.   The restriction it expresses is that all occurrences
 of the same name mean the same type.  For example:
 <programlisting>
   f :: [Int] -> Int -> Int
@@ -2893,7 +2893,33 @@ scope over the methods defined in the <literal>where</literal> part.  For exampl
 
 </sect3>
 
-<sect3>
+<sect3 id="decl-type-sigs">
+<title>Declaration type signatures</title>
+<para>A declaration type signature that has <emphasis>explicit</emphasis>
+quantification (using <literal>forall</literal>) brings into scope the
+explicitly-quantified
+type variables, in the definition of the named function(s).  For example:
+<programlisting>
+  f :: forall a. [a] -> [a]
+  f (x:xs) = xs ++ [ x :: a ]
+</programlisting>
+The "<literal>forall a</literal>" brings "<literal>a</literal>" into scope in
+the definition of "<literal>f</literal>".
+</para>
+<para>This only happens if the quantification in <literal>f</literal>'s type
+signature is explicit.  For example:
+<programlisting>
+  g :: [a] -> [a]
+  g (x:xs) = xs ++ [ x :: a ]
+</programlisting>
+This program will be rejected, because "<literal>a</literal>" does not scope
+over the definition of "<literal>f</literal>", so "<literal>x::a</literal>"
+means "<literal>x::forall a. a</literal>" by Haskell's usual implicit
+quantification rules.
+</para>
+</sect3>
+
+<sect3 id="pattern-type-sigs">
 <title>Where a pattern type signature can occur</title>
 
 <para>
@@ -3010,10 +3036,12 @@ in <literal>f4</literal>'s scope.
 </listitem>
 </itemizedlist>
 </para>
+<para>Pattern type signatures are completely orthogonal to ordinary, separate
+type signatures.  The two can be used independently or together.</para>
 
 </sect3>
 
-<sect3>
+<sect3 id="result-type-sigs">
 <title>Result type signatures</title>
 
 <para>