Three improvements to Template Haskell (fixes #3467)

[ghc-hetmet.git] / docs / users_guide / glasgow_exts.xml

diff --git a/docs/users_guide/glasgow_exts.xml b/docs/users_guide/glasgow_exts.xml
index 4e541a6..fb21918 100644 (file)
--- a/docs/users_guide/glasgow_exts.xml
+++ b/docs/users_guide/glasgow_exts.xml
@@ -3157,7 +3157,8 @@ All the extensions are enabled by the <option>-fglasgow-exts</option> flag.
 <sect3>
 <title>Multi-parameter type classes</title>
 <para>
-Multi-parameter type classes are permitted. For example:
+Multi-parameter type classes are permitted, with flag <option>-XMultiParamTypeClasses</option>. 
+For example:
 
 
 <programlisting>
@@ -3169,13 +3170,17 @@ Multi-parameter type classes are permitted. For example:
 </para>
 </sect3>
 
-<sect3>
+<sect3 id="superclass-rules">
 <title>The superclasses of a class declaration</title>
 
 <para>
-There are no restrictions on the context in a class declaration
-(which introduces superclasses), except that the class hierarchy must
-be acyclic.  So these class declarations are OK:
+In Haskell 98 the context of a class declaration (which introduces superclasses)
+must be simple; that is, each predicate must consist of a class applied to 
+type variables.  The flag <option>-XFlexibleContexts</option> 
+(<xref linkend="flexible-contexts"/>)
+lifts this restriction,
+so that the only restriction on the context in a class declaration is 
+that the class hierarchy must be acyclic.  So these class declarations are OK:
 
 
 <programlisting>
@@ -4723,7 +4728,11 @@ these type signatures are perfectly OK
   g :: Eq [a] => ...
   g :: Ord (T a ()) => ...
 </programlisting>
+The flag <option>-XFlexibleContexts</option> also lifts the corresponding
+restriction on class declarations (<xref linkend="superclass-rules"/>) and instance declarations
+(<xref linkend="instance-rules"/>).
 </para>
+
 <para>
 GHC imposes the following restrictions on the constraints in a type signature.
 Consider the type:
@@ -6056,12 +6065,11 @@ Wiki page</ulink>.
                    have type <literal>Q Exp</literal></para></listitem>
                    <listitem><para> an type; the spliced expression must
                    have type <literal>Q Typ</literal></para></listitem>
-                   <listitem><para> a list of top-level declarations; the spliced expression must have type <literal>Q [Dec]</literal></para></listitem>
+                   <listitem><para> a list of top-level declarations; the spliced expression 
+                    must have type <literal>Q [Dec]</literal></para></listitem>
                    </itemizedlist>
-               </para>
            Inside a splice you can can only call functions defined in imported modules,
-       not functions defined elsewhere in the same module.</listitem>
-
+       not functions defined elsewhere in the same module.</para></listitem>
 
              <listitem><para>
                  A expression quotation is written in Oxford brackets, thus:
@@ -6078,7 +6086,7 @@ Wiki page</ulink>.
                  A quasi-quotation can appear in either a pattern context or an
                  expression context and is also written in Oxford brackets:
                  <itemizedlist>
-                   <listitem><para> <literal>[:<replaceable>varid</replaceable>| ... |]</literal>,
+                   <listitem><para> <literal>[$<replaceable>varid</replaceable>| ... |]</literal>,
                         where the "..." is an arbitrary string; a full description of the
                        quasi-quotation facility is given in <xref linkend="th-quasiquotation"/>.</para></listitem>
                  </itemizedlist></para></listitem>
@@ -6099,6 +6107,25 @@ Wiki page</ulink>.
                 </para>
                </listitem>
 
+             <listitem><para> You may omit the <literal>$(...)</literal> in a top-level declaration splice. 
+              Simply writing an expression (rather than a declaration) implies a splice.  For example, you can write
+<programlisting>
+module Foo where
+import Bar
+
+f x = x
+
+$(deriveStuff 'f)   -- Uses the $(...) notation
+
+g y = y+1
+
+deriveStuff 'g      -- Omits the $(...)
+
+h z = z-1
+</programlisting>
+            This abbreviation makes top-level declaration slices quieter and less intimidating.
+           </para></listitem>
+
                  
        </itemizedlist>
 (Compared to the original paper, there are many differences of detail.