New syntax for GADT-style record declarations, and associated refactoring
[ghc-hetmet.git] / docs / users_guide / glasgow_exts.xml
index 6dfda6b..5d1b5cf 100644 (file)
@@ -38,243 +38,68 @@ documentation</ulink> describes all the libraries that come with GHC.
     <indexterm><primary>extensions</primary><secondary>options controlling</secondary>
     </indexterm>
 
-    <para>These flags control what variation of the language are
+    <para>The language option flags control what variation of the language are
     permitted.  Leaving out all of them gives you standard Haskell
     98.</para>
 
-    <para>NB. turning on an option that enables special syntax
-    <emphasis>might</emphasis> cause working Haskell 98 code to fail
-    to compile, perhaps because it uses a variable name which has
-    become a reserved word.  So, together with each option below, we
-    list the special syntax which is enabled by this option.  We use
-    notation and nonterminal names from the Haskell 98 lexical syntax
-    (see the Haskell 98 Report).  There are two classes of special
-    syntax:</para>
-
+    <para>Language options can be controlled in two ways:
     <itemizedlist>
-      <listitem>
-       <para>New reserved words and symbols: character sequences
-        which are no longer available for use as identifiers in the
-        program.</para>
-      </listitem>
-      <listitem>
-       <para>Other special syntax: sequences of characters that have
-       a different meaning when this particular option is turned
-       on.</para>
-      </listitem>
-    </itemizedlist>
-
-    <para>We are only listing syntax changes here that might affect
-    existing working programs (i.e. "stolen" syntax).  Many of these
-    extensions will also enable new context-free syntax, but in all
-    cases programs written to use the new syntax would not be
-    compilable without the option enabled.</para>
-
-    <variablelist>
-
-      <varlistentry>
-       <term>
-          <option>-fglasgow-exts</option>:
+      <listitem><para>Every language option can switched on by a command-line flag "<option>-X...</option>" 
+        (e.g. <option>-XTemplateHaskell</option>), and switched off by the flag "<option>-XNo...</option>"; 
+        (e.g. <option>-XNoTemplateHaskell</option>).</para></listitem>
+      <listitem><para>
+          Language options recognised by Cabal can also be enabled using the <literal>LANGUAGE</literal> pragma,
+          thus <literal>{-# LANGUAGE TemplateHaskell #-}</literal> (see <xref linkend="language-pragma"/>). </para>
+          </listitem>
+      </itemizedlist></para>
+
+    <para>The flag <option>-fglasgow-exts</option>
           <indexterm><primary><option>-fglasgow-exts</option></primary></indexterm>
-        </term>
-       <listitem>
-         <para>This simultaneously enables all of the extensions to
-          Haskell 98 described in <xref
-          linkend="ghc-language-features"/>, except where otherwise
-          noted. </para>
-
-         <para>New reserved words: <literal>forall</literal> (only in
-         types), <literal>mdo</literal>.</para>
-
-         <para>Other syntax stolen:
-             <replaceable>varid</replaceable>{<literal>&num;</literal>},
-             <replaceable>char</replaceable><literal>&num;</literal>,      
-             <replaceable>string</replaceable><literal>&num;</literal>,    
-             <replaceable>integer</replaceable><literal>&num;</literal>,    
-             <replaceable>float</replaceable><literal>&num;</literal>,    
-             <replaceable>float</replaceable><literal>&num;&num;</literal>,    
-             <literal>(&num;</literal>, <literal>&num;)</literal>,         
-             <literal>|)</literal>, <literal>{|</literal>.</para>
-       </listitem>
-      </varlistentry>
-
-      <varlistentry>
-       <term>
-          <option>-ffi</option> and <option>-fffi</option>:
-          <indexterm><primary><option>-ffi</option></primary></indexterm>
-          <indexterm><primary><option>-fffi</option></primary></indexterm>
-        </term>
-       <listitem>
-         <para>This option enables the language extension defined in the
-         Haskell 98 Foreign Function Interface Addendum.</para>
-
-         <para>New reserved words: <literal>foreign</literal>.</para>
-       </listitem>
-      </varlistentry>
-
-      <varlistentry>
-       <term>
-          <option>-fno-monomorphism-restriction</option>,<option>-fno-mono-pat-binds</option>:
-        </term>
-       <listitem>
-         <para> These two flags control how generalisation is done.
-           See <xref linkend="monomorphism"/>.
-          </para>
-       </listitem>
-      </varlistentry>
-
-      <varlistentry>
-       <term>
-          <option>-fextended-default-rules</option>:
-          <indexterm><primary><option>-fextended-default-rules</option></primary></indexterm>
-        </term>
-       <listitem>
-         <para> Use GHCi's extended default rules in a regular module (<xref linkend="extended-default-rules"/>).
-          Independent of the <option>-fglasgow-exts</option>
-          flag. </para>
-       </listitem>
-      </varlistentry>
+         is equivalent to enabling the following extensions: 
+          <option>-XPrintExplicitForalls</option>,
+          <option>-XForeignFunctionInterface</option>,
+          <option>-XUnliftedFFITypes</option>,
+          <option>-XGADTs</option>,
+          <option>-XImplicitParams</option>,
+          <option>-XScopedTypeVariables</option>,
+          <option>-XUnboxedTuples</option>,
+          <option>-XTypeSynonymInstances</option>,
+          <option>-XStandaloneDeriving</option>,
+          <option>-XDeriveDataTypeable</option>,
+          <option>-XFlexibleContexts</option>,
+          <option>-XFlexibleInstances</option>,
+          <option>-XConstrainedClassMethods</option>,
+          <option>-XMultiParamTypeClasses</option>,
+          <option>-XFunctionalDependencies</option>,
+          <option>-XMagicHash</option>,
+          <option>-XPolymorphicComponents</option>,
+          <option>-XExistentialQuantification</option>,
+          <option>-XUnicodeSyntax</option>,
+          <option>-XPostfixOperators</option>,
+          <option>-XPatternGuards</option>,
+          <option>-XLiberalTypeSynonyms</option>,
+          <option>-XRankNTypes</option>,
+          <option>-XImpredicativeTypes</option>,
+          <option>-XTypeOperators</option>,
+          <option>-XRecursiveDo</option>,
+          <option>-XParallelListComp</option>,
+          <option>-XEmptyDataDecls</option>,
+          <option>-XKindSignatures</option>,
+          <option>-XGeneralizedNewtypeDeriving</option>,
+          <option>-XTypeFamilies</option>.
+           Enabling these options is the <emphasis>only</emphasis> 
+           effect of <option>-fglasgow-exts</option>.
+          We are trying to move away from this portmanteau flag, 
+         and towards enabling features individually.</para>
 
-      <varlistentry>
-       <term>
-          <option>-fallow-overlapping-instances</option>
-          <indexterm><primary><option>-fallow-overlapping-instances</option></primary></indexterm>
-        </term>
-       <term>
-          <option>-fallow-undecidable-instances</option>
-          <indexterm><primary><option>-fallow-undecidable-instances</option></primary></indexterm>
-        </term>
-       <term>
-          <option>-fallow-incoherent-instances</option>
-          <indexterm><primary><option>-fallow-incoherent-instances</option></primary></indexterm>
-        </term>
-       <term>
-          <option>-fcontext-stack=N</option>
-          <indexterm><primary><option>-fcontext-stack</option></primary></indexterm>
-        </term>
-       <listitem>
-         <para> See <xref linkend="instance-decls"/>.  Only relevant
-          if you also use <option>-fglasgow-exts</option>.</para>
-       </listitem>
-      </varlistentry>
-
-      <varlistentry>
-       <term>
-          <option>-finline-phase</option>
-          <indexterm><primary><option>-finline-phase</option></primary></indexterm>
-        </term>
-       <listitem>
-         <para>See <xref linkend="rewrite-rules"/>.  Only relevant if
-          you also use <option>-fglasgow-exts</option>.</para>
-       </listitem>
-      </varlistentry>
-
-      <varlistentry>
-       <term>
-          <option>-farrows</option>
-          <indexterm><primary><option>-farrows</option></primary></indexterm>
-        </term>
-       <listitem>
-         <para>See <xref linkend="arrow-notation"/>.  Independent of
-          <option>-fglasgow-exts</option>.</para>
-
-         <para>New reserved words/symbols: <literal>rec</literal>,
-         <literal>proc</literal>, <literal>-&lt;</literal>,
-         <literal>&gt;-</literal>, <literal>-&lt;&lt;</literal>,
-         <literal>&gt;&gt;-</literal>.</para>
-
-         <para>Other syntax stolen: <literal>(|</literal>,
-         <literal>|)</literal>.</para>
-       </listitem>
-      </varlistentry>
-
-      <varlistentry>
-       <term>
-          <option>-fgenerics</option>
-          <indexterm><primary><option>-fgenerics</option></primary></indexterm>
-        </term>
-       <listitem>
-         <para>See <xref linkend="generic-classes"/>.  Independent of
-          <option>-fglasgow-exts</option>.</para>
-       </listitem>
-      </varlistentry>
-
-      <varlistentry>
-       <term><option>-fno-implicit-prelude</option></term>
-       <listitem>
-         <para><indexterm><primary>-fno-implicit-prelude
-          option</primary></indexterm> GHC normally imports
-          <filename>Prelude.hi</filename> files for you.  If you'd
-          rather it didn't, then give it a
-          <option>-fno-implicit-prelude</option> option.  The idea is
-          that you can then import a Prelude of your own.  (But don't
-          call it <literal>Prelude</literal>; the Haskell module
-          namespace is flat, and you must not conflict with any
-          Prelude module.)</para>
-
-         <para>Even though you have not imported the Prelude, most of
-          the built-in syntax still refers to the built-in Haskell
-          Prelude types and values, as specified by the Haskell
-          Report.  For example, the type <literal>[Int]</literal>
-          still means <literal>Prelude.[] Int</literal>; tuples
-          continue to refer to the standard Prelude tuples; the
-          translation for list comprehensions continues to use
-          <literal>Prelude.map</literal> etc.</para>
-
-         <para>However, <option>-fno-implicit-prelude</option> does
-         change the handling of certain built-in syntax: see <xref
-         linkend="rebindable-syntax"/>.</para>
-       </listitem>
-      </varlistentry>
-
-      <varlistentry>
-       <term><option>-fimplicit-params</option></term>
-       <listitem>
-         <para>Enables implicit parameters (see <xref
-         linkend="implicit-parameters"/>).  Currently also implied by 
-         <option>-fglasgow-exts</option>.</para>
-
-         <para>Syntax stolen:
-         <literal>?<replaceable>varid</replaceable></literal>,
-         <literal>%<replaceable>varid</replaceable></literal>.</para>
-       </listitem>
-      </varlistentry>
-
-      <varlistentry>
-       <term><option>-fscoped-type-variables</option></term>
-       <listitem>
-         <para>Enables lexically-scoped type variables (see <xref
-         linkend="scoped-type-variables"/>).  Implied by
-         <option>-fglasgow-exts</option>.</para>
-       </listitem>
-      </varlistentry>
-
-      <varlistentry>
-       <term><option>-fth</option></term>
-       <listitem>
-         <para>Enables Template Haskell (see <xref
-         linkend="template-haskell"/>).  This flag must
-         be given explicitly; it is no longer implied by
-         <option>-fglasgow-exts</option>.</para>
-
-         <para>Syntax stolen: <literal>[|</literal>,
-         <literal>[e|</literal>, <literal>[p|</literal>,
-         <literal>[d|</literal>, <literal>[t|</literal>,
-         <literal>$(</literal>,
-         <literal>$<replaceable>varid</replaceable></literal>.</para>
-       </listitem>
-      </varlistentry>
-
-    </variablelist>
   </sect1>
 
 <!-- UNBOXED TYPES AND PRIMITIVE OPERATIONS -->
-<!--    included from primitives.sgml  -->
-<!-- &primitives; -->
 <sect1 id="primitives">
   <title>Unboxed types and primitive operations</title>
 
-<para>GHC is built on a raft of primitive data types and operations.
+<para>GHC is built on a raft of primitive data types and operations;
+"primitive" in the sense that they cannot be defined in Haskell itself.
 While you really can use this stuff to write fast code,
   we generally find it a lot less painful, and more satisfying in the
   long run, to use higher-level language features and libraries.  With
@@ -282,28 +107,21 @@ While you really can use this stuff to write fast code,
   unboxed version in any case.  And if it isn't, we'd like to know
   about it.</para>
 
-<para>We do not currently have good, up-to-date documentation about the
-primitives, perhaps because they are mainly intended for internal use.
-There used to be a long section about them here in the User Guide, but it
-became out of date, and wrong information is worse than none.</para>
-
-<para>The Real Truth about what primitive types there are, and what operations
-work over those types, is held in the file
-<filename>fptools/ghc/compiler/prelude/primops.txt.pp</filename>.
-This file is used directly to generate GHC's primitive-operation definitions, so
-it is always correct!  It is also intended for processing into text.</para>
-
-<para> Indeed,
-the result of such processing is part of the description of the 
- <ulink
-      url="http://haskell.cs.yale.edu/ghc/docs/papers/core.ps.gz">External
-        Core language</ulink>.
-So that document is a good place to look for a type-set version.
-We would be very happy if someone wanted to volunteer to produce an SGML
-back end to the program that processes <filename>primops.txt</filename> so that
-we could include the results here in the User Guide.</para>
-
-<para>What follows here is a brief summary of some main points.</para>
+<para>All these primitive data types and operations are exported by the 
+library <literal>GHC.Prim</literal>, for which there is 
+<ulink url="../libraries/base/GHC.Prim.html">detailed online documentation</ulink>.
+(This documentation is generated from the file <filename>compiler/prelude/primops.txt.pp</filename>.)
+</para>
+<para>
+If you want to mention any of the primitive data types or operations in your
+program, you must first import <literal>GHC.Prim</literal> to bring them
+into scope.  Many of them have names ending in "&num;", and to mention such
+names you need the <option>-XMagicHash</option> extension (<xref linkend="magic-hash"/>).
+</para>
+
+<para>The primops make extensive use of <link linkend="glasgow-unboxed">unboxed types</link> 
+and <link linkend="unboxed-tuples">unboxed tuples</link>, which
+we briefly summarise here. </para>
   
 <sect2 id="glasgow-unboxed">
 <title>Unboxed types
@@ -336,8 +154,11 @@ know and love&mdash;usually one instruction.
 Primitive (unboxed) types cannot be defined in Haskell, and are
 therefore built into the language and compiler.  Primitive types are
 always unlifted; that is, a value of a primitive type cannot be
-bottom.  We use the convention that primitive types, values, and
-operations have a <literal>&num;</literal> suffix.
+bottom.  We use the convention (but it is only a convention) 
+that primitive types, values, and
+operations have a <literal>&num;</literal> suffix (see <xref linkend="magic-hash"/>).
+For some primitive types we have special syntax for literals, also
+described in the <link linkend="magic-hash">same section</link>.
 </para>
 
 <para>
@@ -375,6 +196,13 @@ worse, the unboxed value might be larger than a pointer
 (<literal>Double&num;</literal> for instance).
 </para>
 </listitem>
+<listitem><para> You cannot define a newtype whose representation type
+(the argument type of the data constructor) is an unboxed type.  Thus,
+this is illegal:
+<programlisting>
+  newtype A = MkA Int#
+</programlisting>
+</para></listitem>
 <listitem><para> You cannot bind a variable with an unboxed type
 in a <emphasis>top-level</emphasis> binding.
 </para></listitem>
@@ -382,22 +210,20 @@ in a <emphasis>top-level</emphasis> binding.
 in a <emphasis>recursive</emphasis> binding.
 </para></listitem>
 <listitem><para> You may bind unboxed variables in a (non-recursive,
-non-top-level) pattern binding, but any such variable causes the entire
-pattern-match
-to become strict.  For example:
+non-top-level) pattern binding, but you must make any such pattern-match
+strict.  For example, rather than:
 <programlisting>
   data Foo = Foo Int Int#
 
   f x = let (Foo a b, w) = ..rhs.. in ..body..
 </programlisting>
-Since <literal>b</literal> has type <literal>Int#</literal>, the entire pattern
-match
-is strict, and the program behaves as if you had written
+you must write:
 <programlisting>
   data Foo = Foo Int Int#
 
-  f x = case ..rhs.. of { (Foo a b, w) -> ..body.. }
+  f x = let !(Foo a b, w) = ..rhs.. in ..body..
 </programlisting>
+since <literal>b</literal> has type <literal>Int#</literal>.
 </para>
 </listitem>
 </itemizedlist>
@@ -507,8 +333,146 @@ Indeed, the bindings can even be recursive.
 <sect1 id="syntax-extns">
 <title>Syntactic extensions</title>
  
+    <sect2 id="unicode-syntax">
+      <title>Unicode syntax</title>
+      <para>The language
+      extension <option>-XUnicodeSyntax</option><indexterm><primary><option>-XUnicodeSyntax</option></primary></indexterm>
+      enables Unicode characters to be used to stand for certain ASCII
+      character sequences.  The following alternatives are provided:</para>
+
+      <informaltable>
+       <tgroup cols="2" align="left" colsep="1" rowsep="1">
+         <thead>
+           <row>
+             <entry>ASCII</entry>
+              <entry>Unicode alternative</entry>
+             <entry>Code point</entry>
+             <entry>Name</entry>
+           </row>
+         </thead>
+         <tbody>
+           <row>
+             <entry><literal>::</literal></entry>
+             <entry>::</entry> <!-- no special char, apparently -->
+              <entry>0x2237</entry>
+             <entry>PROPORTION</entry>
+           </row>
+          </tbody>
+         <tbody>
+           <row>
+             <entry><literal>=&gt;</literal></entry>
+             <entry>&rArr;</entry>
+             <entry>0x21D2</entry>
+              <entry>RIGHTWARDS DOUBLE ARROW</entry>
+           </row>
+          </tbody>
+         <tbody>
+           <row>
+             <entry><literal>forall</literal></entry>
+             <entry>&forall;</entry>
+             <entry>0x2200</entry>
+              <entry>FOR ALL</entry>
+           </row>
+          </tbody>
+         <tbody>
+           <row>
+             <entry><literal>-&gt;</literal></entry>
+             <entry>&rarr;</entry>
+             <entry>0x2192</entry>
+              <entry>RIGHTWARDS ARROW</entry>
+           </row>
+          </tbody>
+         <tbody>
+           <row>
+             <entry><literal>&lt;-</literal></entry>
+             <entry>&larr;</entry>
+             <entry>0x2190</entry>
+              <entry>LEFTWARDS ARROW</entry>
+           </row>
+          </tbody>
+         <tbody>
+           <row>
+             <entry>..</entry>
+             <entry>&hellip;</entry>
+             <entry>0x22EF</entry>
+             <entry>MIDLINE HORIZONTAL ELLIPSIS</entry>
+           </row>
+          </tbody>
+        </tgroup>
+      </informaltable>
+    </sect2>
+
+    <sect2 id="magic-hash">
+      <title>The magic hash</title>
+      <para>The language extension <option>-XMagicHash</option> allows "&num;" as a
+       postfix modifier to identifiers.  Thus, "x&num;" is a valid variable, and "T&num;" is
+       a valid type constructor or data constructor.</para>
+
+      <para>The hash sign does not change sematics at all.  We tend to use variable
+       names ending in "&num;" for unboxed values or types (e.g. <literal>Int&num;</literal>), 
+       but there is no requirement to do so; they are just plain ordinary variables.
+       Nor does the <option>-XMagicHash</option> extension bring anything into scope.
+       For example, to bring <literal>Int&num;</literal> into scope you must 
+       import <literal>GHC.Prim</literal> (see <xref linkend="primitives"/>); 
+       the <option>-XMagicHash</option> extension
+       then allows you to <emphasis>refer</emphasis> to the <literal>Int&num;</literal>
+       that is now in scope.</para>
+      <para> The <option>-XMagicHash</option> also enables some new forms of literals (see <xref linkend="glasgow-unboxed"/>):
+       <itemizedlist> 
+         <listitem><para> <literal>'x'&num;</literal> has type <literal>Char&num;</literal></para> </listitem>
+         <listitem><para> <literal>&quot;foo&quot;&num;</literal> has type <literal>Addr&num;</literal></para> </listitem>
+         <listitem><para> <literal>3&num;</literal> has type <literal>Int&num;</literal>. In general,
+         any Haskell 98 integer lexeme followed by a <literal>&num;</literal> is an <literal>Int&num;</literal> literal, e.g.
+            <literal>-0x3A&num;</literal> as well as <literal>32&num;</literal></para>.</listitem>
+         <listitem><para> <literal>3&num;&num;</literal> has type <literal>Word&num;</literal>. In general,
+         any non-negative Haskell 98 integer lexeme followed by <literal>&num;&num;</literal> 
+             is a <literal>Word&num;</literal>. </para> </listitem>
+         <listitem><para> <literal>3.2&num;</literal> has type <literal>Float&num;</literal>.</para> </listitem>
+         <listitem><para> <literal>3.2&num;&num;</literal> has type <literal>Double&num;</literal></para> </listitem>
+         </itemizedlist>
+      </para>
+   </sect2>
+
+    <sect2 id="new-qualified-operators">
+      <title>New qualified operator syntax</title>
+
+      <para>A new syntax for referencing qualified operators is
+        planned to be introduced by Haskell', and is enabled in GHC
+        with
+        the <option>-XNewQualifiedOperators</option><indexterm><primary><option>-XNewQualifiedOperators</option></primary></indexterm>
+        option.  In the new syntax, the prefix form of a qualified
+        operator is
+        written <literal><replaceable>module</replaceable>.(<replaceable>symbol</replaceable>)</literal>
+        (in Haskell 98 this would
+        be <literal>(<replaceable>module</replaceable>.<replaceable>symbol</replaceable>)</literal>),
+        and the infix form is
+        written <literal>`<replaceable>module</replaceable>.(<replaceable>symbol</replaceable>)`</literal>
+        (in Haskell 98 this would
+        be <literal>`<replaceable>module</replaceable>.<replaceable>symbol</replaceable>`</literal>.
+        For example:
+<programlisting>
+  add x y = Prelude.(+) x y
+  subtract y = (`Prelude.(-)` y)
+</programlisting>
+        The new form of qualified operators is intended to regularise
+        the syntax by eliminating odd cases
+        like <literal>Prelude..</literal>.  For example,
+        when <literal>NewQualifiedOperators</literal> is on, it is possible to
+        write the enumerated sequence <literal>[Monday..]</literal>
+        without spaces, whereas in Haskell 98 this would be a
+        reference to the operator &lsquo;<literal>.</literal>&lsquo;
+        from module <literal>Monday</literal>.</para>
+
+      <para>When <option>-XNewQualifiedOperators</option> is on, the old Haskell
+        98 syntax for qualified operators is not accepted, so this
+        option may cause existing Haskell 98 code to break.</para>
+
+    </sect2>
+        
+
     <!-- ====================== HIERARCHICAL MODULES =======================  -->
 
+
     <sect2 id="hierarchical-modules">
       <title>Hierarchical Modules</title>
 
@@ -544,14 +508,11 @@ import qualified Control.Monad.ST.Strict as ST
       linkend="search-path"/>.</para>
 
       <para>GHC comes with a large collection of libraries arranged
-      hierarchically; see the accompanying library documentation.
-      There is an ongoing project to create and maintain a stable set
-      of <quote>core</quote> libraries used by several Haskell
-      compilers, and the libraries that GHC comes with represent the
-      current status of that project.  For more details, see <ulink
-      url="http://www.haskell.org/~simonmar/libraries/libraries.html">Haskell
-      Libraries</ulink>.</para>
-
+      hierarchically; see the accompanying <ulink
+      url="../libraries/index.html">library
+      documentation</ulink>.  More libraries to install are available
+      from <ulink
+      url="http://hackage.haskell.org/packages/hackage.html">HackageDB</ulink>.</para>
     </sect2>
 
     <!-- ====================== PATTERN GUARDS =======================  -->
@@ -683,6 +644,202 @@ qualifier list has just one element, a boolean expression.
 </para>
 </sect2>
 
+    <!-- ===================== View patterns ===================  -->
+
+<sect2 id="view-patterns">
+<title>View patterns
+</title>
+
+<para>
+View patterns are enabled by the flag <literal>-XViewPatterns</literal>.
+More information and examples of view patterns can be found on the
+<ulink url="http://hackage.haskell.org/trac/ghc/wiki/ViewPatterns">Wiki
+page</ulink>.
+</para>
+
+<para>
+View patterns are somewhat like pattern guards that can be nested inside
+of other patterns.  They are a convenient way of pattern-matching
+against values of abstract types. For example, in a programming language
+implementation, we might represent the syntax of the types of the
+language as follows:
+
+<programlisting>
+type Typ
+data TypView = Unit
+             | Arrow Typ Typ
+
+view :: Type -> TypeView
+
+-- additional operations for constructing Typ's ...
+</programlisting>
+
+The representation of Typ is held abstract, permitting implementations
+to use a fancy representation (e.g., hash-consing to manage sharing).
+
+Without view patterns, using this signature a little inconvenient: 
+<programlisting>
+size :: Typ -> Integer
+size t = case view t of
+  Unit -> 1
+  Arrow t1 t2 -> size t1 + size t2
+</programlisting>
+
+It is necessary to iterate the case, rather than using an equational
+function definition. And the situation is even worse when the matching
+against <literal>t</literal> is buried deep inside another pattern.
+</para>
+
+<para>
+View patterns permit calling the view function inside the pattern and
+matching against the result: 
+<programlisting>
+size (view -> Unit) = 1
+size (view -> Arrow t1 t2) = size t1 + size t2
+</programlisting>
+
+That is, we add a new form of pattern, written
+<replaceable>expression</replaceable> <literal>-></literal>
+<replaceable>pattern</replaceable> that means "apply the expression to
+whatever we're trying to match against, and then match the result of
+that application against the pattern". The expression can be any Haskell
+expression of function type, and view patterns can be used wherever
+patterns are used.
+</para>
+
+<para>
+The semantics of a pattern <literal>(</literal>
+<replaceable>exp</replaceable> <literal>-></literal>
+<replaceable>pat</replaceable> <literal>)</literal> are as follows:
+
+<itemizedlist>
+
+<listitem> Scoping:
+
+<para>The variables bound by the view pattern are the variables bound by
+<replaceable>pat</replaceable>.
+</para>
+
+<para>
+Any variables in <replaceable>exp</replaceable> are bound occurrences,
+but variables bound "to the left" in a pattern are in scope.  This
+feature permits, for example, one argument to a function to be used in
+the view of another argument.  For example, the function
+<literal>clunky</literal> from <xref linkend="pattern-guards" /> can be
+written using view patterns as follows:
+
+<programlisting>
+clunky env (lookup env -> Just val1) (lookup env -> Just val2) = val1 + val2
+...other equations for clunky...
+</programlisting>
+</para>
+
+<para>
+More precisely, the scoping rules are: 
+<itemizedlist>
+<listitem>
+<para>
+In a single pattern, variables bound by patterns to the left of a view
+pattern expression are in scope. For example:
+<programlisting>
+example :: Maybe ((String -> Integer,Integer), String) -> Bool
+example Just ((f,_), f -> 4) = True
+</programlisting>
+
+Additionally, in function definitions, variables bound by matching earlier curried
+arguments may be used in view pattern expressions in later arguments:
+<programlisting>
+example :: (String -> Integer) -> String -> Bool
+example f (f -> 4) = True
+</programlisting>
+That is, the scoping is the same as it would be if the curried arguments
+were collected into a tuple.  
+</para>
+</listitem>
+
+<listitem>
+<para>
+In mutually recursive bindings, such as <literal>let</literal>,
+<literal>where</literal>, or the top level, view patterns in one
+declaration may not mention variables bound by other declarations.  That
+is, each declaration must be self-contained.  For example, the following
+program is not allowed:
+<programlisting>
+let {(x -> y) = e1 ;
+     (y -> x) = e2 } in x
+</programlisting>
+
+(We may lift this
+restriction in the future; the only cost is that type checking patterns
+would get a little more complicated.)  
+
+
+</para>
+</listitem>
+</itemizedlist>
+
+</para>
+</listitem>
+
+<listitem><para> Typing: If <replaceable>exp</replaceable> has type
+<replaceable>T1</replaceable> <literal>-></literal>
+<replaceable>T2</replaceable> and <replaceable>pat</replaceable> matches
+a <replaceable>T2</replaceable>, then the whole view pattern matches a
+<replaceable>T1</replaceable>.
+</para></listitem>
+
+<listitem><para> Matching: To the equations in Section 3.17.3 of the
+<ulink url="http://www.haskell.org/onlinereport/">Haskell 98
+Report</ulink>, add the following:
+<programlisting>
+case v of { (e -> p) -> e1 ; _ -> e2 } 
+ = 
+case (e v) of { p -> e1 ; _ -> e2 }
+</programlisting>
+That is, to match a variable <replaceable>v</replaceable> against a pattern
+<literal>(</literal> <replaceable>exp</replaceable>
+<literal>-></literal> <replaceable>pat</replaceable>
+<literal>)</literal>, evaluate <literal>(</literal>
+<replaceable>exp</replaceable> <replaceable> v</replaceable>
+<literal>)</literal> and match the result against
+<replaceable>pat</replaceable>.  
+</para></listitem>
+
+<listitem><para> Efficiency: When the same view function is applied in
+multiple branches of a function definition or a case expression (e.g.,
+in <literal>size</literal> above), GHC makes an attempt to collect these
+applications into a single nested case expression, so that the view
+function is only applied once.  Pattern compilation in GHC follows the
+matrix algorithm described in Chapter 4 of <ulink
+url="http://research.microsoft.com/~simonpj/Papers/slpj-book-1987/">The
+Implementation of Functional Programming Languages</ulink>.  When the
+top rows of the first column of a matrix are all view patterns with the
+"same" expression, these patterns are transformed into a single nested
+case.  This includes, for example, adjacent view patterns that line up
+in a tuple, as in
+<programlisting>
+f ((view -> A, p1), p2) = e1
+f ((view -> B, p3), p4) = e2
+</programlisting>
+</para>
+
+<para> The current notion of when two view pattern expressions are "the
+same" is very restricted: it is not even full syntactic equality.
+However, it does include variables, literals, applications, and tuples;
+e.g., two instances of <literal>view ("hi", "there")</literal> will be
+collected.  However, the current implementation does not compare up to
+alpha-equivalence, so two instances of <literal>(x, view x ->
+y)</literal> will not be coalesced.
+</para>
+
+</listitem>
+
+</itemizedlist>
+</para>
+
+</sect2>
+
     <!-- ===================== Recursive do-notation ===================  -->
 
 <sect2 id="mdo-notation">
@@ -690,9 +847,11 @@ qualifier list has just one element, a boolean expression.
 </title>
 
 <para> The recursive do-notation (also known as mdo-notation) is implemented as described in
-"A recursive do for Haskell",
-Levent Erkok, John Launchbury",
+<ulink url="http://citeseer.ist.psu.edu/erk02recursive.html">A recursive do for Haskell</ulink>,
+by Levent Erkok, John Launchbury,
 Haskell Workshop 2002, pages: 29-37. Pittsburgh, Pennsylvania. 
+This paper is essential reading for anyone making non-trivial use of mdo-notation,
+and we do not repeat it here.
 </para>
 <para>
 The do-notation of Haskell does not allow <emphasis>recursive bindings</emphasis>,
@@ -723,17 +882,24 @@ class Monad m => MonadFix m where
 </programlisting>
 <para>
 The function <literal>mfix</literal>
-dictates how the required recursion operation should be performed. If recursive bindings are required for a monad,
-then that monad must be declared an instance of the <literal>MonadFix</literal> class.
-For details, see the above mentioned reference.
+dictates how the required recursion operation should be performed.  For example, 
+<literal>justOnes</literal> desugars as follows:
+<programlisting>
+justOnes = mfix (\xs' -&gt; do { xs &lt;- Just (1:xs'); return xs }
+</programlisting>
+For full details of the way in which mdo is typechecked and desugared, see 
+the paper <ulink url="http://citeseer.ist.psu.edu/erk02recursive.html">A recursive do for Haskell</ulink>.
+In particular, GHC implements the segmentation technique described in Section 3.2 of the paper.
 </para>
 <para>
+If recursive bindings are required for a monad,
+then that monad must be declared an instance of the <literal>MonadFix</literal> class.
 The following instances of <literal>MonadFix</literal> are automatically provided: List, Maybe, IO. 
 Furthermore, the Control.Monad.ST and Control.Monad.ST.Lazy modules provide the instances of the MonadFix class 
 for Haskell's internal state monad (strict and lazy, respectively).
 </para>
 <para>
-There are three important points in using the recursive-do notation:
+Here are some important points in using the recursive-do notation:
 <itemizedlist>
 <listitem><para>
 The recursive version of the do-notation uses the keyword <literal>mdo</literal> (rather
@@ -741,21 +907,23 @@ than <literal>do</literal>).
 </para></listitem>
 
 <listitem><para>
-You should <literal>import Control.Monad.Fix</literal>.
-(Note: Strictly speaking, this import is required only when you need to refer to the name
-<literal>MonadFix</literal> in your program, but the import is always safe, and the programmers
-are encouraged to always import this module when using the mdo-notation.)
+It is enabled with the flag <literal>-XRecursiveDo</literal>, which is in turn implied by
+<literal>-fglasgow-exts</literal>.
 </para></listitem>
 
 <listitem><para>
-As with other extensions, ghc should be given the flag <literal>-fglasgow-exts</literal>
+Unlike ordinary do-notation, but like <literal>let</literal> and <literal>where</literal> bindings,
+name shadowing is not allowed; that is, all the names bound in a single <literal>mdo</literal> must
+be distinct (Section 3.3 of the paper).
 </para></listitem>
-</itemizedlist>
-</para>
 
-<para>
-The web page: <ulink url="http://www.cse.ogi.edu/PacSoft/projects/rmb">http://www.cse.ogi.edu/PacSoft/projects/rmb</ulink>
-contains up to date information on recursive monadic bindings.
+<listitem><para>
+Variables bound by a <literal>let</literal> statement in an <literal>mdo</literal>
+are monomorphic in the <literal>mdo</literal> (Section 3.1 of the paper).  However
+GHC breaks the <literal>mdo</literal> into segments to enhance polymorphism,
+and improve termination (Section 3.2 of the paper).
+</para></listitem>
+</itemizedlist>
 </para>
 
 <para>
@@ -819,24 +987,193 @@ This name is not supported by GHC.
     branches.</para>
 
   </sect2>
+  
+  <!-- ===================== TRANSFORM LIST COMPREHENSIONS ===================  -->
 
-<sect2 id="rebindable-syntax">
-<title>Rebindable syntax</title>
+  <sect2 id="generalised-list-comprehensions">
+    <title>Generalised (SQL-Like) List Comprehensions</title>
+    <indexterm><primary>list comprehensions</primary><secondary>generalised</secondary>
+    </indexterm>
+    <indexterm><primary>extended list comprehensions</primary>
+    </indexterm>
+    <indexterm><primary>group</primary></indexterm>
+    <indexterm><primary>sql</primary></indexterm>
+
+
+    <para>Generalised list comprehensions are a further enhancement to the
+    list comprehension syntatic sugar to allow operations such as sorting
+    and grouping which are familiar from SQL.   They are fully described in the
+       paper <ulink url="http://research.microsoft.com/~simonpj/papers/list-comp">
+         Comprehensive comprehensions: comprehensions with "order by" and "group by"</ulink>,
+    except that the syntax we use differs slightly from the paper.</para>
+<para>The extension is enabled with the flag <option>-XTransformListComp</option>.</para>
+<para>Here is an example: 
+<programlisting>
+employees = [ ("Simon", "MS", 80)
+, ("Erik", "MS", 100)
+, ("Phil", "Ed", 40)
+, ("Gordon", "Ed", 45)
+, ("Paul", "Yale", 60)]
+
+output = [ (the dept, sum salary)
+| (name, dept, salary) &lt;- employees
+, then group by dept
+, then sortWith by (sum salary)
+, then take 5 ]
+</programlisting>
+In this example, the list <literal>output</literal> would take on 
+    the value:
+    
+<programlisting>
+[("Yale", 60), ("Ed", 85), ("MS", 180)]
+</programlisting>
+</para>
+<para>There are three new keywords: <literal>group</literal>, <literal>by</literal>, and <literal>using</literal>.
+(The function <literal>sortWith</literal> is not a keyword; it is an ordinary
+function that is exported by <literal>GHC.Exts</literal>.)</para>
+
+<para>There are five new forms of comprehension qualifier,
+all introduced by the (existing) keyword <literal>then</literal>:
+    <itemizedlist>
+    <listitem>
+    
+<programlisting>
+then f
+</programlisting>
 
+    This statement requires that <literal>f</literal> have the type <literal>
+    forall a. [a] -> [a]</literal>. You can see an example of it's use in the
+    motivating example, as this form is used to apply <literal>take 5</literal>.
+    
+    </listitem>
+    
+    
+    <listitem>
+<para>
+<programlisting>
+then f by e
+</programlisting>
+
+    This form is similar to the previous one, but allows you to create a function
+    which will be passed as the first argument to f. As a consequence f must have 
+    the type <literal>forall a. (a -> t) -> [a] -> [a]</literal>. As you can see
+    from the type, this function lets f &quot;project out&quot; some information 
+    from the elements of the list it is transforming.</para>
+
+    <para>An example is shown in the opening example, where <literal>sortWith</literal> 
+    is supplied with a function that lets it find out the <literal>sum salary</literal> 
+    for any item in the list comprehension it transforms.</para>
+
+    </listitem>
+
+
+    <listitem>
+
+<programlisting>
+then group by e using f
+</programlisting>
+
+    <para>This is the most general of the grouping-type statements. In this form,
+    f is required to have type <literal>forall a. (a -> t) -> [a] -> [[a]]</literal>.
+    As with the <literal>then f by e</literal> case above, the first argument
+    is a function supplied to f by the compiler which lets it compute e on every
+    element of the list being transformed. However, unlike the non-grouping case,
+    f additionally partitions the list into a number of sublists: this means that
+    at every point after this statement, binders occurring before it in the comprehension
+    refer to <emphasis>lists</emphasis> of possible values, not single values. To help understand
+    this, let's look at an example:</para>
+    
+<programlisting>
+-- This works similarly to groupWith in GHC.Exts, but doesn't sort its input first
+groupRuns :: Eq b => (a -> b) -> [a] -> [[a]]
+groupRuns f = groupBy (\x y -> f x == f y)
+
+output = [ (the x, y)
+| x &lt;- ([1..3] ++ [1..2])
+, y &lt;- [4..6]
+, then group by x using groupRuns ]
+</programlisting>
 
-      <para>GHC allows most kinds of built-in syntax to be rebound by
-      the user, to facilitate replacing the <literal>Prelude</literal>
-      with a home-grown version, for example.</para>
+    <para>This results in the variable <literal>output</literal> taking on the value below:</para>
 
-            <para>You may want to define your own numeric class
+<programlisting>
+[(1, [4, 5, 6]), (2, [4, 5, 6]), (3, [4, 5, 6]), (1, [4, 5, 6]), (2, [4, 5, 6])]
+</programlisting>
+
+    <para>Note that we have used the <literal>the</literal> function to change the type 
+    of x from a list to its original numeric type. The variable y, in contrast, is left 
+    unchanged from the list form introduced by the grouping.</para>
+
+    </listitem>
+
+    <listitem>
+
+<programlisting>
+then group by e
+</programlisting>
+
+    <para>This form of grouping is essentially the same as the one described above. However,
+    since no function to use for the grouping has been supplied it will fall back on the
+    <literal>groupWith</literal> function defined in 
+    <ulink url="../libraries/base/GHC-Exts.html"><literal>GHC.Exts</literal></ulink>. This
+    is the form of the group statement that we made use of in the opening example.</para>
+
+    </listitem>
+    
+    
+    <listitem>
+
+<programlisting>
+then group using f
+</programlisting>
+
+    <para>With this form of the group statement, f is required to simply have the type
+    <literal>forall a. [a] -> [[a]]</literal>, which will be used to group up the
+    comprehension so far directly. An example of this form is as follows:</para>
+    
+<programlisting>
+output = [ x
+| y &lt;- [1..5]
+, x &lt;- "hello"
+, then group using inits]
+</programlisting>
+
+    <para>This will yield a list containing every prefix of the word "hello" written out 5 times:</para>
+
+<programlisting>
+["","h","he","hel","hell","hello","helloh","hellohe","hellohel","hellohell","hellohello","hellohelloh",...]
+</programlisting>
+
+    </listitem>
+</itemizedlist>
+</para>
+  </sect2>
+
+   <!-- ===================== REBINDABLE SYNTAX ===================  -->
+
+<sect2 id="rebindable-syntax">
+<title>Rebindable syntax and the implicit Prelude import</title>
+
+ <para><indexterm><primary>-XNoImplicitPrelude
+ option</primary></indexterm> GHC normally imports
+ <filename>Prelude.hi</filename> files for you.  If you'd
+ rather it didn't, then give it a
+ <option>-XNoImplicitPrelude</option> option.  The idea is
+ that you can then import a Prelude of your own.  (But don't
+ call it <literal>Prelude</literal>; the Haskell module
+ namespace is flat, and you must not conflict with any
+ Prelude module.)</para>
+
+            <para>Suppose you are importing a Prelude of your own
+             in order to define your own numeric class
             hierarchy.  It completely defeats that purpose if the
             literal "1" means "<literal>Prelude.fromInteger
             1</literal>", which is what the Haskell Report specifies.
-            So the <option>-fno-implicit-prelude</option> flag causes
+            So the <option>-XNoImplicitPrelude</option> 
+             flag <emphasis>also</emphasis> causes
             the following pieces of built-in syntax to refer to
             <emphasis>whatever is in scope</emphasis>, not the Prelude
             versions:
-
            <itemizedlist>
              <listitem>
                <para>An integer literal <literal>368</literal> means
@@ -885,7 +1222,7 @@ This name is not supported by GHC.
              </para></listitem>
            </itemizedlist>
 In all cases (apart from arrow notation), the static semantics should be that of the desugared form,
-even if that is a little unexpected. For emample, the 
+even if that is a little unexpected. For example, the 
 static semantics of the literal <literal>368</literal>
 is exactly that of <literal>fromInteger (368::Integer)</literal>; it's fine for
 <literal>fromInteger</literal> to have any of the types:
@@ -908,33 +1245,399 @@ fromInteger :: Integer -> Bool -> Bool
 <title>Postfix operators</title>
 
 <para>
-GHC allows a small extension to the syntax of left operator sections, which
-allows you to define postfix operators.  The extension is this:  the left section
+  The <option>-XPostfixOperators</option> flag enables a small
+extension to the syntax of left operator sections, which allows you to
+define postfix operators.  The extension is this: the left section
 <programlisting>
   (e !)
-</programlisting> 
+</programlisting>
 is equivalent (from the point of view of both type checking and execution) to the expression
 <programlisting>
   ((!) e)
-</programlisting> 
+</programlisting>
 (for any expression <literal>e</literal> and operator <literal>(!)</literal>.
 The strict Haskell 98 interpretation is that the section is equivalent to
 <programlisting>
   (\y -> (!) e y)
-</programlisting> 
+</programlisting>
 That is, the operator must be a function of two arguments.  GHC allows it to
 take only one argument, and that in turn allows you to write the function
 postfix.
 </para>
-<para>Since this extension goes beyond Haskell 98, it should really be enabled
-by a flag; but in fact it is enabled all the time.  (No Haskell 98 programs
-change their behaviour, of course.)
-</para>
 <para>The extension does not extend to the left-hand side of function
 definitions; you must define such a function in prefix form.</para>
 
 </sect2>
 
+<sect2 id="disambiguate-fields">
+<title>Record field disambiguation</title>
+<para>
+In record construction and record pattern matching
+it is entirely unambiguous which field is referred to, even if there are two different
+data types in scope with a common field name.  For example:
+<programlisting>
+module M where
+  data S = MkS { x :: Int, y :: Bool }
+
+module Foo where
+  import M
+
+  data T = MkT { x :: Int }
+  
+  ok1 (MkS { x = n }) = n+1   -- Unambiguous
+
+  ok2 n = MkT { x = n+1 }     -- Unambiguous
+
+  bad1 k = k { x = 3 }  -- Ambiguous
+  bad2 k = x k          -- Ambiguous
+</programlisting>
+Even though there are two <literal>x</literal>'s in scope,
+it is clear that the <literal>x</literal> in the pattern in the
+definition of <literal>ok1</literal> can only mean the field
+<literal>x</literal> from type <literal>S</literal>. Similarly for
+the function <literal>ok2</literal>.  However, in the record update
+in <literal>bad1</literal> and the record selection in <literal>bad2</literal>
+it is not clear which of the two types is intended.
+</para>
+<para>
+Haskell 98 regards all four as ambiguous, but with the
+<option>-XDisambiguateRecordFields</option> flag, GHC will accept
+the former two.  The rules are precisely the same as those for instance
+declarations in Haskell 98, where the method names on the left-hand side 
+of the method bindings in an instance declaration refer unambiguously
+to the method of that class (provided they are in scope at all), even
+if there are other variables in scope with the same name.
+This reduces the clutter of qualified names when you import two
+records from different modules that use the same field name.
+</para>
+</sect2>
+
+    <!-- ===================== Record puns ===================  -->
+
+<sect2 id="record-puns">
+<title>Record puns
+</title>
+
+<para>
+Record puns are enabled by the flag <literal>-XNamedFieldPuns</literal>.
+</para>
+
+<para>
+When using records, it is common to write a pattern that binds a
+variable with the same name as a record field, such as:
+
+<programlisting>
+data C = C {a :: Int}
+f (C {a = a}) = a
+</programlisting>
+</para>
+
+<para>
+Record punning permits the variable name to be elided, so one can simply
+write
+
+<programlisting>
+f (C {a}) = a
+</programlisting>
+
+to mean the same pattern as above.  That is, in a record pattern, the
+pattern <literal>a</literal> expands into the pattern <literal>a =
+a</literal> for the same name <literal>a</literal>.  
+</para>
+
+<para>
+Note that puns and other patterns can be mixed in the same record:
+<programlisting>
+data C = C {a :: Int, b :: Int}
+f (C {a, b = 4}) = a
+</programlisting>
+and that puns can be used wherever record patterns occur (e.g. in
+<literal>let</literal> bindings or at the top-level).  
+</para>
+
+<para>
+Record punning can also be used in an expression, writing, for example,
+<programlisting>
+let a = 1 in C {a}
+</programlisting>
+instead of 
+<programlisting>
+let a = 1 in C {a = a}
+</programlisting>
+
+Note that this expansion is purely syntactic, so the record pun
+expression refers to the nearest enclosing variable that is spelled the
+same as the field name.
+</para>
+
+</sect2>
+
+    <!-- ===================== Record wildcards ===================  -->
+
+<sect2 id="record-wildcards">
+<title>Record wildcards
+</title>
+
+<para>
+Record wildcards are enabled by the flag <literal>-XRecordWildCards</literal>.
+</para>
+
+<para>
+For records with many fields, it can be tiresome to write out each field
+individually in a record pattern, as in
+<programlisting>
+data C = C {a :: Int, b :: Int, c :: Int, d :: Int}
+f (C {a = 1, b = b, c = c, d = d}) = b + c + d
+</programlisting>
+</para>
+
+<para>
+Record wildcard syntax permits a (<literal>..</literal>) in a record
+pattern, where each elided field <literal>f</literal> is replaced by the
+pattern <literal>f = f</literal>.  For example, the above pattern can be
+written as
+<programlisting>
+f (C {a = 1, ..}) = b + c + d
+</programlisting>
+</para>
+
+<para>
+Note that wildcards can be mixed with other patterns, including puns
+(<xref linkend="record-puns"/>); for example, in a pattern <literal>C {a
+= 1, b, ..})</literal>.  Additionally, record wildcards can be used
+wherever record patterns occur, including in <literal>let</literal>
+bindings and at the top-level.  For example, the top-level binding
+<programlisting>
+C {a = 1, ..} = e
+</programlisting>
+defines <literal>b</literal>, <literal>c</literal>, and
+<literal>d</literal>.
+</para>
+
+<para>
+Record wildcards can also be used in expressions, writing, for example,
+
+<programlisting>
+let {a = 1; b = 2; c = 3; d = 4} in C {..}
+</programlisting>
+
+in place of
+
+<programlisting>
+let {a = 1; b = 2; c = 3; d = 4} in C {a=a, b=b, c=c, d=d}
+</programlisting>
+
+Note that this expansion is purely syntactic, so the record wildcard
+expression refers to the nearest enclosing variables that are spelled
+the same as the omitted field names.
+</para>
+
+</sect2>
+
+    <!-- ===================== Local fixity declarations ===================  -->
+
+<sect2 id="local-fixity-declarations">
+<title>Local Fixity Declarations
+</title>
+
+<para>A careful reading of the Haskell 98 Report reveals that fixity
+declarations (<literal>infix</literal>, <literal>infixl</literal>, and
+<literal>infixr</literal>) are permitted to appear inside local bindings
+such those introduced by <literal>let</literal> and
+<literal>where</literal>.  However, the Haskell Report does not specify
+the semantics of such bindings very precisely.
+</para>
+
+<para>In GHC, a fixity declaration may accompany a local binding:
+<programlisting>
+let f = ...
+    infixr 3 `f`
+in 
+    ...
+</programlisting>
+and the fixity declaration applies wherever the binding is in scope.
+For example, in a <literal>let</literal>, it applies in the right-hand
+sides of other <literal>let</literal>-bindings and the body of the
+<literal>let</literal>C. Or, in recursive <literal>do</literal>
+expressions (<xref linkend="mdo-notation"/>), the local fixity
+declarations of a <literal>let</literal> statement scope over other
+statements in the group, just as the bound name does.
+</para>
+
+<para>
+Moreover, a local fixity declaration *must* accompany a local binding of
+that name: it is not possible to revise the fixity of name bound
+elsewhere, as in
+<programlisting>
+let infixr 9 $ in ...
+</programlisting>
+
+Because local fixity declarations are technically Haskell 98, no flag is
+necessary to enable them.
+</para>
+</sect2>
+
+<sect2 id="package-imports">
+  <title>Package-qualified imports</title>
+
+  <para>With the <option>-XPackageImports</option> flag, GHC allows
+  import declarations to be qualified by the package name that the
+    module is intended to be imported from.  For example:</para>
+
+<programlisting>
+import "network" Network.Socket
+</programlisting>
+  
+  <para>would import the module <literal>Network.Socket</literal> from
+    the package <literal>network</literal> (any version).  This may
+    be used to disambiguate an import when the same module is
+    available from multiple packages, or is present in both the
+    current package being built and an external package.</para>
+
+  <para>Note: you probably don't need to use this feature, it was
+    added mainly so that we can build backwards-compatible versions of
+    packages when APIs change.  It can lead to fragile dependencies in
+    the common case: modules occasionally move from one package to
+    another, rendering any package-qualified imports broken.</para>
+</sect2>
+
+<sect2 id="syntax-stolen">
+<title>Summary of stolen syntax</title>
+
+    <para>Turning on an option that enables special syntax
+    <emphasis>might</emphasis> cause working Haskell 98 code to fail
+    to compile, perhaps because it uses a variable name which has
+    become a reserved word.  This section lists the syntax that is
+    "stolen" by language extensions.
+     We use
+    notation and nonterminal names from the Haskell 98 lexical syntax
+    (see the Haskell 98 Report).  
+    We only list syntax changes here that might affect
+    existing working programs (i.e. "stolen" syntax).  Many of these
+    extensions will also enable new context-free syntax, but in all
+    cases programs written to use the new syntax would not be
+    compilable without the option enabled.</para>
+
+<para>There are two classes of special
+    syntax:
+
+    <itemizedlist>
+      <listitem>
+       <para>New reserved words and symbols: character sequences
+        which are no longer available for use as identifiers in the
+        program.</para>
+      </listitem>
+      <listitem>
+       <para>Other special syntax: sequences of characters that have
+       a different meaning when this particular option is turned
+       on.</para>
+      </listitem>
+    </itemizedlist>
+    
+The following syntax is stolen:
+
+    <variablelist>
+      <varlistentry>
+       <term>
+          <literal>forall</literal>
+          <indexterm><primary><literal>forall</literal></primary></indexterm>
+       </term>
+       <listitem><para>
+       Stolen (in types) by: <option>-XScopedTypeVariables</option>,
+           <option>-XLiberalTypeSynonyms</option>,
+           <option>-XRank2Types</option>,
+           <option>-XRankNTypes</option>,
+           <option>-XPolymorphicComponents</option>,
+           <option>-XExistentialQuantification</option>
+         </para></listitem>
+      </varlistentry>
+
+      <varlistentry>
+       <term>
+          <literal>mdo</literal>
+          <indexterm><primary><literal>mdo</literal></primary></indexterm>
+       </term>
+       <listitem><para>
+       Stolen by: <option>-XRecursiveDo</option>,
+         </para></listitem>
+      </varlistentry>
+
+      <varlistentry>
+       <term>
+          <literal>foreign</literal>
+          <indexterm><primary><literal>foreign</literal></primary></indexterm>
+       </term>
+       <listitem><para>
+       Stolen by: <option>-XForeignFunctionInterface</option>,
+         </para></listitem>
+      </varlistentry>
+
+      <varlistentry>
+       <term>
+          <literal>rec</literal>,
+         <literal>proc</literal>, <literal>-&lt;</literal>,
+         <literal>&gt;-</literal>, <literal>-&lt;&lt;</literal>,
+         <literal>&gt;&gt;-</literal>, and <literal>(|</literal>,
+         <literal>|)</literal> brackets
+          <indexterm><primary><literal>proc</literal></primary></indexterm>
+       </term>
+       <listitem><para>
+       Stolen by: <option>-XArrows</option>,
+         </para></listitem>
+      </varlistentry>
+
+      <varlistentry>
+       <term>
+         <literal>?<replaceable>varid</replaceable></literal>,
+         <literal>%<replaceable>varid</replaceable></literal>
+          <indexterm><primary>implicit parameters</primary></indexterm>
+       </term>
+       <listitem><para>
+       Stolen by: <option>-XImplicitParams</option>,
+         </para></listitem>
+      </varlistentry>
+
+      <varlistentry>
+       <term>
+         <literal>[|</literal>,
+         <literal>[e|</literal>, <literal>[p|</literal>,
+         <literal>[d|</literal>, <literal>[t|</literal>,
+         <literal>$(</literal>,
+         <literal>$<replaceable>varid</replaceable></literal>
+          <indexterm><primary>Template Haskell</primary></indexterm>
+       </term>
+       <listitem><para>
+       Stolen by: <option>-XTemplateHaskell</option>,
+         </para></listitem>
+      </varlistentry>
+
+      <varlistentry>
+       <term>
+         <literal>[:<replaceable>varid</replaceable>|</literal>
+          <indexterm><primary>quasi-quotation</primary></indexterm>
+       </term>
+       <listitem><para>
+       Stolen by: <option>-XQuasiQuotes</option>,
+         </para></listitem>
+      </varlistentry>
+
+      <varlistentry>
+       <term>
+             <replaceable>varid</replaceable>{<literal>&num;</literal>},
+             <replaceable>char</replaceable><literal>&num;</literal>,      
+             <replaceable>string</replaceable><literal>&num;</literal>,    
+             <replaceable>integer</replaceable><literal>&num;</literal>,    
+             <replaceable>float</replaceable><literal>&num;</literal>,    
+             <replaceable>float</replaceable><literal>&num;&num;</literal>,    
+             <literal>(&num;</literal>, <literal>&num;)</literal>,         
+       </term>
+       <listitem><para>
+       Stolen by: <option>-XMagicHash</option>,
+         </para></listitem>
+      </varlistentry>
+    </variablelist>
+</para>
+</sect2>
 </sect1>
 
 
@@ -956,7 +1659,7 @@ a data type with no constructors.  For example:</para>
 <para>Syntactically, the declaration lacks the "= constrs" part.  The 
 type can be parameterised over types of any kind, but if the kind is
 not <literal>*</literal> then an explicit kind annotation must be used
-(see <xref linkend="sec-kinding"/>).</para>
+(see <xref linkend="kinding"/>).</para>
 
 <para>Such data types have only one value, namely bottom.
 Nevertheless, they can be useful when defining "phantom types".</para>
@@ -1035,9 +1738,12 @@ to be written infix, very much like expressions.  More specifically:
 <title>Liberalised type synonyms</title>
 
 <para>
-Type synonyms are like macros at the type level, and
+Type synonyms are like macros at the type level, but Haskell 98 imposes many rules
+on individual synonym declarations.
+With the <option>-XLiberalTypeSynonyms</option> extension,
 GHC does validity checking on types <emphasis>only after expanding type synonyms</emphasis>.
-That means that GHC can be very much more liberal about type synonyms than Haskell 98:
+That means that GHC can be very much more liberal about type synonyms than Haskell 98. 
+
 <itemizedlist>
 <listitem> <para>You can write a <literal>forall</literal> (including overloading)
 in a type synonym, thus:
@@ -1054,7 +1760,8 @@ in a type synonym, thus:
 </listitem>
 
 <listitem><para>
-You can write an unboxed tuple in a type synonym:
+If you also use <option>-XUnboxedTuples</option>, 
+you can write an unboxed tuple in a type synonym:
 <programlisting>
   type Pr = (# Int, Int #)
 
@@ -1212,13 +1919,13 @@ apply <function>fn</function> to <literal>val</literal> to get a boolean.  For e
 </para>
 
 <para>
-What this allows us to do is to package heterogenous values
+What this allows us to do is to package heterogeneous values
 together with a bunch of functions that manipulate them, and then treat
 that collection of packages in a uniform manner.  You can express
 quite a bit of object-oriented-like programming this way.
 </para>
 
-<sect4 id="existential">
+<sect3 id="existential">
 <title>Why existential?
 </title>
 
@@ -1241,10 +1948,10 @@ But Haskell programmers can safely think of the ordinary
 adding a new existential quantification construct.
 </para>
 
-</sect4>
+</sect3>
 
-<sect4>
-<title>Type classes</title>
+<sect3 id="existential-with-context">
+<title>Existentials and type classes</title>
 
 <para>
 An easy extension is to allow
@@ -1298,14 +2005,9 @@ dictionaries for <literal>Eq</literal> and <literal>Show</literal> respectively,
 extract it on pattern matching.
 </para>
 
-<para>
-Notice the way that the syntax fits smoothly with that used for
-universal quantification earlier.
-</para>
-
-</sect4>
+</sect3>
 
-<sect4 id="existential-records">
+<sect3 id="existential-records">
 <title>Record Constructors</title>
 
 <para>
@@ -1322,7 +2024,7 @@ data Counter a = forall self. NewCounter
 Here <literal>tag</literal> is a public field, with a well-typed selector
 function <literal>tag :: Counter a -> a</literal>.  The <literal>self</literal>
 type is hidden from the outside; any attempt to apply <literal>_this</literal>,
-<literal>_inc</literal> or <literal>_output</literal> as functions will raise a
+<literal>_inc</literal> or <literal>_display</literal> as functions will raise a
 compile-time error.  In other words, <emphasis>GHC defines a record selector function
 only for fields whose type does not mention the existentially-quantified variables</emphasis>.
 (This example used an underscore in the fields for which record selectors
@@ -1357,21 +2059,34 @@ main = do
     display (inc (inc counterB))   -- prints "##"
 </programlisting>
 
-At the moment, record update syntax is only supported for Haskell 98 data types,
-so the following function does <emphasis>not</emphasis> work:
-
+Record update syntax is supported for existentials (and GADTs):
 <programlisting>
--- This is invalid; use explicit NewCounter instead for now
 setTag :: Counter a -> a -> Counter a
 setTag obj t = obj{ tag = t }
 </programlisting>
+The rule for record update is this: <emphasis>
+the types of the updated fields may
+mention only the universally-quantified type variables
+of the data constructor.  For GADTs, the field may mention only types
+that appear as a simple type-variable argument in the constructor's result
+type</emphasis>.  For example:
+<programlisting>
+data T a b where { T1 { f1::a, f2::b, f3::(b,c) } :: T a b } -- c is existential
+upd1 t x = t { f1=x }   -- OK:   upd1 :: T a b -> a' -> T a' b
+upd2 t x = t { f3=x }   -- BAD   (f3's type mentions c, which is
+                        --        existentially quantified)
 
+data G a b where { G1 { g1::a, g2::c } :: G a [c] }
+upd3 g x = g { g1=x }   -- OK:   upd3 :: G a b -> c -> G c b
+upd4 g x = g { g2=x }   -- BAD (f2's type mentions c, which is not a simple
+                        --      type-variable argument in G1's result type)
+</programlisting>
 </para>
 
-</sect4>
+</sect3>
 
 
-<sect4>
+<sect3>
 <title>Restrictions</title>
 
 <para>
@@ -1522,7 +2237,7 @@ declarations.  Define your own instances!
 
 </para>
 
-</sect4>
+</sect3>
 </sect2>
 
 <!-- ====================== Generalised algebraic data types =======================  -->
@@ -1575,19 +2290,8 @@ In the example, the equality dictionary is used to satisfy the equality constrai
 generated by the call to <literal>elem</literal>, so that the type of
 <literal>insert</literal> itself has no <literal>Eq</literal> constraint.
 </para>
-<para>This behaviour contrasts with Haskell 98's peculiar treament of 
-contexts on a data type declaration (Section 4.2.1 of the Haskell 98 Report).
-In Haskell 98 the defintion
-<programlisting>
-  data Eq a => Set' a = MkSet' [a]
-</programlisting>
-gives <literal>MkSet'</literal> the same type as <literal>MkSet</literal> above.  But instead of 
-<emphasis>making available</emphasis> an <literal>(Eq a)</literal> constraint, pattern-matching
-on <literal>MkSet'</literal> <emphasis>requires</emphasis> an <literal>(Eq a)</literal> constraint!
-GHC faithfully implements this behaviour, odd though it is.  But for GADT-style declarations,
-GHC's behaviour is much more useful, as well as much more intuitive.</para>
 <para>
-For example, a possible application of GHC's behaviour is to reify dictionaries:
+For example, one possible application is to reify dictionaries:
 <programlisting>
    data NumInst a where
      MkNumInst :: Num a => NumInst a
@@ -1601,6 +2305,38 @@ For example, a possible application of GHC's behaviour is to reify dictionaries:
 Here, a value of type <literal>NumInst a</literal> is equivalent 
 to an explicit <literal>(Num a)</literal> dictionary.
 </para>
+<para>
+All this applies to constructors declared using the syntax of <xref linkend="existential-with-context"/>.
+For example, the <literal>NumInst</literal> data type above could equivalently be declared 
+like this:
+<programlisting>
+   data NumInst a 
+      = Num a => MkNumInst (NumInst a)
+</programlisting>
+Notice that, unlike the situation when declaring an existential, there is 
+no <literal>forall</literal>, because the <literal>Num</literal> constrains the
+data type's universally quantified type variable <literal>a</literal>.  
+A constructor may have both universal and existential type variables: for example,
+the following two declarations are equivalent:
+<programlisting>
+   data T1 a 
+       = forall b. (Num a, Eq b) => MkT1 a b
+   data T2 a where
+       MkT2 :: (Num a, Eq b) => a -> b -> T2 a
+</programlisting>
+</para>
+<para>All this behaviour contrasts with Haskell 98's peculiar treatment of 
+contexts on a data type declaration (Section 4.2.1 of the Haskell 98 Report).
+In Haskell 98 the definition
+<programlisting>
+  data Eq a => Set' a = MkSet' [a]
+</programlisting>
+gives <literal>MkSet'</literal> the same type as <literal>MkSet</literal> above.  But instead of 
+<emphasis>making available</emphasis> an <literal>(Eq a)</literal> constraint, pattern-matching
+on <literal>MkSet'</literal> <emphasis>requires</emphasis> an <literal>(Eq a)</literal> constraint!
+GHC faithfully implements this behaviour, odd though it is.  But for GADT-style declarations,
+GHC's behaviour is much more useful, as well as much more intuitive.
+</para>
 
 <para>
 The rest of this section gives further details about GADT-style data
@@ -1616,16 +2352,46 @@ otherwise is a <emphasis>generalised</emphasis> data type (<xref linkend="gadt"/
 </para></listitem>
 
 <listitem><para>
+As with other type signatures, you can give a single signature for several data constructors.
+In this example we give a single signature for <literal>T1</literal> and <literal>T2</literal>:
+<programlisting>
+  data T a where
+    T1,T2 :: a -> T a
+    T3 :: T a
+</programlisting>
+</para></listitem>
+
+<listitem><para>
 The type signature of
 each constructor is independent, and is implicitly universally quantified as usual. 
-Different constructors may have different universally-quantified type variables
-and different type-class constraints.  
-For example, this is fine:
+In particular, the type variable(s) in the "<literal>data T a where</literal>" header 
+have no scope, and different constructors may have different universally-quantified type variables:
+<programlisting>
+  data T a where        -- The 'a' has no scope
+    T1,T2 :: b -> T b   -- Means forall b. b -> T b
+    T3 :: T a           -- Means forall a. T a
+</programlisting>
+</para></listitem>
+
+<listitem><para>
+A constructor signature may mention type class constraints, which can differ for
+different constructors.  For example, this is fine:
 <programlisting>
   data T a where
-    T1 :: Eq b => b -> T b
+    T1 :: Eq b => b -> b -> T b
     T2 :: (Show c, Ix c) => c -> [c] -> T c
 </programlisting>
+When patten matching, these constraints are made available to discharge constraints
+in the body of the match. For example:
+<programlisting>
+  f :: T a -> String
+  f (T1 x y) | x==y      = "yes"
+             | otherwise = "no"
+  f (T2 a b)             = show a
+</programlisting>
+Note that <literal>f</literal> is not overloaded; the <literal>Eq</literal> constraint arising
+from the use of <literal>==</literal> is discharged by the pattern match on <literal>T1</literal>
+and similarly the <literal>Show</literal> constraint arising from the use of <literal>show</literal>.
 </para></listitem>
 
 <listitem><para>
@@ -1637,12 +2403,12 @@ have no scope.  Indeed, one can write a kind signature instead:
 </programlisting>
 or even a mixture of the two:
 <programlisting>
-  data Foo a :: (* -> *) -> * where ...
+  data Bar a :: (* -> *) -> * where ...
 </programlisting>
 The type variables (if given) may be explicitly kinded, so we could also write the header for <literal>Foo</literal>
 like this:
 <programlisting>
-  data Foo a (b :: * -> *) where ...
+  data Bar a (b :: * -> *) where ...
 </programlisting>
 </para></listitem>
 
@@ -1673,27 +2439,48 @@ declaration.   For example, these two declarations are equivalent
 </para></listitem>
 
 <listitem><para>
+The type signature may have quantified type variables that do not appear
+in the result type:
+<programlisting>
+  data Foo where
+     MkFoo :: a -> (a->Bool) -> Foo
+     Nil   :: Foo
+</programlisting>
+Here the type variable <literal>a</literal> does not appear in the result type
+of either constructor.  
+Although it is universally quantified in the type of the constructor, such
+a type variable is often called "existential".  
+Indeed, the above declaration declares precisely the same type as 
+the <literal>data Foo</literal> in <xref linkend="existential-quantification"/>.
+</para><para>
+The type may contain a class context too, of course:
+<programlisting>
+  data Showable where
+    MkShowable :: Show a => a -> Showable
+</programlisting>
+</para></listitem>
+
+<listitem><para>
 You can use record syntax on a GADT-style data type declaration:
 
 <programlisting>
   data Person where
-      Adult { name :: String, children :: [Person] } :: Person
-      Child { name :: String } :: Person
+      Adult :: { name :: String, children :: [Person] } -> Person
+      Child :: Show a => { name :: !String, funny :: a } -> Person
 </programlisting>
 As usual, for every constructor that has a field <literal>f</literal>, the type of
 field <literal>f</literal> must be the same (modulo alpha conversion).
-</para>
-<para>
-At the moment, record updates are not yet possible with GADT-style declarations, 
-so support is limited to record construction, selection and pattern matching.
-For exmaple
-<programlisting>
-  aPerson = Adult { name = "Fred", children = [] }
+The <literal>Child</literal> constructor above shows that the signature
+may have a context, existentially-quantified variables, and strictness annotations, 
+just as in the non-record case.  (NB: the "type" that follows the double-colon
+is not really a type, because of the record syntax and strictness annotations.
+A "type" of this form can appear only in a constructor signature.)
+</para></listitem>
 
-  shortName :: Person -> Bool
-  hasChildren (Adult { children = kids }) = not (null kids)
-  hasChildren (Child {})                  = False
-</programlisting>
+<listitem><para> 
+Record updates are allowed with GADT-style declarations, 
+only fields that have the following property: the type of the field
+mentions no existential type variables.
 </para></listitem>
 
 <listitem><para> 
@@ -1752,7 +2539,7 @@ the type <literal>a</literal> is refined to <literal>Int</literal>.  That's the
 A precise specification of the type rules is beyond what this user manual aspires to, 
 but the design closely follows that described in
 the paper <ulink
-url="http://research.microsoft.com/%7Esimonpj/papers/gadt/index.htm">Simple
+url="http://research.microsoft.com/%7Esimonpj/papers/gadt/">Simple
 unification-based type inference for GADTs</ulink>,
 (ICFP 2006).
 The general principle is this: <emphasis>type refinement is only carried out 
@@ -1771,13 +2558,14 @@ the result type of the <literal>case</literal> expression.  Hence the addition <
 <para>
 These and many other examples are given in papers by Hongwei Xi, and
 Tim Sheard. There is a longer introduction
-<ulink url="http://haskell.org/haskellwiki/GADT">on the wiki</ulink>,
+<ulink url="http://www.haskell.org/haskellwiki/GADT">on the wiki</ulink>,
 and Ralf Hinze's
 <ulink url="http://www.informatik.uni-bonn.de/~ralf/publications/With.pdf">Fun with phantom types</ulink> also has a number of examples. Note that papers
 may use different notation to that implemented in GHC.
 </para>
 <para>
-The rest of this section outlines the extensions to GHC that support GADTs. 
+The rest of this section outlines the extensions to GHC that support GADTs.   The extension is enabled with 
+<option>-XGADTs</option>.  The <option>-XGADTs</option> flag also sets <option>-XRelaxedPolyRec</option>.
 <itemizedlist>
 <listitem><para>
 A GADT can only be declared using GADT-style syntax (<xref linkend="gadt-style"/>); 
@@ -1786,13 +2574,19 @@ The result type of each constructor must begin with the type constructor being d
 but for a GADT the arguments to the type constructor can be arbitrary monotypes.  
 For example, in the <literal>Term</literal> data
 type above, the type of each constructor must end with <literal>Term ty</literal>, but
-the <literal>ty</literal> may not be a type variable (e.g. the <literal>Lit</literal>
+the <literal>ty</literal> need not be a type variable (e.g. the <literal>Lit</literal>
 constructor).
 </para></listitem>
 
 <listitem><para>
+It's is permitted to declare an ordinary algebraic data type using GADT-style syntax.
+What makes a GADT into a GADT is not the syntax, but rather the presence of data constructors
+whose result type is not just <literal>T a b</literal>.
+</para></listitem>
+
+<listitem><para>
 You cannot use a <literal>deriving</literal> clause for a GADT; only for
-an ordianary data type.
+an ordinary data type.
 </para></listitem>
 
 <listitem><para>
@@ -1826,16 +2620,119 @@ their selector functions actually have different types:
 </programlisting>
 </para></listitem>
 
+<listitem><para>
+When pattern-matching against data constructors drawn from a GADT, 
+for example in a <literal>case</literal> expression, the following rules apply:
+<itemizedlist>
+<listitem><para>The type of the scrutinee must be rigid.</para></listitem>
+<listitem><para>The type of the entire <literal>case</literal> expression must be rigid.</para></listitem>
+<listitem><para>The type of any free variable mentioned in any of
+the <literal>case</literal> alternatives must be rigid.</para></listitem>
+</itemizedlist>
+A type is "rigid" if it is completely known to the compiler at its binding site.  The easiest
+way to ensure that a variable a rigid type is to give it a type signature.
+For more precise details see <ulink url="http://research.microsoft.com/%7Esimonpj/papers/gadt">
+Simple unification-based type inference for GADTs
+</ulink>. The criteria implemented by GHC are given in the Appendix.
+
+</para></listitem>
+
 </itemizedlist>
 </para>
 
 </sect2>
+</sect1>
 
 <!-- ====================== End of Generalised algebraic data types =======================  -->
 
+<sect1 id="deriving">
+<title>Extensions to the "deriving" mechanism</title>
+
+<sect2 id="deriving-inferred">
+<title>Inferred context for deriving clauses</title>
+
+<para>
+The Haskell Report is vague about exactly when a <literal>deriving</literal> clause is
+legal.  For example:
+<programlisting>
+  data T0 f a = MkT0 a         deriving( Eq )
+  data T1 f a = MkT1 (f a)     deriving( Eq )
+  data T2 f a = MkT2 (f (f a)) deriving( Eq )
+</programlisting>
+The natural generated <literal>Eq</literal> code would result in these instance declarations:
+<programlisting>
+  instance Eq a         => Eq (T0 f a) where ...
+  instance Eq (f a)     => Eq (T1 f a) where ...
+  instance Eq (f (f a)) => Eq (T2 f a) where ...
+</programlisting>
+The first of these is obviously fine. The second is still fine, although less obviously. 
+The third is not Haskell 98, and risks losing termination of instances.
+</para>
+<para>
+GHC takes a conservative position: it accepts the first two, but not the third.  The  rule is this:
+each constraint in the inferred instance context must consist only of type variables, 
+with no repetitions.
+</para>
+<para>
+This rule is applied regardless of flags.  If you want a more exotic context, you can write
+it yourself, using the <link linkend="stand-alone-deriving">standalone deriving mechanism</link>.
+</para>
+</sect2>
+
+<sect2 id="stand-alone-deriving">
+<title>Stand-alone deriving declarations</title>
+
+<para>
+GHC now allows stand-alone <literal>deriving</literal> declarations, enabled by <literal>-XStandaloneDeriving</literal>:
+<programlisting>
+  data Foo a = Bar a | Baz String
+
+  deriving instance Eq a => Eq (Foo a)
+</programlisting>
+The syntax is identical to that of an ordinary instance declaration apart from (a) the keyword
+<literal>deriving</literal>, and (b) the absence of the <literal>where</literal> part.
+You must supply a context (in the example the context is <literal>(Eq a)</literal>), 
+exactly as you would in an ordinary instance declaration.
+(In contrast the context is inferred in a <literal>deriving</literal> clause 
+attached to a data type declaration.) 
+
+A <literal>deriving instance</literal> declaration
+must obey the same rules concerning form and termination as ordinary instance declarations,
+controlled by the same flags; see <xref linkend="instance-decls"/>.
+</para>
+<para>
+Unlike a <literal>deriving</literal>
+declaration attached to a <literal>data</literal> declaration, the instance can be more specific
+than the data type (assuming you also use 
+<literal>-XFlexibleInstances</literal>, <xref linkend="instance-rules"/>).  Consider
+for example
+<programlisting>
+  data Foo a = Bar a | Baz String
+
+  deriving instance Eq a => Eq (Foo [a])
+  deriving instance Eq a => Eq (Foo (Maybe a))
+</programlisting>
+This will generate a derived instance for <literal>(Foo [a])</literal> and <literal>(Foo (Maybe a))</literal>,
+but other types such as <literal>(Foo (Int,Bool))</literal> will not be an instance of <literal>Eq</literal>.
+</para>
+
+<para>The stand-alone syntax is generalised for newtypes in exactly the same
+way that ordinary <literal>deriving</literal> clauses are generalised (<xref linkend="newtype-deriving"/>).
+For example:
+<programlisting>
+  newtype Foo a = MkFoo (State Int a)
+
+  deriving instance MonadState Int Foo
+</programlisting>
+GHC always treats the <emphasis>last</emphasis> parameter of the instance
+(<literal>Foo</literal> in this example) as the type whose instance is being derived.
+</para>
+
+</sect2>
+
 
 <sect2 id="deriving-typeable">
-<title>Deriving clause for classes <literal>Typeable</literal> and <literal>Data</literal></title>
+<title>Deriving clause for extra classes (<literal>Typeable</literal>, <literal>Data</literal>, etc)</title>
 
 <para>
 Haskell 98 allows the programmer to add "<literal>deriving( Eq, Ord )</literal>" to a data type 
@@ -1845,11 +2742,11 @@ classes <literal>Eq</literal>, <literal>Ord</literal>,
 <literal>Enum</literal>, <literal>Ix</literal>, <literal>Bounded</literal>, <literal>Read</literal>, and <literal>Show</literal>.
 </para>
 <para>
-GHC extends this list with two more classes that may be automatically derived 
-(provided the <option>-fglasgow-exts</option> flag is specified):
-<literal>Typeable</literal>, and <literal>Data</literal>.  These classes are defined in the library
-modules <literal>Data.Typeable</literal> and <literal>Data.Generics</literal> respectively, and the
-appropriate class must be in scope before it can be mentioned in the <literal>deriving</literal> clause.
+GHC extends this list with several more classes that may be automatically derived:
+<itemizedlist>
+<listitem><para> With <option>-XDeriveDataTypeable</option>, you can derive instances of the classes
+<literal>Typeable</literal>, and <literal>Data</literal>, defined in the library
+modules <literal>Data.Typeable</literal> and <literal>Data.Generics</literal> respectively.
 </para>
 <para>An instance of <literal>Typeable</literal> can only be derived if the
 data type has seven or fewer type parameters, all of kind <literal>*</literal>.
@@ -1865,6 +2762,26 @@ In other cases, there is nothing to stop the programmer writing a <literal>Typab
 class, whose kind suits that of the data type constructor, and
 then writing the data type instance by hand.
 </para>
+</listitem>
+
+<listitem><para> With <option>-XDeriveFunctor</option>, you can derive instances of 
+the class <literal>Functor</literal>,
+defined in <literal>GHC.Base</literal>.
+</para></listitem>
+
+<listitem><para> With <option>-XDeriveFoldable</option>, you can derive instances of 
+the class <literal>Foldable</literal>,
+defined in <literal>Data.Foldable</literal>.
+</para></listitem>
+
+<listitem><para> With <option>-XDeriveTraversable</option>, you can derive instances of 
+the class <literal>Traversable</literal>,
+defined in <literal>Data.Traversable</literal>.
+</para></listitem>
+</itemizedlist>
+In each case the appropriate class must be in scope before it 
+can be mentioned in the <literal>deriving</literal> clause.
+</para>
 </sect2>
 
 <sect2 id="newtype-deriving">
@@ -1878,14 +2795,14 @@ Haskell 98, you can inherit instances of <literal>Eq</literal>, <literal>Ord</li
 other classes you have to write an explicit instance declaration. For
 example, if you define
 
-<programlisting> 
+<programlisting>
   newtype Dollars = Dollars Int 
-</programlisting> 
+</programlisting>
 
 and you want to use arithmetic on <literal>Dollars</literal>, you have to
 explicitly define an instance of <literal>Num</literal>:
 
-<programlisting> 
+<programlisting>
   instance Num Dollars where
     Dollars a + Dollars b = Dollars (a+b)
     ...
@@ -1900,18 +2817,20 @@ dictionary, only slower!
 
 <sect3> <title> Generalising the deriving clause </title>
 <para>
-GHC now permits such instances to be derived instead, so one can write 
-<programlisting> 
+GHC now permits such instances to be derived instead, 
+using the flag <option>-XGeneralizedNewtypeDeriving</option>,
+so one can write 
+<programlisting>
   newtype Dollars = Dollars Int deriving (Eq,Show,Num)
-</programlisting> 
+</programlisting>
 
 and the implementation uses the <emphasis>same</emphasis> <literal>Num</literal> dictionary
 for <literal>Dollars</literal> as for <literal>Int</literal>. Notionally, the compiler
 derives an instance declaration of the form
 
-<programlisting> 
+<programlisting>
   instance Num Int => Num Dollars
-</programlisting> 
+</programlisting>
 
 which just adds or removes the <literal>newtype</literal> constructor according to the type.
 </para>
@@ -1921,32 +2840,32 @@ We can also derive instances of constructor classes in a similar
 way. For example, suppose we have implemented state and failure monad
 transformers, such that
 
-<programlisting> 
+<programlisting>
   instance Monad m => Monad (State s m) 
   instance Monad m => Monad (Failure m)
-</programlisting> 
+</programlisting>
 In Haskell 98, we can define a parsing monad by 
-<programlisting> 
+<programlisting>
   type Parser tok m a = State [tok] (Failure m) a
-</programlisting> 
+</programlisting>
 
 which is automatically a monad thanks to the instance declarations
 above. With the extension, we can make the parser type abstract,
 without needing to write an instance of class <literal>Monad</literal>, via
 
-<programlisting> 
+<programlisting>
   newtype Parser tok m a = Parser (State [tok] (Failure m) a)
                          deriving Monad
 </programlisting>
 In this case the derived instance declaration is of the form 
-<programlisting> 
+<programlisting>
   instance Monad (State [tok] (Failure m)) => Monad (Parser tok m) 
-</programlisting> 
+</programlisting>
 
 Notice that, since <literal>Monad</literal> is a constructor class, the
 instance is a <emphasis>partial application</emphasis> of the new type, not the
 entire left hand side. We can imagine that the type declaration is
-``eta-converted'' to generate the context of the instance
+"eta-converted" to generate the context of the instance
 declaration.
 </para>
 <para>
@@ -1956,12 +2875,12 @@ newtype is the last class parameter. In this case, a ``partial
 application'' of the class appears in the <literal>deriving</literal>
 clause. For example, given the class
 
-<programlisting> 
+<programlisting>
   class StateMonad s m | m -> s where ... 
   instance Monad m => StateMonad s (State s m) where ... 
-</programlisting> 
+</programlisting>
 then we can derive an instance of <literal>StateMonad</literal> for <literal>Parser</literal>s by 
-<programlisting> 
+<programlisting>
   newtype Parser tok m a = Parser (State [tok] (Failure m) a)
                          deriving (Monad, StateMonad [tok])
 </programlisting>
@@ -1969,7 +2888,7 @@ then we can derive an instance of <literal>StateMonad</literal> for <literal>Par
 The derived instance is obtained by completing the application of the
 class to the new type:
 
-<programlisting> 
+<programlisting>
   instance StateMonad [tok] (State [tok] (Failure m)) =>
            StateMonad [tok] (Parser tok m)
 </programlisting>
@@ -1989,9 +2908,9 @@ the newtype and its representation.
 Derived instance declarations are constructed as follows. Consider the
 declaration (after expansion of any type synonyms)
 
-<programlisting> 
+<programlisting>
   newtype T v1...vn = T' (t vk+1...vn) deriving (c1...cm) 
-</programlisting> 
+</programlisting>
 
 where 
  <itemizedlist>
@@ -2020,17 +2939,17 @@ where
 </itemizedlist>
 Then, for each <literal>ci</literal>, the derived instance
 declaration is:
-<programlisting> 
+<programlisting>
   instance ci t => ci (T v1...vk)
 </programlisting>
 As an example which does <emphasis>not</emphasis> work, consider 
-<programlisting> 
+<programlisting>
   newtype NonMonad m s = NonMonad (State s m s) deriving Monad 
-</programlisting> 
+</programlisting>
 Here we cannot derive the instance 
-<programlisting> 
+<programlisting>
   instance Monad (State s m) => Monad (NonMonad m) 
-</programlisting> 
+</programlisting>
 
 because the type variable <literal>s</literal> occurs in <literal>State s m</literal>,
 and so cannot be "eta-converted" away. It is a good thing that this
@@ -2044,7 +2963,7 @@ Notice also that the <emphasis>order</emphasis> of class parameters becomes
 important, since we can only derive instances for the last one. If the
 <literal>StateMonad</literal> class above were instead defined as
 
-<programlisting> 
+<programlisting>
   class StateMonad m s | m -> s where ... 
 </programlisting>
 
@@ -2062,41 +2981,13 @@ and <literal>Data</literal>, for which the built-in derivation applies (section
 the standard method is used or the one described here.)
 </para>
 </sect3>
-
-</sect2>
-
-<sect2 id="stand-alone-deriving">
-<title>Stand-alone deriving declarations</title>
-
-<para>
-GHC now allows stand-alone <literal>deriving</literal> declarations, enabled by <literal>-fglasgow-exts</literal>:
-<programlisting>
-  data Foo a = Bar a | Baz String
-
-  derive instance Eq (Foo a)
-</programlisting>
-The token "<literal>derive</literal>" is a keyword only when followed by "<literal>instance</literal>";
-you can use it as a variable name elsewhere.</para>
-<para>The stand-alone syntax is generalised for newtypes in exactly the same
-way that ordinary <literal>deriving</literal> clauses are generalised (<xref linkend="newtype-deriving"/>).
-For example:
-<programlisting>
-  newtype Foo a = MkFoo (State Int a)
-
-  derive instance MonadState Int Foo
-</programlisting>
-GHC always treats the <emphasis>last</emphasis> parameter of the instance
-(<literal>Foo</literal> in this exmample) as the type whose instance is being derived.
-</para>
-
 </sect2>
-
 </sect1>
 
 
 <!-- TYPE SYSTEM EXTENSIONS -->
-<sect1 id="other-type-extensions">
-<title>Other type system extensions</title>
+<sect1 id="type-class-extensions">
+<title>Class and instances declarations</title>
 
 <sect2 id="multi-param-type-classes">
 <title>Class declarations</title>
@@ -2104,8 +2995,8 @@ GHC always treats the <emphasis>last</emphasis> parameter of the instance
 <para>
 This section, and the next one, documents GHC's type-class extensions.
 There's lots of background in the paper <ulink
-url="http://research.microsoft.com/~simonpj/Papers/type-class-design-space" >Type
-classes: exploring the design space</ulink > (Simon Peyton Jones, Mark
+url="http://research.microsoft.com/~simonpj/Papers/type-class-design-space/">Type
+classes: exploring the design space</ulink> (Simon Peyton Jones, Mark
 Jones, Erik Meijer).
 </para>
 <para>
@@ -2184,7 +3075,7 @@ class type variable, thus:
 The type of <literal>elem</literal> is illegal in Haskell 98, because it
 contains the constraint <literal>Eq a</literal>, constrains only the 
 class type variable (in this case <literal>a</literal>).
-GHC lifts this restriction.
+GHC lifts this restriction (flag <option>-XConstrainedClassMethods</option>).
 </para>
 
 
@@ -2196,7 +3087,7 @@ GHC lifts this restriction.
 </title>
 
 <para> Functional dependencies are implemented as described by Mark Jones
-in &ldquo;<ulink url="http://www.cse.ogi.edu/~mpj/pubs/fundeps.html">Type Classes with Functional Dependencies</ulink>&rdquo;, Mark P. Jones, 
+in &ldquo;<ulink url="http://citeseer.ist.psu.edu/jones00type.html">Type Classes with Functional Dependencies</ulink>&rdquo;, Mark P. Jones, 
 In Proceedings of the 9th European Symposium on Programming, 
 ESOP 2000, Berlin, Germany, March 2000, Springer-Verlag LNCS 1782,
 .
@@ -2509,9 +3400,6 @@ sets of instance declarations.
 <sect2 id="instance-decls">
 <title>Instance declarations</title>
 
-<sect3 id="instance-rules">
-<title>Relaxed rules for instance declarations</title>
-
 <para>An instance declaration has the form
 <screen>
   instance ( <replaceable>assertion</replaceable><subscript>1</subscript>, ..., <replaceable>assertion</replaceable><subscript>n</subscript>) =&gt; <replaceable>class</replaceable> <replaceable>type</replaceable><subscript>1</subscript> ... <replaceable>type</replaceable><subscript>m</subscript> where ...
@@ -2521,24 +3409,78 @@ The part before the "<literal>=&gt;</literal>" is the
 "<literal>=&gt;</literal>" is the <emphasis>head</emphasis> of the instance declaration.
 </para>
 
+<sect3 id="flexible-instance-head">
+<title>Relaxed rules for the instance head</title>
+
 <para>
 In Haskell 98 the head of an instance declaration
 must be of the form <literal>C (T a1 ... an)</literal>, where
-<literal>C</literal> is the class, <literal>T</literal> is a type constructor,
+<literal>C</literal> is the class, <literal>T</literal> is a data type constructor,
 and the <literal>a1 ... an</literal> are distinct type variables.
-Furthermore, the assertions in the context of the instance declaration
+GHC relaxes these rules in two ways.
+<itemizedlist>
+<listitem>
+<para>
+The <option>-XFlexibleInstances</option> flag allows the head of the instance
+declaration to mention arbitrary nested types.
+For example, this becomes a legal instance declaration
+<programlisting>
+  instance C (Maybe Int) where ...
+</programlisting>
+See also the <link linkend="instance-overlap">rules on overlap</link>.
+</para></listitem>
+<listitem><para>
+With the <option>-XTypeSynonymInstances</option> flag, instance heads may use type
+synonyms. As always, using a type synonym is just shorthand for
+writing the RHS of the type synonym definition.  For example:
+
+
+<programlisting>
+  type Point = (Int,Int)
+  instance C Point   where ...
+  instance C [Point] where ...
+</programlisting>
+
+
+is legal.  However, if you added
+
+
+<programlisting>
+  instance C (Int,Int) where ...
+</programlisting>
+
+
+as well, then the compiler will complain about the overlapping
+(actually, identical) instance declarations.  As always, type synonyms
+must be fully applied.  You cannot, for example, write:
+
+<programlisting>
+  type P a = [[a]]
+  instance Monad P where ...
+</programlisting>
+
+</para></listitem>
+</itemizedlist>
+</para>
+</sect3>
+
+<sect3 id="instance-rules">
+<title>Relaxed rules for instance contexts</title>
+
+<para>In Haskell 98, the assertions in the context of the instance declaration
 must be of the form <literal>C a</literal> where <literal>a</literal>
 is a type variable that occurs in the head.
 </para>
+
 <para>
-The <option>-fglasgow-exts</option> flag loosens these restrictions
-considerably.  Firstly, multi-parameter type classes are permitted.  Secondly,
-the context and head of the instance declaration can each consist of arbitrary
+The <option>-XFlexibleContexts</option> flag relaxes this rule, as well
+as the corresponding rule for type signatures (see <xref linkend="flexible-contexts"/>).
+With this flag the context of the instance declaration can each consist of arbitrary
 (well-kinded) assertions <literal>(C t1 ... tn)</literal> subject only to the
 following rules:
 <orderedlist>
 <listitem><para>
-For each assertion in the context:
+The Paterson Conditions: for each assertion in the context
 <orderedlist>
 <listitem><para>No type variable has more occurrences in the assertion than in the head</para></listitem>
 <listitem><para>The assertion has fewer constructors and variables (taken together
@@ -2546,7 +3488,7 @@ For each assertion in the context:
 </orderedlist>
 </para></listitem>
 
-<listitem><para>The coverage condition.  For each functional dependency,
+<listitem><para>The Coverage Condition.  For each functional dependency,
 <replaceable>tvs</replaceable><subscript>left</subscript> <literal>-&gt;</literal>
 <replaceable>tvs</replaceable><subscript>right</subscript>,  of the class,
 every type variable in
@@ -2558,11 +3500,15 @@ corresponding type in the instance declaration.
 </orderedlist>
 These restrictions ensure that context reduction terminates: each reduction
 step makes the problem smaller by at least one
-constructor.  For example, the following would make the type checker
-loop if it wasn't excluded:
-<programlisting>
-  instance C a => C a where ...
-</programlisting>
+constructor.  Both the Paterson Conditions and the Coverage Condition are lifted 
+if you give the <option>-XUndecidableInstances</option> 
+flag (<xref linkend="undecidable-instances"/>).
+You can find lots of background material about the reason for these
+restrictions in the paper <ulink
+url="http://research.microsoft.com/%7Esimonpj/papers/fd%2Dchr/">
+Understanding functional dependencies via Constraint Handling Rules</ulink>.
+</para>
+<para>
 For example, these are OK:
 <programlisting>
   instance C Int [a]          -- Multiple parameters
@@ -2614,11 +3560,6 @@ something more specific does not:
     op = ... -- Default
 </programlisting>
 </para>
-<para>You can find lots of background material about the reason for these
-restrictions in the paper <ulink
-url="http://research.microsoft.com/%7Esimonpj/papers/fd%2Dchr/">
-Understanding functional dependencies via Constraint Handling Rules</ulink>.
-</para>
 </sect3>
 
 <sect3 id="undecidable-instances">
@@ -2661,7 +3602,7 @@ typechecker loop:
   class F a b | a->b
   instance F [a] [[a]]
   instance (D c, F a c) => D [a]   -- 'c' is not mentioned in the head
-</programlisting>  
+</programlisting>
 Similarly, it can be tempting to lift the coverage condition:
 <programlisting>
   class Mul a b c | a b -> c where
@@ -2681,10 +3622,10 @@ makes instance inference go into a loop, because it requires the constraint
 </para>
 <para>
 Nevertheless, GHC allows you to experiment with more liberal rules.  If you use
-the experimental flag <option>-fallow-undecidable-instances</option>
-<indexterm><primary>-fallow-undecidable-instances
-option</primary></indexterm>, you can use arbitrary
-types in both an instance context and instance head.  Termination is ensured by having a
+the experimental flag <option>-XUndecidableInstances</option>
+<indexterm><primary>-XUndecidableInstances</primary></indexterm>, 
+both the Paterson Conditions and the Coverage Condition
+(described in <xref linkend="instance-rules"/>) are lifted.  Termination is ensured by having a
 fixed-depth recursion stack.  If you exceed the stack depth you get a
 sort of backtrace, and the opportunity to increase the stack depth
 with <option>-fcontext-stack=</option><emphasis>N</emphasis>.
@@ -2699,11 +3640,11 @@ with <option>-fcontext-stack=</option><emphasis>N</emphasis>.
 In general, <emphasis>GHC requires that that it be unambiguous which instance
 declaration
 should be used to resolve a type-class constraint</emphasis>. This behaviour
-can be modified by two flags: <option>-fallow-overlapping-instances</option>
-<indexterm><primary>-fallow-overlapping-instances
+can be modified by two flags: <option>-XOverlappingInstances</option>
+<indexterm><primary>-XOverlappingInstances
 </primary></indexterm> 
-and <option>-fallow-incoherent-instances</option>
-<indexterm><primary>-fallow-incoherent-instances
+and <option>-XIncoherentInstances</option>
+<indexterm><primary>-XIncoherentInstances
 </primary></indexterm>, as this section discusses.  Both these
 flags are dynamic flags, and can be set on a per-module basis, using 
 an <literal>OPTIONS_GHC</literal> pragma if desired (<xref linkend="source-file-options"/>).</para>
@@ -2731,7 +3672,7 @@ particular constraint matches more than one.
 </para>
 
 <para>
-The <option>-fallow-overlapping-instances</option> flag instructs GHC to allow
+The <option>-XOverlappingInstances</option> flag instructs GHC to allow
 more than one instance to match, provided there is a most specific one.  For
 example, the constraint <literal>C Int [Int]</literal> matches instances (A),
 (C) and (D), but the last is more specific, and hence is chosen.  If there is no
@@ -2748,30 +3689,67 @@ Suppose that from the RHS of <literal>f</literal> we get the constraint
 GHC does not commit to instance (C), because in a particular
 call of <literal>f</literal>, <literal>b</literal> might be instantiate 
 to <literal>Int</literal>, in which case instance (D) would be more specific still.
-So GHC rejects the program.  If you add the flag <option>-fallow-incoherent-instances</option>,
+So GHC rejects the program.  
+(If you add the flag <option>-XIncoherentInstances</option>,
 GHC will instead pick (C), without complaining about 
-the problem of subsequent instantiations.
+the problem of subsequent instantiations.)
+</para>
+<para>
+Notice that we gave a type signature to <literal>f</literal>, so GHC had to
+<emphasis>check</emphasis> that <literal>f</literal> has the specified type.  
+Suppose instead we do not give a type signature, asking GHC to <emphasis>infer</emphasis>
+it instead.  In this case, GHC will refrain from
+simplifying the constraint <literal>C Int [b]</literal> (for the same reason
+as before) but, rather than rejecting the program, it will infer the type
+<programlisting>
+  f :: C Int [b] => [b] -> [b]
+</programlisting>
+That postpones the question of which instance to pick to the 
+call site for <literal>f</literal>
+by which time more is known about the type <literal>b</literal>.
+You can write this type signature yourself if you use the 
+<link linkend="flexible-contexts"><option>-XFlexibleContexts</option></link>
+flag.
+</para>
+<para>
+Exactly the same situation can arise in instance declarations themselves.  Suppose we have
+<programlisting>
+  class Foo a where
+     f :: a -> a
+  instance Foo [b] where
+     f x = ...
+</programlisting>
+and, as before, the constraint <literal>C Int [b]</literal> arises from <literal>f</literal>'s
+right hand side.  GHC will reject the instance, complaining as before that it does not know how to resolve
+the constraint <literal>C Int [b]</literal>, because it matches more than one instance
+declaration.  The solution is to postpone the choice by adding the constraint to the context
+of the instance declaration, thus:
+<programlisting>
+  instance C Int [b] => Foo [b] where
+     f x = ...
+</programlisting>
+(You need <link linkend="instance-rules"><option>-XFlexibleInstances</option></link> to do this.)
 </para>
 <para>
 The willingness to be overlapped or incoherent is a property of 
 the <emphasis>instance declaration</emphasis> itself, controlled by the
-presence or otherwise of the <option>-fallow-overlapping-instances</option> 
-and <option>-fallow-incoherent-instances</option> flags when that mdodule is
+presence or otherwise of the <option>-XOverlappingInstances</option> 
+and <option>-XIncoherentInstances</option> flags when that module is
 being defined.  Neither flag is required in a module that imports and uses the
 instance declaration.  Specifically, during the lookup process:
 <itemizedlist>
 <listitem><para>
 An instance declaration is ignored during the lookup process if (a) a more specific
 match is found, and (b) the instance declaration was compiled with 
-<option>-fallow-overlapping-instances</option>.  The flag setting for the
+<option>-XOverlappingInstances</option>.  The flag setting for the
 more-specific instance does not matter.
 </para></listitem>
 <listitem><para>
-Suppose an instance declaration does not matche the constraint being looked up, but
+Suppose an instance declaration does not match the constraint being looked up, but
 does unify with it, so that it might match when the constraint is further 
 instantiated.  Usually GHC will regard this as a reason for not committing to
 some other constraint.  But if the instance declaration was compiled with
-<option>-fallow-incoherent-instances</option>, GHC will skip the "does-it-unify?" 
+<option>-XIncoherentInstances</option>, GHC will skip the "does-it-unify?" 
 check for that declaration.
 </para></listitem>
 </itemizedlist>
@@ -2780,74 +3758,815 @@ overlapping instances without the library client having to know.
 </para>
 <para>
 If an instance declaration is compiled without
-<option>-fallow-overlapping-instances</option>,
+<option>-XOverlappingInstances</option>,
 then that instance can never be overlapped.  This could perhaps be
 inconvenient.  Perhaps the rule should instead say that the
 <emphasis>overlapping</emphasis> instance declaration should be compiled in
 this way, rather than the <emphasis>overlapped</emphasis> one.  Perhaps overlap
 at a usage site should be permitted regardless of how the instance declarations
-are compiled, if the <option>-fallow-overlapping-instances</option> flag is
+are compiled, if the <option>-XOverlappingInstances</option> flag is
 used at the usage site.  (Mind you, the exact usage site can occasionally be
 hard to pin down.)  We are interested to receive feedback on these points.
 </para>
-<para>The <option>-fallow-incoherent-instances</option> flag implies the
-<option>-fallow-overlapping-instances</option> flag, but not vice versa.
+<para>The <option>-XIncoherentInstances</option> flag implies the
+<option>-XOverlappingInstances</option> flag, but not vice versa.
 </para>
 </sect3>
 
-<sect3>
-<title>Type synonyms in the instance head</title>
 
-<para>
-<emphasis>Unlike Haskell 98, instance heads may use type
-synonyms</emphasis>.  (The instance "head" is the bit after the "=>" in an instance decl.)
-As always, using a type synonym is just shorthand for
-writing the RHS of the type synonym definition.  For example:
 
+</sect2>
+
+<sect2 id="overloaded-strings">
+<title>Overloaded string literals
+</title>
+
+<para>
+GHC supports <emphasis>overloaded string literals</emphasis>.  Normally a
+string literal has type <literal>String</literal>, but with overloaded string
+literals enabled (with <literal>-XOverloadedStrings</literal>)
+ a string literal has type <literal>(IsString a) => a</literal>.
+</para>
+<para>
+This means that the usual string syntax can be used, e.g., for packed strings
+and other variations of string like types.  String literals behave very much
+like integer literals, i.e., they can be used in both expressions and patterns.
+If used in a pattern the literal with be replaced by an equality test, in the same
+way as an integer literal is.
+</para>
+<para>
+The class <literal>IsString</literal> is defined as:
+<programlisting>
+class IsString a where
+    fromString :: String -> a
+</programlisting>
+The only predefined instance is the obvious one to make strings work as usual:
+<programlisting>
+instance IsString [Char] where
+    fromString cs = cs
+</programlisting>
+The class <literal>IsString</literal> is not in scope by default.  If you want to mention
+it explicitly (for example, to give an instance declaration for it), you can import it
+from module <literal>GHC.Exts</literal>.
+</para>
+<para>
+Haskell's defaulting mechanism is extended to cover string literals, when <option>-XOverloadedStrings</option> is specified.
+Specifically:
+<itemizedlist>
+<listitem><para>
+Each type in a default declaration must be an 
+instance of <literal>Num</literal> <emphasis>or</emphasis> of <literal>IsString</literal>.
+</para></listitem>
+
+<listitem><para>
+The standard defaulting rule (<ulink url="http://www.haskell.org/onlinereport/decls.html#sect4.3.4">Haskell Report, Section 4.3.4</ulink>)
+is extended thus: defaulting applies when all the unresolved constraints involve standard classes
+<emphasis>or</emphasis> <literal>IsString</literal>; and at least one is a numeric class
+<emphasis>or</emphasis> <literal>IsString</literal>.
+</para></listitem>
+</itemizedlist>
+</para>
+<para>
+A small example:
+<programlisting>
+module Main where
+
+import GHC.Exts( IsString(..) )
+
+newtype MyString = MyString String deriving (Eq, Show)
+instance IsString MyString where
+    fromString = MyString
+
+greet :: MyString -> MyString
+greet "hello" = "world"
+greet other = other
+
+main = do
+    print $ greet "hello"
+    print $ greet "fool"
+</programlisting>
+</para>
+<para>
+Note that deriving <literal>Eq</literal> is necessary for the pattern matching
+to work since it gets translated into an equality comparison.
+</para>
+</sect2>
+
+</sect1>
+
+<sect1 id="type-families">
+<title>Type families</title>
+
+<para>
+  <firstterm>Indexed type families</firstterm> are a new GHC extension to
+  facilitate type-level 
+  programming. Type families are a generalisation of <firstterm>associated
+  data types</firstterm> 
+  (&ldquo;<ulink url="http://www.cse.unsw.edu.au/~chak/papers/CKPM05.html">Associated 
+  Types with Class</ulink>&rdquo;, M. Chakravarty, G. Keller, S. Peyton Jones,
+  and S. Marlow. In Proceedings of &ldquo;The 32nd Annual ACM SIGPLAN-SIGACT
+     Symposium on Principles of Programming Languages (POPL'05)&rdquo;, pages
+  1-13, ACM Press, 2005) and <firstterm>associated type synonyms</firstterm>
+  (&ldquo;<ulink url="http://www.cse.unsw.edu.au/~chak/papers/CKP05.html">Type  
+  Associated Type Synonyms</ulink>&rdquo;. M. Chakravarty, G. Keller, and
+  S. Peyton Jones. 
+  In Proceedings of &ldquo;The Tenth ACM SIGPLAN International Conference on
+  Functional Programming&rdquo;, ACM Press, pages 241-253, 2005).  Type families
+  themselves are described in the paper &ldquo;<ulink 
+  url="http://www.cse.unsw.edu.au/~chak/papers/SPCS08.html">Type
+  Checking with Open Type Functions</ulink>&rdquo;, T. Schrijvers,
+  S. Peyton-Jones, 
+  M. Chakravarty, and M. Sulzmann, in Proceedings of &ldquo;ICFP 2008: The
+  13th ACM SIGPLAN International Conference on Functional
+  Programming&rdquo;, ACM Press, pages 51-62, 2008. Type families
+  essentially provide type-indexed data types and named functions on types,
+  which are useful for generic programming and highly parameterised library
+  interfaces as well as interfaces with enhanced static information, much like
+  dependent types. They might also be regarded as an alternative to functional
+  dependencies, but provide a more functional style of type-level programming
+  than the relational style of functional dependencies. 
+</para>
+<para>
+  Indexed type families, or type families for short, are type constructors that
+  represent sets of types. Set members are denoted by supplying the type family
+  constructor with type parameters, which are called <firstterm>type
+  indices</firstterm>. The 
+  difference between vanilla parametrised type constructors and family
+  constructors is much like between parametrically polymorphic functions and
+  (ad-hoc polymorphic) methods of type classes. Parametric polymorphic functions
+  behave the same at all type instances, whereas class methods can change their
+  behaviour in dependence on the class type parameters. Similarly, vanilla type
+  constructors imply the same data representation for all type instances, but
+  family constructors can have varying representation types for varying type
+  indices. 
+</para>
+<para>
+  Indexed type families come in two flavours: <firstterm>data
+    families</firstterm> and <firstterm>type synonym 
+    families</firstterm>. They are the indexed family variants of algebraic
+  data types and type synonyms, respectively. The instances of data families
+  can be data types and newtypes. 
+</para>
+<para>
+  Type families are enabled by the flag <option>-XTypeFamilies</option>.
+  Additional information on the use of type families in GHC is available on
+  <ulink url="http://www.haskell.org/haskellwiki/GHC/Indexed_types">the
+  Haskell wiki page on type families</ulink>.
+</para>
+
+<sect2 id="data-families">
+  <title>Data families</title>
+
+  <para>
+    Data families appear in two flavours: (1) they can be defined on the
+    toplevel 
+    or (2) they can appear inside type classes (in which case they are known as
+    associated types). The former is the more general variant, as it lacks the
+    requirement for the type-indexes to coincide with the class
+    parameters. However, the latter can lead to more clearly structured code and
+    compiler warnings if some type instances were - possibly accidentally -
+    omitted. In the following, we always discuss the general toplevel form first
+    and then cover the additional constraints placed on associated types.
+  </para>
+
+  <sect3 id="data-family-declarations"> 
+    <title>Data family declarations</title>
+
+    <para>
+      Indexed data families are introduced by a signature, such as 
+<programlisting>
+data family GMap k :: * -> *
+</programlisting>
+      The special <literal>family</literal> distinguishes family from standard
+      data declarations.  The result kind annotation is optional and, as
+      usual, defaults to <literal>*</literal> if omitted.  An example is
+<programlisting>
+data family Array e
+</programlisting>
+      Named arguments can also be given explicit kind signatures if needed.
+      Just as with
+      [http://www.haskell.org/ghc/docs/latest/html/users_guide/gadt.html GADT
+      declarations] named arguments are entirely optional, so that we can
+      declare <literal>Array</literal> alternatively with 
+<programlisting>
+data family Array :: * -> *
+</programlisting>
+    </para>
+
+    <sect4 id="assoc-data-family-decl">
+      <title>Associated data family declarations</title>
+      <para>
+       When a data family is declared as part of a type class, we drop
+       the <literal>family</literal> special.  The <literal>GMap</literal>
+       declaration takes the following form 
+<programlisting>
+class GMapKey k where
+  data GMap k :: * -> *
+  ...
+</programlisting>
+       In contrast to toplevel declarations, named arguments must be used for
+       all type parameters that are to be used as type-indexes.  Moreover,
+       the argument names must be class parameters.  Each class parameter may
+       only be used at most once per associated type, but some may be omitted
+       and they may be in an order other than in the class head.  Hence, the
+       following contrived example is admissible: 
+<programlisting>
+  class C a b c where
+  data T c a :: *
+</programlisting>
+      </para>
+    </sect4>
+  </sect3>
+
+  <sect3 id="data-instance-declarations"> 
+    <title>Data instance declarations</title>
+
+    <para>
+      Instance declarations of data and newtype families are very similar to
+      standard data and newtype declarations.  The only two differences are
+      that the keyword <literal>data</literal> or <literal>newtype</literal>
+      is followed by <literal>instance</literal> and that some or all of the
+      type arguments can be non-variable types, but may not contain forall
+      types or type synonym families.  However, data families are generally
+      allowed in type parameters, and type synonyms are allowed as long as
+      they are fully applied and expand to a type that is itself admissible -
+      exactly as this is required for occurrences of type synonyms in class
+      instance parameters.  For example, the <literal>Either</literal>
+      instance for <literal>GMap</literal> is 
+<programlisting>
+data instance GMap (Either a b) v = GMapEither (GMap a v) (GMap b v)
+</programlisting>
+      In this example, the declaration has only one variant.  In general, it
+      can be any number.
+    </para>
+    <para>
+      Data and newtype instance declarations are only permitted when an
+      appropriate family declaration is in scope - just as a class instance declaratoin
+      requires the class declaration to be visible.  Moreover, each instance
+      declaration has to conform to the kind determined by its family
+      declaration.  This implies that the number of parameters of an instance
+      declaration matches the arity determined by the kind of the family.
+    </para>
+    <para>
+      A data family instance declaration can use the full exprssiveness of
+      ordinary <literal>data</literal> or <literal>newtype</literal> declarations:
+      <itemizedlist>
+      <listitem><para> Although, a data family is <emphasis>introduced</emphasis> with
+      the keyword "<literal>data</literal>", a data family <emphasis>instance</emphasis> can 
+      use either <literal>data</literal> or <literal>newtype</literal>. For example:
+<programlisting>
+data family T a
+data    instance T Int  = T1 Int | T2 Bool
+newtype instance T Char = TC Bool
+</programlisting>
+      </para></listitem>
+      <listitem><para> A <literal>data instance</literal> can use GADT syntax for the data constructors,
+      and indeed can define a GADT.  For example:
+<programlisting>
+data family G a b
+data instance G [a] b where
+   G1 :: c -> G [Int] b
+   G2 :: G [a] Bool
+</programlisting>
+      </para></listitem>
+      <listitem><para> You can use a <literal>deriving</literal> clause on a
+      <literal>data instance</literal> or <literal>newtype instance</literal>
+      declaration.
+      </para></listitem>
+      </itemizedlist>
+    </para>
+
+    <para>
+      Even if type families are defined as toplevel declarations, functions
+      that perform different computations for different family instances may still
+      need to be defined as methods of type classes.  In particular, the
+      following is not possible: 
+<programlisting>
+data family T a
+data instance T Int  = A
+data instance T Char = B
+foo :: T a -> Int
+foo A = 1             -- WRONG: These two equations together...
+foo B = 2             -- ...will produce a type error.
+</programlisting>
+Instead, you would have to write <literal>foo</literal> as a class operation, thus:
+<programlisting>
+class C a where 
+  foo :: T a -> Int
+instance Foo Int where
+  foo A = 1
+instance Foo Char where
+  foo B = 2
+</programlisting>
+      (Given the functionality provided by GADTs (Generalised Algebraic Data
+      Types), it might seem as if a definition, such as the above, should be
+      feasible.  However, type families are - in contrast to GADTs - are
+      <emphasis>open;</emphasis> i.e., new instances can always be added,
+      possibly in other 
+      modules.  Supporting pattern matching across different data instances
+      would require a form of extensible case construct.)
+    </para>
+
+    <sect4 id="assoc-data-inst">
+      <title>Associated data instances</title>
+      <para>
+       When an associated data family instance is declared within a type
+       class instance, we drop the <literal>instance</literal> keyword in the
+       family instance.  So, the <literal>Either</literal> instance
+       for <literal>GMap</literal> becomes: 
+<programlisting>
+instance (GMapKey a, GMapKey b) => GMapKey (Either a b) where
+  data GMap (Either a b) v = GMapEither (GMap a v) (GMap b v)
+  ...
+</programlisting>
+        The most important point about associated family instances is that the
+        type indexes corresponding to class parameters must be identical to
+        the type given in the instance head; here this is the first argument
+        of <literal>GMap</literal>, namely <literal>Either a b</literal>,
+        which coincides with the only class parameter.  Any parameters to the
+        family constructor that do not correspond to class parameters, need to
+        be variables in every instance; here this is the
+        variable <literal>v</literal>. 
+      </para>
+      <para>
+       Instances for an associated family can only appear as part of
+       instances declarations of the class in which the family was declared -
+       just as with the equations of the methods of a class.  Also in
+       correspondence to how methods are handled, declarations of associated
+       types can be omitted in class instances.  If an associated family
+       instance is omitted, the corresponding instance type is not inhabited;
+       i.e., only diverging expressions, such
+       as <literal>undefined</literal>, can assume the type. 
+      </para>
+    </sect4>
+
+    <sect4 id="scoping-class-params">
+      <title>Scoping of class parameters</title>
+      <para>
+       In the case of multi-parameter type classes, the visibility of class
+       parameters in the right-hand side of associated family instances
+       depends <emphasis>solely</emphasis> on the parameters of the data
+       family.  As an example, consider the simple class declaration 
+<programlisting>
+class C a b where
+  data T a
+</programlisting>
+        Only one of the two class parameters is a parameter to the data
+        family.  Hence, the following instance declaration is invalid: 
+<programlisting>
+instance C [c] d where
+  data T [c] = MkT (c, d)    -- WRONG!!  'd' is not in scope
+</programlisting>
+        Here, the right-hand side of the data instance mentions the type
+        variable <literal>d</literal> that does not occur in its left-hand
+        side.  We cannot admit such data instances as they would compromise
+        type safety. 
+      </para>
+    </sect4>
 
+    <sect4 id="family-class-inst">
+      <title>Type class instances of family instances</title>
+      <para>
+       Type class instances of instances of data families can be defined as
+       usual, and in particular data instance declarations can
+       have <literal>deriving</literal> clauses.  For example, we can write 
 <programlisting>
-  type Point = (Int,Int)
-  instance C Point   where ...
-  instance C [Point] where ...
+data GMap () v = GMapUnit (Maybe v)
+               deriving Show
+</programlisting>
+        which implicitly defines an instance of the form
+<programlisting>
+instance Show v => Show (GMap () v) where ...
 </programlisting>
+      </para>
+      <para>
+       Note that class instances are always for
+       particular <emphasis>instances</emphasis> of a data family and never
+       for an entire family as a whole.  This is for essentially the same
+       reasons that we cannot define a toplevel function that performs
+       pattern matching on the data constructors
+       of <emphasis>different</emphasis> instances of a single type family.
+       It would require a form of extensible case construct. 
+      </para>
+    </sect4>
+
+    <sect4 id="data-family-overlap">
+      <title>Overlap of data instances</title>
+      <para>
+       The instance declarations of a data family used in a single program
+       may not overlap at all, independent of whether they are associated or
+       not.  In contrast to type class instances, this is not only a matter
+       of consistency, but one of type safety. 
+      </para>
+    </sect4>
+
+  </sect3>
+
+  <sect3 id="data-family-import-export">
+    <title>Import and export</title>
+
+    <para>
+      The association of data constructors with type families is more dynamic
+      than that is the case with standard data and newtype declarations.  In
+      the standard case, the notation <literal>T(..)</literal> in an import or
+      export list denotes the type constructor and all the data constructors
+      introduced in its declaration.  However, a family declaration never
+      introduces any data constructors; instead, data constructors are
+      introduced by family instances.  As a result, which data constructors
+      are associated with a type family depends on the currently visible
+      instance declarations for that family.  Consequently, an import or
+      export item of the form <literal>T(..)</literal> denotes the family
+      constructor and all currently visible data constructors - in the case of
+      an export item, these may be either imported or defined in the current
+      module.  The treatment of import and export items that explicitly list
+      data constructors, such as <literal>GMap(GMapEither)</literal>, is
+      analogous. 
+    </para>
+
+    <sect4 id="data-family-impexp-assoc">
+      <title>Associated families</title>
+      <para>
+       As expected, an import or export item of the
+       form <literal>C(..)</literal> denotes all of the class' methods and
+       associated types.  However, when associated types are explicitly
+       listed as subitems of a class, we need some new syntax, as uppercase
+       identifiers as subitems are usually data constructors, not type
+       constructors.  To clarify that we denote types here, each associated
+       type name needs to be prefixed by the keyword <literal>type</literal>.
+       So for example, when explicitly listing the components of
+       the <literal>GMapKey</literal> class, we write <literal>GMapKey(type
+       GMap, empty, lookup, insert)</literal>. 
+      </para>
+    </sect4>
 
+    <sect4 id="data-family-impexp-examples">
+      <title>Examples</title>
+      <para>
+       Assuming our running <literal>GMapKey</literal> class example, let us
+       look at some export lists and their meaning: 
+       <itemizedlist>
+         <listitem>
+           <para><literal>module GMap (GMapKey) where...</literal>: Exports
+             just the class name.</para>
+         </listitem>
+         <listitem>
+           <para><literal>module GMap (GMapKey(..)) where...</literal>:
+             Exports the class, the associated type <literal>GMap</literal>
+             and the member
+             functions <literal>empty</literal>, <literal>lookup</literal>,
+             and <literal>insert</literal>.  None of the data constructors is 
+             exported.</para>
+         </listitem> 
+         <listitem>
+           <para><literal>module GMap (GMapKey(..), GMap(..))
+               where...</literal>: As before, but also exports all the data
+             constructors <literal>GMapInt</literal>, 
+             <literal>GMapChar</literal>,  
+             <literal>GMapUnit</literal>, <literal>GMapPair</literal>,
+             and <literal>GMapUnit</literal>.</para>
+         </listitem>
+         <listitem>
+           <para><literal>module GMap (GMapKey(empty, lookup, insert),
+           GMap(..)) where...</literal>: As before.</para>
+         </listitem>
+         <listitem>
+           <para><literal>module GMap (GMapKey, empty, lookup, insert, GMap(..))
+               where...</literal>: As before.</para>
+         </listitem>
+       </itemizedlist>
+      </para>
+      <para>
+       Finally, you can write <literal>GMapKey(type GMap)</literal> to denote
+       both the class <literal>GMapKey</literal> as well as its associated
+       type <literal>GMap</literal>.  However, you cannot
+       write <literal>GMapKey(type GMap(..))</literal> &mdash; i.e.,
+       sub-component specifications cannot be nested.  To
+       specify <literal>GMap</literal>'s data constructors, you have to list
+       it separately. 
+      </para>
+    </sect4>
+
+    <sect4 id="data-family-impexp-instances">
+      <title>Instances</title>
+      <para>
+       Family instances are implicitly exported, just like class instances.
+       However, this applies only to the heads of instances, not to the data
+       constructors an instance defines. 
+      </para>
+    </sect4>
 
-is legal.  However, if you added
+  </sect3>
 
+</sect2>
 
-<programlisting>
-  instance C (Int,Int) where ...
-</programlisting>
+<sect2 id="synonym-families">
+  <title>Synonym families</title>
 
+  <para>
+    Type families appear in two flavours: (1) they can be defined on the
+    toplevel or (2) they can appear inside type classes (in which case they
+    are known as associated type synonyms).  The former is the more general
+    variant, as it lacks the requirement for the type-indexes to coincide with
+    the class parameters.  However, the latter can lead to more clearly
+    structured code and compiler warnings if some type instances were -
+    possibly accidentally - omitted.  In the following, we always discuss the
+    general toplevel form first and then cover the additional constraints
+    placed on associated types.
+  </para>
 
-as well, then the compiler will complain about the overlapping
-(actually, identical) instance declarations.  As always, type synonyms
-must be fully applied.  You cannot, for example, write:
+  <sect3 id="type-family-declarations">
+    <title>Type family declarations</title>
 
+    <para>
+      Indexed type families are introduced by a signature, such as 
+<programlisting>
+type family Elem c :: *
+</programlisting>
+      The special <literal>family</literal> distinguishes family from standard
+      type declarations.  The result kind annotation is optional and, as
+      usual, defaults to <literal>*</literal> if omitted.  An example is 
+<programlisting>
+type family Elem c
+</programlisting>
+      Parameters can also be given explicit kind signatures if needed.  We
+      call the number of parameters in a type family declaration, the family's
+      arity, and all applications of a type family must be fully saturated
+      w.r.t. to that arity.  This requirement is unlike ordinary type synonyms
+      and it implies that the kind of a type family is not sufficient to
+      determine a family's arity, and hence in general, also insufficient to
+      determine whether a type family application is well formed.  As an
+      example, consider the following declaration: 
+<programlisting>
+type family F a b :: * -> *   -- F's arity is 2, 
+                              -- although it's overall kind is * -> * -> * -> *
+</programlisting>
+      Given this declaration the following are examples of well-formed and
+      malformed types: 
+<programlisting>
+F Char [Int]       -- OK!  Kind: * -> *
+F Char [Int] Bool  -- OK!  Kind: *
+F IO Bool          -- WRONG: kind mismatch in the first argument
+F Bool             -- WRONG: unsaturated application
+</programlisting>
+      </para>
 
+    <sect4 id="assoc-type-family-decl">
+      <title>Associated type family declarations</title>
+      <para>
+       When a type family is declared as part of a type class, we drop
+       the <literal>family</literal> special.  The <literal>Elem</literal>
+       declaration takes the following form 
 <programlisting>
-  type P a = [[a]]
-  instance Monad P where ...
+class Collects ce where
+  type Elem ce :: *
+  ...
+</programlisting>
+        The argument names of the type family must be class parameters.  Each
+        class parameter may only be used at most once per associated type, but
+        some may be omitted and they may be in an order other than in the
+        class head.  Hence, the following contrived example is admissible: 
+<programlisting>
+class C a b c where
+  type T c a :: *
 </programlisting>
+        These rules are exactly as for associated data families.
+      </para>
+    </sect4>
+  </sect3>
+
+  <sect3 id="type-instance-declarations">
+    <title>Type instance declarations</title>
+    <para>
+      Instance declarations of type families are very similar to standard type
+      synonym declarations.  The only two differences are that the
+      keyword <literal>type</literal> is followed
+      by <literal>instance</literal> and that some or all of the type
+      arguments can be non-variable types, but may not contain forall types or
+      type synonym families. However, data families are generally allowed, and
+      type synonyms are allowed as long as they are fully applied and expand
+      to a type that is admissible - these are the exact same requirements as
+      for data instances.  For example, the <literal>[e]</literal> instance
+      for <literal>Elem</literal> is 
+<programlisting>
+type instance Elem [e] = e
+</programlisting>
+    </para>
+    <para>
+      Type family instance declarations are only legitimate when an
+      appropriate family declaration is in scope - just like class instances
+      require the class declaration to be visible.  Moreover, each instance
+      declaration has to conform to the kind determined by its family
+      declaration, and the number of type parameters in an instance
+      declaration must match the number of type parameters in the family
+      declaration.   Finally, the right-hand side of a type instance must be a
+      monotype (i.e., it may not include foralls) and after the expansion of
+      all saturated vanilla type synonyms, no synonyms, except family synonyms
+      may remain.  Here are some examples of admissible and illegal type
+      instances: 
+<programlisting>
+type family F a :: *
+type instance F [Int]              = Int         -- OK!
+type instance F String             = Char        -- OK!
+type instance F (F a)              = a           -- WRONG: type parameter mentions a type family
+type instance F (forall a. (a, b)) = b           -- WRONG: a forall type appears in a type parameter
+type instance F Float              = forall a.a  -- WRONG: right-hand side may not be a forall type
+
+type family G a b :: * -> *
+type instance G Int            = (,)     -- WRONG: must be two type parameters
+type instance G Int Char Float = Double  -- WRONG: must be two type parameters
+</programlisting>
+    </para>
+
+    <sect4 id="assoc-type-instance">
+      <title>Associated type instance declarations</title>
+      <para>
+       When an associated family instance is declared within a type class
+       instance, we drop the <literal>instance</literal> keyword in the family
+       instance.  So, the <literal>[e]</literal> instance
+       for <literal>Elem</literal> becomes: 
+<programlisting>
+instance (Eq (Elem [e])) => Collects ([e]) where
+  type Elem [e] = e
+  ...
+</programlisting>
+        The most important point about associated family instances is that the
+       type indexes corresponding to class parameters must be identical to the
+        type given in the instance head; here this is <literal>[e]</literal>,
+        which coincides with the only class parameter. 
+      </para>
+      <para>
+        Instances for an associated family can only appear as part of  instances
+       declarations of the class in which the family was declared - just as
+       with the equations of the methods of a class.  Also in correspondence to
+       how methods are handled, declarations of associated types can be omitted
+       in class instances.  If an associated family instance is omitted, the
+       corresponding instance type is not inhabited; i.e., only diverging
+       expressions, such as <literal>undefined</literal>, can assume the type. 
+      </para>
+    </sect4>
+
+    <sect4 id="type-family-overlap">
+      <title>Overlap of type synonym instances</title>
+      <para>
+       The instance declarations of a type family used in a single program
+       may only overlap if the right-hand sides of the overlapping instances
+       coincide for the overlapping types.  More formally, two instance
+       declarations overlap if there is a substitution that makes the
+       left-hand sides of the instances syntactically the same.  Whenever
+       that is the case, the right-hand sides of the instances must also be
+       syntactically equal under the same substitution.  This condition is
+       independent of whether the type family is associated or not, and it is
+       not only a matter of consistency, but one of type safety. 
+      </para>
+      <para>
+       Here are two example to illustrate the condition under which overlap
+       is permitted. 
+<programlisting>
+type instance F (a, Int) = [a]
+type instance F (Int, b) = [b]   -- overlap permitted
 
+type instance G (a, Int)  = [a]
+type instance G (Char, a) = [a]  -- ILLEGAL overlap, as [Char] /= [Int]
+</programlisting>
+      </para>
+    </sect4>
+
+    <sect4 id="type-family-decidability">
+      <title>Decidability of type synonym instances</title>
+      <para>
+       In order to guarantee that type inference in the presence of type
+       families decidable, we need to place a number of additional
+       restrictions on the formation of type instance declarations (c.f.,
+       Definition 5 (Relaxed Conditions) of &ldquo;<ulink 
+        url="http://www.cse.unsw.edu.au/~chak/papers/SPCS08.html">Type
+         Checking with Open Type Functions</ulink>&rdquo;).  Instance
+         declarations have the general form 
+<programlisting>
+type instance F t1 .. tn = t
+</programlisting>
+        where we require that for every type family application <literal>(G s1
+        .. sm)</literal> in <literal>t</literal>,  
+       <orderedlist>
+         <listitem>
+           <para><literal>s1 .. sm</literal> do not contain any type family
+           constructors,</para>
+         </listitem>
+         <listitem>
+           <para>the total number of symbols (data type constructors and type
+           variables) in <literal>s1 .. sm</literal> is strictly smaller than
+           in <literal>t1 .. tn</literal>, and</para> 
+         </listitem>
+         <listitem>
+           <para>for every type
+           variable <literal>a</literal>, <literal>a</literal> occurs
+           in <literal>s1 .. sm</literal> at most as often as in <literal>t1
+           .. tn</literal>.</para>
+         </listitem>
+       </orderedlist>
+       These restrictions are easily verified and ensure termination of type
+       inference.  However, they are not sufficient to guarantee completeness
+       of type inference in the presence of, so called, ''loopy equalities'',
+       such as <literal>a ~ [F a]</literal>, where a recursive occurrence of
+       a type variable is underneath a family application and data
+       constructor application - see the above mentioned paper for details.   
+      </para>
+      <para>
+       If the option <option>-XUndecidableInstances</option> is passed to the
+       compiler, the above restrictions are not enforced and it is on the
+       programmer to ensure termination of the normalisation of type families
+       during type inference. 
+      </para>
+    </sect4>
+  </sect3>
+
+  <sect3 id-="equality-constraints">
+    <title>Equality constraints</title>
+    <para>
+      Type context can include equality constraints of the form <literal>t1 ~
+      t2</literal>, which denote that the types <literal>t1</literal>
+      and <literal>t2</literal> need to be the same.  In the presence of type
+      families, whether two types are equal cannot generally be decided
+      locally.  Hence, the contexts of function signatures may include
+      equality constraints, as in the following example: 
+<programlisting>
+sumCollects :: (Collects c1, Collects c2, Elem c1 ~ Elem c2) => c1 -> c2 -> c2
+</programlisting>
+      where we require that the element type of <literal>c1</literal>
+      and <literal>c2</literal> are the same.  In general, the
+      types <literal>t1</literal> and <literal>t2</literal> of an equality
+      constraint may be arbitrary monotypes; i.e., they may not contain any
+      quantifiers, independent of whether higher-rank types are otherwise
+      enabled. 
+    </para>
+    <para>
+      Equality constraints can also appear in class and instance contexts.
+      The former enable a simple translation of programs using functional
+      dependencies into programs using family synonyms instead.  The general
+      idea is to rewrite a class declaration of the form 
+<programlisting>
+class C a b | a -> b
+</programlisting>
+      to
+<programlisting>
+class (F a ~ b) => C a b where
+  type F a
+</programlisting>
+      That is, we represent every functional dependency (FD) <literal>a1 .. an
+      -> b</literal> by an FD type family <literal>F a1 .. an</literal> and a
+      superclass context equality <literal>F a1 .. an ~ b</literal>,
+      essentially giving a name to the functional dependency.  In class
+      instances, we define the type instances of FD families in accordance
+      with the class head.  Method signatures are not affected by that
+      process. 
+    </para>
+    <para>
+      NB: Equalities in superclass contexts are not fully implemented in
+      GHC 6.10. 
+    </para>
+  </sect3>
+
+  <sect3 id-="ty-fams-in-instances">
+    <title>Type families and instance declarations</title>
+    <para>Type families require us to extend the rules for 
+      the form of instance heads, which are given 
+      in <xref linkend="flexible-instance-head"/>.
+      Specifically:
+<itemizedlist>
+ <listitem><para>Data type families may appear in an instance head</para></listitem>
+ <listitem><para>Type synonym families may not appear (at all) in an instance head</para></listitem>
+</itemizedlist>
+The reason for the latter restriction is that there is no way to check for. Consider
+<programlisting>
+   type family F a
+   type instance F Bool = Int
 
-This design decision is independent of all the others, and easily
-reversed, but it makes sense to me.
+   class C a
 
+   instance C Int
+   instance C (F a)
+</programlisting>
+Now a constraint <literal>(C (F Bool))</literal> would match both instances.
+The situation is especially bad because the type instance for <literal>F Bool</literal>
+might be in another module, or even in a module that is not yet written.
 </para>
 </sect3>
+</sect2>
 
+</sect1>
 
-</sect2>
+<sect1 id="other-type-extensions">
+<title>Other type system extensions</title>
 
 <sect2 id="type-restrictions">
 <title>Type signatures</title>
 
-<sect3><title>The context of a type signature</title>
+<sect3 id="flexible-contexts"><title>The context of a type signature</title>
 <para>
-Unlike Haskell 98, constraints in types do <emphasis>not</emphasis> have to be of
-the form <emphasis>(class type-variable)</emphasis> or
-<emphasis>(class (type-variable type-variable ...))</emphasis>.  Thus,
+The <option>-XFlexibleContexts</option> flag lifts the Haskell 98 restriction
+that the type-class constraints in a type signature must have the 
+form <emphasis>(class type-variable)</emphasis> or
+<emphasis>(class (type-variable type-variable ...))</emphasis>. 
+With <option>-XFlexibleContexts</option>
 these type signatures are perfectly OK
 <programlisting>
   g :: Eq [a] => ...
@@ -2878,8 +4597,8 @@ in GHC, you can give the foralls if you want.  See <xref linkend="universal-quan
  <emphasis>Each universally quantified type variable
 <literal>tvi</literal> must be reachable from <literal>type</literal></emphasis>.
 
-A type variable <literal>a</literal> is "reachable" if it it appears
-in the same constraint as either a type variable free in in
+A type variable <literal>a</literal> is "reachable" if it appears
+in the same constraint as either a type variable free in
 <literal>type</literal>, or another reachable type variable.  
 A value with a type that does not obey 
 this reachability restriction cannot be used without introducing
@@ -2970,11 +4689,11 @@ J Lewis, MB Shields, E Meijer, J Launchbury,
 Boston, Jan 2000.
 </para>
 
-<para>(Most of the following, stil rather incomplete, documentation is
+<para>(Most of the following, still rather incomplete, documentation is
 due to Jeff Lewis.)</para>
 
 <para>Implicit parameter support is enabled with the option
-<option>-fimplicit-params</option>.</para>
+<option>-XImplicitParams</option>.</para>
 
 <para>
 A variable is called <emphasis>dynamically bound</emphasis> when it is bound by the calling
@@ -3150,7 +4869,7 @@ In the former case, <literal>len_acc1</literal> is monomorphic in its own
 right-hand side, so the implicit parameter <literal>?acc</literal> is not
 passed to the recursive call.  In the latter case, because <literal>len_acc2</literal>
 has a type signature, the recursive call is made to the
-<emphasis>polymoprhic</emphasis> version, which takes <literal>?acc</literal>
+<emphasis>polymorphic</emphasis> version, which takes <literal>?acc</literal>
 as an implicit parameter.  So we get the following results in GHCi:
 <programlisting>
   Prog> len1 "hello"
@@ -3275,7 +4994,7 @@ Other points:
 <itemizedlist>
 <listitem> <para> '<literal>?x</literal>' and '<literal>%x</literal>' 
 are entirely distinct implicit parameters: you 
-  can use them together and they won't intefere with each other. </para>
+  can use them together and they won't interfere with each other. </para>
 </listitem>
 
 <listitem> <para> You can bind linear implicit parameters in 'with' clauses. </para> </listitem>
@@ -3364,7 +5083,7 @@ and you'd be right.  That is why they are an experimental feature.
 
 ================ END OF Linear Implicit Parameters commented out -->
 
-<sect2 id="sec-kinding">
+<sect2 id="kinding">
 <title>Explicitly-kinded quantification</title>
 
 <para>
@@ -3382,7 +5101,10 @@ kind for the type variable <literal>cxt</literal>.
 </para>
 <para>
 GHC now instead allows you to specify the kind of a type variable directly, wherever
-a type variable is explicitly bound.  Namely:
+a type variable is explicitly bound, with the flag <option>-XKindSignatures</option>.
+</para>
+<para>
+This flag enables kind signatures in the following places:
 <itemizedlist>
 <listitem><para><literal>data</literal> declarations:
 <screen>
@@ -3476,21 +5198,31 @@ The function <literal>f3</literal> has a rank-3 type;
 it has rank-2 types on the left of a function arrow.
 </para>
 <para>
-GHC allows types of arbitrary rank; you can nest <literal>forall</literal>s
-arbitrarily deep in function arrows.   (GHC used to be restricted to rank 2, but
-that restriction has now been lifted.)
+GHC has three flags to control higher-rank types:
+<itemizedlist>
+<listitem><para>
+ <option>-XPolymorphicComponents</option>: data constructors (only) can have polymorphic argument types.
+</para></listitem>
+<listitem><para>
+ <option>-XRank2Types</option>: any function (including data constructors) can have a rank-2 type.
+</para></listitem>
+<listitem><para>
+ <option>-XRankNTypes</option>: any function (including data constructors) can have an arbitrary-rank type.
+That is,  you can nest <literal>forall</literal>s
+arbitrarily deep in function arrows.
 In particular, a forall-type (also called a "type scheme"),
 including an operational type class context, is legal:
 <itemizedlist>
 <listitem> <para> On the left or right (see <literal>f4</literal>, for example)
 of a function arrow </para> </listitem>
-<listitem> <para> On the right of a function arrow (see <xref linkend="hoist"/>) </para> </listitem>
 <listitem> <para> As the argument of a constructor, or type of a field, in a data type declaration. For
 example, any of the <literal>f1,f2,f3,g1,g2</literal> above would be valid
 field type signatures.</para> </listitem>
 <listitem> <para> As the type of an implicit parameter </para> </listitem>
 <listitem> <para> In a pattern type signature (see <xref linkend="scoped-type-variables"/>) </para> </listitem>
 </itemizedlist>
+</para></listitem>
+</itemizedlist>
 Of course <literal>forall</literal> becomes a keyword; you can't use <literal>forall</literal> as
 a type variable any more!
 </para>
@@ -3729,7 +5461,9 @@ for rank-2 types.
 <sect2 id="impredicative-polymorphism">
 <title>Impredicative polymorphism
 </title>
-<para>GHC supports <emphasis>impredicative polymorphism</emphasis>.  This means
+<para>GHC supports <emphasis>impredicative polymorphism</emphasis>, 
+enabled with <option>-XImpredicativeTypes</option>.  
+This means
 that you can call a polymorphic function at a polymorphic type, and
 parameterise data structures over polymorphic types.  For example:
 <programlisting>
@@ -3742,7 +5476,7 @@ Notice here that the <literal>Maybe</literal> type is parameterised by the
 [a])</literal>.
 </para>
 <para>The technical details of this extension are described in the paper
-<ulink url="http://research.microsoft.com/%7Esimonpj/papers/boxy">Boxy types:
+<ulink url="http://research.microsoft.com/%7Esimonpj/papers/boxy/">Boxy types:
 type inference for higher-rank types and impredicativity</ulink>,
 which appeared at ICFP 2006.  
 </para>
@@ -3762,15 +5496,19 @@ f xs = ys ++ ys
        ys :: [a]
        ys = reverse xs
 </programlisting>
-The type signature for <literal>f</literal> brings the type variable <literal>a</literal> into scope; it scopes over
-the entire definition of <literal>f</literal>.
-In particular, it is in scope at the type signature for <varname>ys</varname>. 
+The type signature for <literal>f</literal> brings the type variable <literal>a</literal> into scope,
+because of the explicit <literal>forall</literal> (<xref linkend="decl-type-sigs"/>).
+The type variables bound by a <literal>forall</literal> scope over
+the entire definition of the accompanying value declaration.
+In this example, the type variable <literal>a</literal> scopes over the whole 
+definition of <literal>f</literal>, including over
+the type signature for <varname>ys</varname>. 
 In Haskell 98 it is not possible to declare
 a type for <varname>ys</varname>; a major benefit of scoped type variables is that
 it becomes possible to do so.
 </para>
 <para>Lexically-scoped type variables are enabled by
-<option>-fglasgow-exts</option>.
+<option>-XScopedTypeVariables</option>.  This flag implies <option>-XRelaxedPolyRec</option>.
 </para>
 <para>Note: GHC 6.6 contains substantial changes to the way that scoped type
 variables work, compared to earlier releases.  Read this section
@@ -3786,7 +5524,7 @@ a <emphasis>type</emphasis>. (This is a change from GHC's earlier
 design.)</para></listitem>
 <listitem><para>Furthermore, distinct lexical type variables stand for distinct
 type variables.  This means that every programmer-written type signature
-(includin one that contains free scoped type variables) denotes a
+(including one that contains free scoped type variables) denotes a
 <emphasis>rigid</emphasis> type; that is, the type is fully known to the type
 checker, and no inference is involved.</para></listitem>
 <listitem><para>Lexical type variables may be alpha-renamed freely, without
@@ -3803,11 +5541,11 @@ A <emphasis>lexically scoped type variable</emphasis> can be bound by:
 </itemizedlist>
 </para>
 <para>
-In Haskell, a programmer-written type signature is implicitly quantifed over
+In Haskell, a programmer-written type signature is implicitly quantified over
 its free type variables (<ulink
-url="http://haskell.org/onlinereport/decls.html#sect4.1.2">Section
+url="http://www.haskell.org/onlinereport/decls.html#sect4.1.2">Section
 4.1.2</ulink> 
-of the Haskel Report).
+of the Haskell Report).
 Lexically scoped type variables affect this implicit quantification rules
 as follows: any type variable that is in scope is <emphasis>not</emphasis> universally
 quantified. For example, if type variable <literal>a</literal> is in scope,
@@ -3828,7 +5566,7 @@ then
 <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:
+type variables, in the definition of the named function.  For example:
 <programlisting>
   f :: forall a. [a] -> [a]
   f (x:xs) = xs ++ [ x :: a ]
@@ -3836,7 +5574,9 @@ type variables, in the definition of the named function(s).  For example:
 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
+<para>This only happens if:
+<itemizedlist>
+<listitem><para> The quantification in <literal>f</literal>'s type
 signature is explicit.  For example:
 <programlisting>
   g :: [a] -> [a]
@@ -3846,6 +5586,26 @@ 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></listitem>
+<listitem><para> The signature gives a type for a function binding or a bare variable binding, 
+not a pattern binding.
+For example:
+<programlisting>
+  f1 :: forall a. [a] -> [a]
+  f1 (x:xs) = xs ++ [ x :: a ]   -- OK
+
+  f2 :: forall a. [a] -> [a]
+  f2 = \(x:xs) -> xs ++ [ x :: a ]   -- OK
+
+  f3 :: forall a. [a] -> [a] 
+  Just f3 = Just (\(x:xs) -> xs ++ [ x :: a ])   -- Not OK!
+</programlisting>
+The binding for <literal>f3</literal> is a pattern binding, and so its type signature
+does not bring <literal>a</literal> into scope.   However <literal>f1</literal> is a
+function binding, and <literal>f2</literal> binds a bare variable; in both cases
+the type signature brings <literal>a</literal> into scope.
+</para></listitem>
+</itemizedlist>
 </para>
 </sect3>
 
@@ -3870,7 +5630,7 @@ type variable <literal>s</literal> into scope, in the annotated expression
 <title>Pattern type signatures</title>
 <para>
 A type signature may occur in any pattern; this is a <emphasis>pattern type
-signature</emphasis>.  
+signature</emphasis>. 
 For example:
 <programlisting>
   -- f and g assume that 'a' is already in scope
@@ -3878,14 +5638,32 @@ For example:
   g (x::a) = x
   h ((x,y) :: (Int,Bool)) = (y,x)
 </programlisting>
-In the case where all the type variables in the pattern type sigature are
+In the case where all the type variables in the pattern type signature are
 already in scope (i.e. bound by the enclosing context), matters are simple: the
 signature simply constrains the type of the pattern in the obvious way.
 </para>
 <para>
-There is only one situation in which you can write a pattern type signature that
-mentions a type variable that is not already in scope, namely in pattern match
-of an existential data constructor.  For example:
+Unlike expression and declaration type signatures, pattern type signatures are not implicitly generalised.
+The pattern in a <emphasis>pattern binding</emphasis> may only mention type variables
+that are already in scope.  For example:
+<programlisting>
+  f :: forall a. [a] -> (Int, [a])
+  f xs = (n, zs)
+    where
+      (ys::[a], n) = (reverse xs, length xs) -- OK
+      zs::[a] = xs ++ ys                     -- OK
+
+      Just (v::b) = ...  -- Not OK; b is not in scope
+</programlisting>
+Here, the pattern signatures for <literal>ys</literal> and <literal>zs</literal>
+are fine, but the one for <literal>v</literal> is not because <literal>b</literal> is
+not in scope. 
+</para>
+<para>
+However, in all patterns <emphasis>other</emphasis> than pattern bindings, a pattern
+type signature may mention a type variable that is not in scope; in this case,
+<emphasis>the signature brings that type variable into scope</emphasis>.
+This is particularly important for existential data constructors.  For example:
 <programlisting>
   data T = forall a. MkT [a]
 
@@ -3895,16 +5673,21 @@ of an existential data constructor.  For example:
                    t3::[a] = [t,t,t]
 </programlisting>
 Here, the pattern type signature <literal>(t::a)</literal> mentions a lexical type
-variable that is not already in scope.  Indeed, it cannot already be in scope,
+variable that is not already in scope.  Indeed, it <emphasis>cannot</emphasis> already be in scope,
 because it is bound by the pattern match.  GHC's rule is that in this situation
 (and only then), a pattern type signature can mention a type variable that is
 not already in scope; the effect is to bring it into scope, standing for the
 existentially-bound type variable.
 </para>
 <para>
-If this seems a little odd, we think so too.  But we must have
+When a pattern type signature binds a type variable in this way, GHC insists that the 
+type variable is bound to a <emphasis>rigid</emphasis>, or fully-known, type variable.
+This means that any user-written type signature always stands for a completely known type.
+</para>
+<para>
+If all this seems a little odd, we think so too.  But we must have
 <emphasis>some</emphasis> way to bring such type variables into scope, else we
-could not name existentially-bound type variables in subequent type signatures.
+could not name existentially-bound type variables in subsequent type signatures.
 </para>
 <para>
 This is (now) the <emphasis>only</emphasis> situation in which a pattern type 
@@ -4000,20 +5783,20 @@ scope over the methods defined in the <literal>where</literal> part.  For exampl
 The Haskell Report specifies that a group of bindings (at top level, or in a
 <literal>let</literal> or <literal>where</literal>) should be sorted into
 strongly-connected components, and then type-checked in dependency order
-(<ulink url="http://haskell.org/onlinereport/decls.html#sect4.5.1">Haskell
+(<ulink url="http://www.haskell.org/onlinereport/decls.html#sect4.5.1">Haskell
 Report, Section 4.5.1</ulink>).  
 As each group is type-checked, any binders of the group that
 have
 an explicit type signature are put in the type environment with the specified
 polymorphic type,
 and all others are monomorphic until the group is generalised 
-(<ulink url="http://haskell.org/onlinereport/decls.html#sect4.5.2">Haskell Report, Section 4.5.2</ulink>).
+(<ulink url="http://www.haskell.org/onlinereport/decls.html#sect4.5.2">Haskell Report, Section 4.5.2</ulink>).
 </para>
 
 <para>Following a suggestion of Mark Jones, in his paper
-<ulink url="http://www.cse.ogi.edu/~mpj/thih/">Typing Haskell in
+<ulink url="http://citeseer.ist.psu.edu/424440.html">Typing Haskell in
 Haskell</ulink>,
-GHC implements a more general scheme.  If <option>-fglasgow-exts</option> is
+GHC implements a more general scheme.  If <option>-XRelaxedPolyRec</option> is
 specified:
 <emphasis>the dependency analysis ignores references to variables that have an explicit
 type signature</emphasis>.
@@ -4029,12 +5812,12 @@ This is rejected by Haskell 98, but under Jones's scheme the definition for
 <literal>g</literal> is typechecked first, separately from that for
 <literal>f</literal>,
 because the reference to <literal>f</literal> in <literal>g</literal>'s right
-hand side is ingored by the dependency analysis.  Then <literal>g</literal>'s
+hand side is ignored by the dependency analysis.  Then <literal>g</literal>'s
 type is generalised, to get
 <programlisting>
   g :: Ord a =&gt; a -> Bool
 </programlisting>
-Now, the defintion for <literal>f</literal> is typechecked, with this type for
+Now, the definition for <literal>f</literal> is typechecked, with this type for
 <literal>g</literal> in the type environment.
 </para>
 
@@ -4042,7 +5825,7 @@ Now, the defintion for <literal>f</literal> is typechecked, with this type for
 The same refined dependency analysis also allows the type signatures of 
 mutually-recursive functions to have different contexts, something that is illegal in
 Haskell 98 (Section 4.5.2, last sentence).  With
-<option>-fglasgow-exts</option>
+<option>-XRelaxedPolyRec</option>
 GHC only insists that the type signatures of a <emphasis>refined</emphasis> group have identical
 type signatures; in practice this means that only variables bound by the same
 pattern binding must have the same context.  For example, this is fine:
@@ -4068,30 +5851,33 @@ pattern binding must have the same context.  For example, this is fine:
 Haskell.  
 The background to
 the main technical innovations is discussed in "<ulink
-url="http://research.microsoft.com/~simonpj/papers/meta-haskell">
+url="http://research.microsoft.com/~simonpj/papers/meta-haskell/">
 Template Meta-programming for Haskell</ulink>" (Proc Haskell Workshop 2002).
 </para>
 <para>
 There is a Wiki page about
-Template Haskell at <ulink url="http://haskell.org/haskellwiki/Template_Haskell">
-http://www.haskell.org/th/</ulink>, and that is the best place to look for
+Template Haskell at <ulink url="http://www.haskell.org/haskellwiki/Template_Haskell">
+http://www.haskell.org/haskellwiki/Template_Haskell</ulink>, and that is the best place to look for
 further details.
 You may also 
 consult the <ulink
 url="http://www.haskell.org/ghc/docs/latest/html/libraries/index.html">online
 Haskell library reference material</ulink> 
-(search for the type ExpQ).
-[Temporary: many changes to the original design are described in 
-      <ulink url="http://research.microsoft.com/~simonpj/tmp/notes2.ps">"http://research.microsoft.com/~simonpj/tmp/notes2.ps"</ulink>.
-Not all of these changes are in GHC 6.6.]
+(look for module <literal>Language.Haskell.TH</literal>).
+Many changes to the original design are described in 
+      <ulink url="http://research.microsoft.com/~simonpj/papers/meta-haskell/notes2.ps">
+Notes on Template Haskell version 2</ulink>.
+Not all of these changes are in GHC, however.
 </para>
 
-<para> The first example from that paper is set out below as a worked example to help get you started. 
+<para> The first example from that paper is set out below (<xref linkend="th-example"/>) 
+as a worked example to help get you started. 
 </para>
 
 <para>
-The documentation here describes the realisation in GHC.  (It's rather sketchy just now;
-Tim Sheard is going to expand it.)
+The documentation here describes the realisation of Template Haskell in GHC.  It is not detailed enough to 
+understand Template Haskell; see the <ulink url="http://haskell.org/haskellwiki/Template_Haskell">
+Wiki page</ulink>.
 </para>
 
     <sect2>
@@ -4099,9 +5885,10 @@ Tim Sheard is going to expand it.)
 
       <para> Template Haskell has the following new syntactic
       constructions.  You need to use the flag
-      <option>-fth</option><indexterm><primary><option>-fth</option></primary>
+      <option>-XTemplateHaskell</option>
+       <indexterm><primary><option>-XTemplateHaskell</option></primary>
       </indexterm>to switch these syntactic extensions on
-      (<option>-fth</option> is no longer implied by
+      (<option>-XTemplateHaskell</option> is no longer implied by
       <option>-fglasgow-exts</option>).</para>
 
        <itemizedlist>
@@ -4116,41 +5903,58 @@ Tim Sheard is going to expand it.)
                  <itemizedlist>
                    <listitem><para> an expression; the spliced expression must
                    have type <literal>Q Exp</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> [Planned, but not implemented yet.] a
-                   type; the spliced expression must have type <literal>Q Typ</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>
                    </itemizedlist>
-          (Note that the syntax for a declaration splice uses "<literal>$</literal>" not "<literal>splice</literal>" as in
-       the paper. Also the type of the enclosed expression must be  <literal>Q [Dec]</literal>, not  <literal>[Q Dec]</literal>
-       as in the paper.)
-               </para></listitem>
+               </para>
+           Inside a splice you can can only call functions defined in imported modules,
+       not functions defined elsewhere in the same module.</listitem>
 
 
              <listitem><para>
                  A expression quotation is written in Oxford brackets, thus:
                  <itemizedlist>
                    <listitem><para> <literal>[| ... |]</literal>, where the "..." is an expression; 
-                             the quotation has type <literal>Expr</literal>.</para></listitem>
+                             the quotation has type <literal>Q Exp</literal>.</para></listitem>
                    <listitem><para> <literal>[d| ... |]</literal>, where the "..." is a list of top-level declarations;
                              the quotation has type <literal>Q [Dec]</literal>.</para></listitem>
-                   <listitem><para>  [Planned, but not implemented yet.]  <literal>[t| ... |]</literal>, where the "..." is a type; 
-                             the quotation has type <literal>Type</literal>.</para></listitem>
+                   <listitem><para> <literal>[t| ... |]</literal>, where the "..." is a type;
+                             the quotation has type <literal>Q Typ</literal>.</para></listitem>
+                 </itemizedlist></para></listitem>
+
+             <listitem><para>
+                 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>,
+                        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>
 
              <listitem><para>
-                 Reification is written thus:
+                 A name can be quoted with either one or two prefix single quotes:
                  <itemizedlist>
-                   <listitem><para> <literal>reifyDecl T</literal>, where <literal>T</literal> is a type constructor; this expression
-                     has type <literal>Dec</literal>. </para></listitem>
-                   <listitem><para> <literal>reifyDecl C</literal>, where <literal>C</literal> is a class; has type <literal>Dec</literal>.</para></listitem>
-                   <listitem><para> <literal>reifyType f</literal>, where <literal>f</literal> is an identifier; has type <literal>Typ</literal>.</para></listitem>
-                   <listitem><para> Still to come: fixities </para></listitem>
-                   
-                 </itemizedlist></para>
+                   <listitem><para> <literal>'f</literal> has type <literal>Name</literal>, and names the function <literal>f</literal>.
+                 Similarly <literal>'C</literal> has type <literal>Name</literal> and names the data constructor <literal>C</literal>.
+                 In general <literal>'</literal><replaceable>thing</replaceable> interprets <replaceable>thing</replaceable> in an expression context.
+                    </para></listitem> 
+                   <listitem><para> <literal>''T</literal> has type <literal>Name</literal>, and names the type constructor  <literal>T</literal>.
+                 That is, <literal>''</literal><replaceable>thing</replaceable> interprets <replaceable>thing</replaceable> in a type context.
+                    </para></listitem> 
+                 </itemizedlist>
+                 These <literal>Names</literal> can be used to construct Template Haskell expressions, patterns, declarations etc.  They
+                 may also be given as an argument to the <literal>reify</literal> function.
+                </para>
                </listitem>
 
                  
        </itemizedlist>
+(Compared to the original paper, there are many differences of detail.
+The syntax for a declaration splice uses "<literal>$</literal>" not "<literal>splice</literal>".
+The type of the enclosed expression must be  <literal>Q [Dec]</literal>, not  <literal>[Q Dec]</literal>.
+Pattern splices and quotations are not implemented.)
+
 </sect2>
 
 <sect2>  <title> Using Template Haskell </title>
@@ -4167,6 +5971,18 @@ Tim Sheard is going to expand it.)
            (It would make sense to do so, but it's hard to implement.)
    </para></listitem>
 
+   <listitem><para>
+   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>.  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>
+
     <listitem><para>
            The flag <literal>-ddump-splices</literal> shows the expansion of all top-level splices as they happen.
    </para></listitem>
@@ -4185,7 +6001,7 @@ Tim Sheard is going to expand it.)
 </para>
 </sect2>
  
-<sect2>  <title> A Template Haskell Worked Example </title>
+<sect2 id="th-example">  <title> A Template Haskell Worked Example </title>
 <para>To help you get over the confidence barrier, try out this skeletal worked example.
   First cut and paste the two modules below into "Main.hs" and "Printf.hs":</para>
 
@@ -4225,21 +6041,21 @@ parse s   = [ L s ]
 -- Generate Haskell source code from a parsed representation
 -- of the format string.  This code will be spliced into
 -- the module which calls "pr", at compile time.
-gen :: [Format] -> ExpQ
+gen :: [Format] -> Q Exp
 gen [D]   = [| \n -> show n |]
 gen [S]   = [| \s -> s |]
 gen [L s] = stringE s
 
 -- Here we generate the Haskell code for the splice
 -- from an input format string.
-pr :: String -> ExpQ
-pr s      = gen (parse s)
+pr :: String -> Q Exp
+pr s = gen (parse s)
 </programlisting>
 
 <para>Now run the compiler (here we are a Cygwin prompt on Windows):
 </para>
 <programlisting>
-$ ghc --make -fth main.hs -o main.exe
+$ ghc --make -XTemplateHaskell main.hs -o main.exe
 </programlisting>
 
 <para>Run "main.exe" and here is your output:</para>
@@ -4280,7 +6096,7 @@ The basic idea is to compile the program twice:</para>
   <para>Then compile it again with <option>-prof</option>, and
   additionally use <option>-osuf
   p_o</option><indexterm><primary><option>-osuf</option></primary></indexterm>
-  to name the object files differentliy (you can choose any suffix
+  to name the object files differently (you can choose any suffix
   that isn't the normal object suffix here).  GHC will automatically
   load the object files built in the first step when executing splice
   expressions.  If you omit the <option>-osuf</option> flag when
@@ -4290,6 +6106,124 @@ The basic idea is to compile the program twice:</para>
 </orderedlist>
 </sect2>
 
+<sect2 id="th-quasiquotation">  <title> Template Haskell Quasi-quotation </title>
+<para>Quasi-quotation allows patterns and expressions to be written using
+programmer-defined concrete syntax; the motivation behind the extension and
+several examples are documented in
+"<ulink url="http://www.eecs.harvard.edu/~mainland/ghc-quasiquoting/">Why It's
+Nice to be Quoted: Quasiquoting for Haskell</ulink>" (Proc Haskell Workshop
+2007). The example below shows how to write a quasiquoter for a simple
+expression language.</para>
+
+<para>
+In the example, the quasiquoter <literal>expr</literal> is bound to a value of
+type <literal>Language.Haskell.TH.Quote.QuasiQuoter</literal> which contains two
+functions for quoting expressions and patterns, respectively. The first argument
+to each quoter is the (arbitrary) string enclosed in the Oxford brackets. The
+context of the quasi-quotation statement determines which of the two parsers is
+called: if the quasi-quotation occurs in an expression context, the expression
+parser is called, and if it occurs in a pattern context, the pattern parser is
+called.</para>
+
+<para>
+Note that in the example we make use of an antiquoted
+variable <literal>n</literal>, indicated by the syntax <literal>'int:n</literal>
+(this syntax for anti-quotation was defined by the parser's
+author, <emphasis>not</emphasis> by GHC). This binds <literal>n</literal> to the
+integer value argument of the constructor <literal>IntExpr</literal> when
+pattern matching. Please see the referenced paper for further details regarding
+anti-quotation as well as the description of a technique that uses SYB to
+leverage a single parser of type <literal>String -> a</literal> to generate both
+an expression parser that returns a value of type <literal>Q Exp</literal> and a
+pattern parser that returns a value of type <literal>Q Pat</literal>.
+</para>
+
+<para>In general, a quasi-quote has the form
+<literal>[$<replaceable>quoter</replaceable>| <replaceable>string</replaceable> |]</literal>.
+The <replaceable>quoter</replaceable> must be the name of an imported quoter; it
+cannot be an arbitrary expression.  The quoted <replaceable>string</replaceable> 
+can be arbitrary, and may contain newlines.
+</para>
+<para>
+Quasiquoters must obey the same stage restrictions as Template Haskell, e.g., in
+the example, <literal>expr</literal> cannot be defined
+in <literal>Main.hs</literal> where it is used, but must be imported.
+</para>
+
+<programlisting>
+
+{- Main.hs -}
+module Main where
+
+import Expr
+
+main :: IO ()
+main = do { print $ eval [$expr|1 + 2|]
+          ; case IntExpr 1 of
+              { [$expr|'int:n|] -> print n
+              ;  _              -> return ()
+              }
+          }
+
+
+{- Expr.hs -}
+module Expr where
+
+import qualified Language.Haskell.TH as TH
+import Language.Haskell.TH.Quote
+
+data Expr  =  IntExpr Integer
+           |  AntiIntExpr String
+           |  BinopExpr BinOp Expr Expr
+           |  AntiExpr String
+    deriving(Show, Typeable, Data)
+
+data BinOp  =  AddOp
+            |  SubOp
+            |  MulOp
+            |  DivOp
+    deriving(Show, Typeable, Data)
+
+eval :: Expr -> Integer
+eval (IntExpr n)        = n
+eval (BinopExpr op x y) = (opToFun op) (eval x) (eval y)
+  where
+    opToFun AddOp = (+)
+    opToFun SubOp = (-)
+    opToFun MulOp = (*)
+    opToFun DivOp = div
+
+expr = QuasiQuoter parseExprExp parseExprPat
+
+-- Parse an Expr, returning its representation as
+-- either a Q Exp or a Q Pat. See the referenced paper
+-- for how to use SYB to do this by writing a single
+-- parser of type String -> Expr instead of two
+-- separate parsers.
+
+parseExprExp :: String -> Q Exp
+parseExprExp ...
+
+parseExprPat :: String -> Q Pat
+parseExprPat ...
+</programlisting>
+
+<para>Now run the compiler:
+</para>
+<programlisting>
+$ ghc --make -XQuasiQuotes Main.hs -o main
+</programlisting>
+
+<para>Run "main" and here is your output:</para>
+
+<programlisting>
+$ ./main
+3
+1
+</programlisting>
+
+</sect2>
+
 </sect1>
 
 <!-- ===================== Arrow notation ===================  -->
@@ -4307,6 +6241,8 @@ For more details, see
 &ldquo;Generalising Monads to Arrows&rdquo;,
 John Hughes, in <citetitle>Science of Computer Programming</citetitle> 37,
 pp67&ndash;111, May 2000.
+The paper that introduced arrows: a friendly introduction, motivated with
+programming examples.
 </para>
 </listitem>
 
@@ -4314,6 +6250,7 @@ pp67&ndash;111, May 2000.
 <para>
 &ldquo;<ulink url="http://www.soi.city.ac.uk/~ross/papers/notation.html">A New Notation for Arrows</ulink>&rdquo;,
 Ross Paterson, in <citetitle>ICFP</citetitle>, Sep 2001.
+Introduced the notation described here.
 </para>
 </listitem>
 
@@ -4325,17 +6262,42 @@ Palgrave, 2003.
 </para>
 </listitem>
 
-</itemizedlist>
-and the arrows web page at
+<listitem>
+<para>
+&ldquo;<ulink url="http://www.cs.chalmers.se/~rjmh/afp-arrows.pdf">Programming with Arrows</ulink>&rdquo;,
+John Hughes, in <citetitle>5th International Summer School on
+Advanced Functional Programming</citetitle>,
+<citetitle>Lecture Notes in Computer Science</citetitle> vol. 3622,
+Springer, 2004.
+This paper includes another introduction to the notation,
+with practical examples.
+</para>
+</listitem>
+
+<listitem>
+<para>
+&ldquo;<ulink url="http://www.haskell.org/ghc/docs/papers/arrow-rules.pdf">Type and Translation Rules for Arrow Notation in GHC</ulink>&rdquo;,
+Ross Paterson and Simon Peyton Jones, September 16, 2004.
+A terse enumeration of the formal rules used
+(extracted from comments in the source code).
+</para>
+</listitem>
+
+<listitem>
+<para>
+The arrows web page at
 <ulink url="http://www.haskell.org/arrows/"><literal>http://www.haskell.org/arrows/</literal></ulink>.
-With the <option>-farrows</option> flag, GHC supports the arrow
-notation described in the second of these papers.
-What follows is a brief introduction to the notation;
-it won't make much sense unless you've read Hughes's paper.
-This notation is translated to ordinary Haskell,
-using combinators from the
+</para>
+</listitem>
+
+</itemizedlist>
+With the <option>-XArrows</option> flag, GHC supports the arrow
+notation described in the second of these papers,
+translating it using combinators from the
 <ulink url="../libraries/base/Control-Arrow.html"><literal>Control.Arrow</literal></ulink>
 module.
+What follows is a brief introduction to the notation;
+it won't make much sense unless you've read Hughes's paper.
 </para>
 
 <para>The extension adds a new kind of expression for defining arrows:
@@ -4609,7 +6571,8 @@ We could define our own operator
 <programlisting>
 untilA :: ArrowChoice a => a e () -> a e Bool -> a e ()
 untilA body cond = proc x ->
-        if cond x then returnA -&lt; ()
+        b &lt;- cond -&lt; x
+        if b then returnA -&lt; ()
         else do
                 body -&lt; x
                 untilA body cond -&lt; x
@@ -4786,22 +6749,33 @@ Because the preprocessor targets Haskell (rather than Core),
 
 <!-- ==================== BANG PATTERNS =================  -->
 
-<sect1 id="sec-bang-patterns">
+<sect1 id="bang-patterns">
 <title>Bang patterns
 <indexterm><primary>Bang patterns</primary></indexterm>
 </title>
 <para>GHC supports an extension of pattern matching called <emphasis>bang
-patterns</emphasis>.   Bang patterns are under consideration for Haskell Prime.
+patterns</emphasis>, written <literal>!<replaceable>pat</replaceable></literal>.   
+Bang patterns are under consideration for Haskell Prime.
 The <ulink
 url="http://hackage.haskell.org/trac/haskell-prime/wiki/BangPatterns">Haskell
 prime feature description</ulink> contains more discussion and examples
 than the material below.
 </para>
 <para>
-Bang patterns are enabled by the flag <option>-fbang-patterns</option>.
+The key change is the addition of a new rule to the 
+<ulink url="http://haskell.org/onlinereport/exps.html#sect3.17.2">semantics of pattern matching in the Haskell 98 report</ulink>.
+Add new bullet 10, saying: Matching the pattern <literal>!</literal><replaceable>pat</replaceable> 
+against a value <replaceable>v</replaceable> behaves as follows:
+<itemizedlist>
+<listitem><para>if <replaceable>v</replaceable> is bottom, the match diverges</para></listitem>
+<listitem><para>otherwise, <replaceable>pat</replaceable> is matched against <replaceable>v</replaceable>  </para></listitem>
+</itemizedlist>
+</para>
+<para>
+Bang patterns are enabled by the flag <option>-XBangPatterns</option>.
 </para>
 
-<sect2 id="sec-bang-patterns-informal">
+<sect2 id="bang-patterns-informal">
 <title>Informal description of bang patterns
 </title>
 <para>
@@ -4828,9 +6802,40 @@ A bang only really has an effect if it precedes a variable or wild-card pattern:
 f3 !(x,y) = [x,y]
 f4 (x,y)  = [x,y]
 </programlisting>
-Here, <literal>f3</literal> and <literal>f4</literal> are identical; putting a bang before a pattern that
+Here, <literal>f3</literal> and <literal>f4</literal> are identical; 
+putting a bang before a pattern that
 forces evaluation anyway does nothing.
-</para><para>
+</para>
+<para>
+There is one (apparent) exception to this general rule that a bang only
+makes a difference when it precedes a variable or wild-card: a bang at the
+top level of a <literal>let</literal> or <literal>where</literal>
+binding makes the binding strict, regardless of the pattern. For example:
+<programlisting>
+let ![x,y] = e in b
+</programlisting>
+is a strict binding: operationally, it evaluates <literal>e</literal>, matches
+it against the pattern <literal>[x,y]</literal>, and then evaluates <literal>b</literal>.
+(We say "apparent" exception because the Right Way to think of it is that the bang
+at the top of a binding is not part of the <emphasis>pattern</emphasis>; rather it
+is part of the syntax of the <emphasis>binding</emphasis>.)
+Nested bangs in a pattern binding behave uniformly with all other forms of 
+pattern matching.  For example
+<programlisting>
+let (!x,[y]) = e in b
+</programlisting>
+is equivalent to this:
+<programlisting>
+let { t = case e of (x,[y]) -> x `seq` (x,y)
+      x = fst t
+      y = snd t }
+in b
+</programlisting>
+The binding is lazy, but when either <literal>x</literal> or <literal>y</literal> is
+evaluated by <literal>b</literal> the entire pattern is matched, including forcing the
+evaluation of <literal>x</literal>.
+</para>
+<para>
 Bang patterns work in <literal>case</literal> expressions too, of course:
 <programlisting>
 g5 x = let y = f x in body
@@ -4838,25 +6843,13 @@ g6 x = case f x of { y -&gt; body }
 g7 x = case f x of { !y -&gt; body }
 </programlisting>
 The functions <literal>g5</literal> and <literal>g6</literal> mean exactly the same thing.  
-But <literal>g7</literal> evalutes <literal>(f x)</literal>, binds <literal>y</literal> to the
+But <literal>g7</literal> evaluates <literal>(f x)</literal>, binds <literal>y</literal> to the
 result, and then evaluates <literal>body</literal>.
-</para><para>
-Bang patterns work in <literal>let</literal> and <literal>where</literal>
-definitions too. For example:
-<programlisting>
-let ![x,y] = e in b
-</programlisting>
-is a strict pattern: operationally, it evaluates <literal>e</literal>, matches
-it against the pattern <literal>[x,y]</literal>, and then evaluates <literal>b</literal>
-The "<literal>!</literal>" should not be regarded as part of the pattern; after all,
-in a function argument <literal>![x,y]</literal> means the 
-same as <literal>[x,y]</literal>.  Rather, the "<literal>!</literal>" 
-is part of the syntax of <literal>let</literal> bindings.
 </para>
 </sect2>
 
 
-<sect2 id="sec-bang-patterns-sem">
+<sect2 id="bang-patterns-sem">
 <title>Syntax and semantics
 </title>
 <para>
@@ -4878,7 +6871,7 @@ prefix notation:
 (!) f x = 3
 </programlisting>
 The semantics of Haskell pattern matching is described in <ulink
-url="http://haskell.org/onlinereport/exps.html#sect3.17.2">
+url="http://www.haskell.org/onlinereport/exps.html#sect3.17.2">
 Section 3.17.2</ulink> of the Haskell Report.  To this description add 
 one extra item 10, saying:
 <itemizedlist><listitem><para>Matching
@@ -4888,7 +6881,7 @@ the pattern <literal>!pat</literal> against a value <literal>v</literal> behaves
                <literal>v</literal></para></listitem>
 </itemizedlist>
 </para></listitem></itemizedlist>
-Similarly, in Figure 4 of  <ulink url="http://haskell.org/onlinereport/exps.html#sect3.17.3">
+Similarly, in Figure 4 of  <ulink url="http://www.haskell.org/onlinereport/exps.html#sect3.17.3">
 Section 3.17.3</ulink>, add a new case (t):
 <programlisting>
 case v of { !pat -> e; _ -> e' }
@@ -4896,7 +6889,7 @@ case v of { !pat -> e; _ -> e' }
 </programlisting>
 </para><para>
 That leaves let expressions, whose translation is given in 
-<ulink url="http://haskell.org/onlinereport/exps.html#sect3.12">Section
+<ulink url="http://www.haskell.org/onlinereport/exps.html#sect3.12">Section
 3.12</ulink>
 of the Haskell Report.
 In the translation box, first apply 
@@ -4930,7 +6923,7 @@ a module.
 
 <!-- ==================== ASSERTIONS =================  -->
 
-<sect1 id="sec-assertions">
+<sect1 id="assertions">
 <title>Assertions
 <indexterm><primary>Assertions</primary></indexterm>
 </title>
@@ -4998,123 +6991,204 @@ can still define and use your own versions of
 <function>assert</function> in your code.
 </para>
 
-<para>
-GHC ignores assertions when optimisation is turned on with the
-      <option>-O</option><indexterm><primary><option>-O</option></primary></indexterm> flag.  That is, expressions of the form
-<literal>assert pred e</literal> will be rewritten to
-<literal>e</literal>.  You can also disable assertions using the
-      <option>-fignore-asserts</option>
-      option<indexterm><primary><option>-fignore-asserts</option></primary>
-      </indexterm>.</para>
+<para>
+GHC ignores assertions when optimisation is turned on with the
+      <option>-O</option><indexterm><primary><option>-O</option></primary></indexterm> flag.  That is, expressions of the form
+<literal>assert pred e</literal> will be rewritten to
+<literal>e</literal>.  You can also disable assertions using the
+      <option>-fignore-asserts</option>
+      option<indexterm><primary><option>-fignore-asserts</option></primary>
+      </indexterm>.</para>
+
+<para>
+Assertion failures can be caught, see the documentation for the
+<literal>Control.Exception</literal> library for the details.
+</para>
+
+</sect1>
+
+
+<!-- =============================== PRAGMAS ===========================  -->
+
+  <sect1 id="pragmas">
+    <title>Pragmas</title>
+
+    <indexterm><primary>pragma</primary></indexterm>
+
+    <para>GHC supports several pragmas, or instructions to the
+    compiler placed in the source code.  Pragmas don't normally affect
+    the meaning of the program, but they might affect the efficiency
+    of the generated code.</para>
+
+    <para>Pragmas all take the form
+
+<literal>{-# <replaceable>word</replaceable> ... #-}</literal>  
+
+    where <replaceable>word</replaceable> indicates the type of
+    pragma, and is followed optionally by information specific to that
+    type of pragma.  Case is ignored in
+    <replaceable>word</replaceable>.  The various values for
+    <replaceable>word</replaceable> that GHC understands are described
+    in the following sections; any pragma encountered with an
+    unrecognised <replaceable>word</replaceable> is
+    ignored. The layout rule applies in pragmas, so the closing <literal>#-}</literal>
+    should start in a column to the right of the opening <literal>{-#</literal>. </para> 
+
+    <para>Certain pragmas are <emphasis>file-header pragmas</emphasis>:
+      <itemizedlist>
+      <listitem><para>
+         A file-header
+         pragma must precede the <literal>module</literal> keyword in the file.
+         </para></listitem>
+      <listitem><para>
+      There can be as many file-header pragmas as you please, and they can be
+      preceded or followed by comments.  
+         </para></listitem>
+      <listitem><para>
+      File-header pragmas are read once only, before
+      pre-processing the file (e.g. with cpp).
+         </para></listitem>
+      <listitem><para>
+         The file-header pragmas are: <literal>{-# LANGUAGE #-}</literal>,
+       <literal>{-# OPTIONS_GHC #-}</literal>, and
+       <literal>{-# INCLUDE #-}</literal>.
+         </para></listitem>
+      </itemizedlist>
+      </para>
+
+    <sect2 id="language-pragma">
+      <title>LANGUAGE pragma</title>
+
+      <indexterm><primary>LANGUAGE</primary><secondary>pragma</secondary></indexterm>
+      <indexterm><primary>pragma</primary><secondary>LANGUAGE</secondary></indexterm>
+
+      <para>The <literal>LANGUAGE</literal> pragma allows language extensions to be enabled 
+       in a portable way.
+       It is the intention that all Haskell compilers support the
+       <literal>LANGUAGE</literal> pragma with the same syntax, although not
+       all extensions are supported by all compilers, of
+       course.  The <literal>LANGUAGE</literal> pragma should be used instead
+       of <literal>OPTIONS_GHC</literal>, if possible.</para>
+
+      <para>For example, to enable the FFI and preprocessing with CPP:</para>
+
+<programlisting>{-# LANGUAGE ForeignFunctionInterface, CPP #-}</programlisting>
+
+        <para><literal>LANGUAGE</literal> is a file-header pragma (see <xref linkend="pragmas"/>).</para>
+
+      <para>Every language extension can also be turned into a command-line flag
+       by prefixing it with "<literal>-X</literal>"; for example <option>-XForeignFunctionInterface</option>.
+       (Similarly, all "<literal>-X</literal>" flags can be written as <literal>LANGUAGE</literal> pragmas.
+      </para>
 
-<para>
-Assertion failures can be caught, see the documentation for the
-<literal>Control.Exception</literal> library for the details.
-</para>
+      <para>A list of all supported language extensions can be obtained by invoking
+       <literal>ghc --supported-languages</literal> (see <xref linkend="modes"/>).</para>
 
-</sect1>
+      <para>Any extension from the <literal>Extension</literal> type defined in
+       <ulink
+         url="../libraries/Cabal/Language-Haskell-Extension.html"><literal>Language.Haskell.Extension</literal></ulink>
+       may be used.  GHC will report an error if any of the requested extensions are not supported.</para>
+    </sect2>
 
 
-<!-- =============================== PRAGMAS ===========================  -->
+    <sect2 id="options-pragma">
+      <title>OPTIONS_GHC pragma</title>
+      <indexterm><primary>OPTIONS_GHC</primary>
+      </indexterm>
+      <indexterm><primary>pragma</primary><secondary>OPTIONS_GHC</secondary>
+      </indexterm>
 
-  <sect1 id="pragmas">
-    <title>Pragmas</title>
+      <para>The <literal>OPTIONS_GHC</literal> pragma is used to specify
+      additional options that are given to the compiler when compiling
+      this source file.  See <xref linkend="source-file-options"/> for
+      details.</para>
 
-    <indexterm><primary>pragma</primary></indexterm>
+      <para>Previous versions of GHC accepted <literal>OPTIONS</literal> rather
+       than <literal>OPTIONS_GHC</literal>, but that is now deprecated.</para>
+    </sect2>
 
-    <para>GHC supports several pragmas, or instructions to the
-    compiler placed in the source code.  Pragmas don't normally affect
-    the meaning of the program, but they might affect the efficiency
-    of the generated code.</para>
+        <para><literal>OPTIONS_GHC</literal> is a file-header pragma (see <xref linkend="pragmas"/>).</para>
 
-    <para>Pragmas all take the form
+    <sect2 id="include-pragma">
+      <title>INCLUDE pragma</title>
 
-<literal>{-# <replaceable>word</replaceable> ... #-}</literal>  
+      <para>The <literal>INCLUDE</literal> pragma is for specifying the names
+       of C header files that should be <literal>#include</literal>'d into
+       the C source code generated by the compiler for the current module (if
+       compiling via C).  For example:</para>
 
-    where <replaceable>word</replaceable> indicates the type of
-    pragma, and is followed optionally by information specific to that
-    type of pragma.  Case is ignored in
-    <replaceable>word</replaceable>.  The various values for
-    <replaceable>word</replaceable> that GHC understands are described
-    in the following sections; any pragma encountered with an
-    unrecognised <replaceable>word</replaceable> is (silently)
-    ignored.</para>
+<programlisting>
+{-# INCLUDE "foo.h" #-}
+{-# INCLUDE &lt;stdio.h&gt; #-}</programlisting>
 
-    <sect2 id="deprecated-pragma">
-      <title>DEPRECATED pragma</title>
-      <indexterm><primary>DEPRECATED</primary>
-      </indexterm>
+        <para><literal>INCLUDE</literal> is a file-header pragma (see <xref linkend="pragmas"/>).</para>
+
+      <para>An <literal>INCLUDE</literal> pragma is  the preferred alternative
+       to the <option>-#include</option> option (<xref
+         linkend="options-C-compiler" />), because the
+       <literal>INCLUDE</literal> pragma is understood by other
+       compilers.  Yet another alternative is to add the include file to each
+       <literal>foreign import</literal> declaration in your code, but we
+       don't recommend using this approach with GHC.</para>
+    </sect2>
+
+    <sect2 id="warning-deprecated-pragma">
+      <title>WARNING and DEPRECATED pragmas</title>
+      <indexterm><primary>WARNING</primary></indexterm>
+      <indexterm><primary>DEPRECATED</primary></indexterm>
 
-      <para>The DEPRECATED pragma lets you specify that a particular
-      function, class, or type, is deprecated.  There are two
-      forms.
+      <para>The WARNING pragma allows you to attach an arbitrary warning
+      to a particular function, class, or type.
+      A DEPRECATED pragma lets you specify that
+      a particular function, class, or type is deprecated.
+      There are two ways of using these pragmas.
 
       <itemizedlist>
        <listitem>
-         <para>You can deprecate an entire module thus:</para>
+         <para>You can work on an entire module thus:</para>
 <programlisting>
    module Wibble {-# DEPRECATED "Use Wobble instead" #-} where
      ...
 </programlisting>
+      <para>Or:</para>
+<programlisting>
+   module Wibble {-# WARNING "This is an unstable interface." #-} where
+     ...
+</programlisting>
          <para>When you compile any module that import
           <literal>Wibble</literal>, GHC will print the specified
           message.</para>
        </listitem>
 
        <listitem>
-         <para>You can deprecate a function, class, type, or data constructor, with the
-         following top-level declaration:</para>
+         <para>You can attach a warning to a function, class, type, or data constructor, with the
+         following top-level declarations:</para>
 <programlisting>
    {-# DEPRECATED f, C, T "Don't use these" #-}
+   {-# WARNING unsafePerformIO "This is unsafe; I hope you know what you're doing" #-}
 </programlisting>
          <para>When you compile any module that imports and uses any
           of the specified entities, GHC will print the specified
           message.</para>
-         <para> You can only depecate entities declared at top level in the module
+         <para> You can only attach to entities declared at top level in the module
          being compiled, and you can only use unqualified names in the list of
-         entities being deprecated.  A capitalised name, such as <literal>T</literal>
+         entities. A capitalised name, such as <literal>T</literal>
          refers to <emphasis>either</emphasis> the type constructor <literal>T</literal>
          <emphasis>or</emphasis> the data constructor <literal>T</literal>, or both if
-         both are in scope.  If both are in scope, there is currently no way to deprecate 
-         one without the other (c.f. fixities <xref linkend="infix-tycons"/>).</para>
+         both are in scope.  If both are in scope, there is currently no way to
+      specify one without the other (c.f. fixities
+      <xref linkend="infix-tycons"/>).</para>
        </listitem>
       </itemizedlist>
-      Any use of the deprecated item, or of anything from a deprecated
-      module, will be flagged with an appropriate message.  However,
-      deprecations are not reported for
-      (a) uses of a deprecated function within its defining module, and
-      (b) uses of a deprecated function in an export list.
+      Warnings and deprecations are not reported for
+      (a) uses within the defining module, and
+      (b) uses in an export list.
       The latter reduces spurious complaints within a library
       in which one module gathers together and re-exports 
       the exports of several others.
       </para>
       <para>You can suppress the warnings with the flag
-      <option>-fno-warn-deprecations</option>.</para>
-    </sect2>
-
-    <sect2 id="include-pragma">
-      <title>INCLUDE pragma</title>
-
-      <para>The <literal>INCLUDE</literal> pragma is for specifying the names
-       of C header files that should be <literal>#include</literal>'d into
-       the C source code generated by the compiler for the current module (if
-       compiling via C).  For example:</para>
-
-<programlisting>
-{-# INCLUDE "foo.h" #-}
-{-# INCLUDE &lt;stdio.h&gt; #-}</programlisting>
-
-      <para>The <literal>INCLUDE</literal> pragma(s) must appear at the top of
-       your source file with any <literal>OPTIONS_GHC</literal>
-       pragma(s).</para>
-
-      <para>An <literal>INCLUDE</literal> pragma is  the preferred alternative
-       to the <option>-#include</option> option (<xref
-         linkend="options-C-compiler" />), because the
-       <literal>INCLUDE</literal> pragma is understood by other
-       compilers.  Yet another alternative is to add the include file to each
-       <literal>foreign import</literal> declaration in your code, but we
-       don't recommend using this approach with GHC.</para>
+      <option>-fno-warn-warnings-deprecations</option>.</para>
     </sect2>
 
     <sect2 id="inline-noinline-pragma">
@@ -5141,20 +7215,41 @@ Assertion failures can be caught, see the documentation for the
 
 <programlisting>
 key_function :: Int -> String -> (Bool, Double)
-
-#ifdef __GLASGOW_HASKELL__
 {-# INLINE key_function #-}
-#endif
 </programlisting>
 
-       <para>(You don't need to do the C pre-processor carry-on
-        unless you're going to stick the code through HBC&mdash;it
-        doesn't like <literal>INLINE</literal> pragmas.)</para>
-
         <para>The major effect of an <literal>INLINE</literal> pragma
         is to declare a function's &ldquo;cost&rdquo; to be very low.
         The normal unfolding machinery will then be very keen to
-        inline it.</para>
+        inline it.  However, an <literal>INLINE</literal> pragma for a 
+       function "<literal>f</literal>" has a number of other effects:
+<itemizedlist>
+<listitem><para>
+No functions are inlined into <literal>f</literal>.  Otherwise
+GHC might inline a big function into <literal>f</literal>'s right hand side, 
+making <literal>f</literal> big; and then inline <literal>f</literal> blindly.
+</para></listitem>
+<listitem><para>
+The float-in, float-out, and common-sub-expression transformations are not 
+applied to the body of <literal>f</literal>.  
+</para></listitem>
+<listitem><para>
+An INLINE function is not worker/wrappered by strictness analysis.
+It's going to be inlined wholesale instead.
+</para></listitem>
+</itemizedlist>
+All of these effects are aimed at ensuring that what gets inlined is
+exactly what you asked for, no more and no less.
+</para>
+<para>GHC ensures that inlining cannot go on forever: every mutually-recursive
+group is cut by one or more <emphasis>loop breakers</emphasis> that is never inlined
+(see <ulink url="http://research.microsoft.com/%7Esimonpj/Papers/inlining/index.htm">
+Secrets of the GHC inliner, JFP 12(4) July 2002</ulink>).
+GHC tries not to select a function with an INLINE pragma as a loop breaker, but
+when there is no choice even an INLINE function can be selected, in which case
+the INLINE pragma is ignored.
+For example, for a self-recursive function, the loop breaker can only be the function
+itself, so an INLINE pragma is always ignored.</para>
 
        <para>Syntactically, an <literal>INLINE</literal> pragma for a
         function can be put anywhere its type signature could be
@@ -5168,14 +7263,18 @@ key_function :: Int -> String -> (Bool, Double)
         <literal>UniqueSupply</literal> monad code, we have:</para>
 
 <programlisting>
-#ifdef __GLASGOW_HASKELL__
 {-# INLINE thenUs #-}
 {-# INLINE returnUs #-}
-#endif
 </programlisting>
 
        <para>See also the <literal>NOINLINE</literal> pragma (<xref
         linkend="noinline-pragma"/>).</para>
+
+       <para>Note: the HBC compiler doesn't like <literal>INLINE</literal> pragmas,
+         so if you want your code to be HBC-compatible you'll have to surround
+         the pragma with C pre-processor directives 
+         <literal>#ifdef __GLASGOW_HASKELL__</literal>...<literal>#endif</literal>.</para>
+
       </sect3>
 
       <sect3 id="noinline-pragma">
@@ -5229,7 +7328,7 @@ key_function :: Int -> String -> (Bool, Double)
              there was no pragma).
             </para></listitem>
            <listitem>
-           <para>"<literal>INLINE[~k] f</literal>" means: be willing to inline
+           <para>"<literal>NOINLINE[~k] f</literal>" means: be willing to inline
            <literal>f</literal>
              until phase <literal>k</literal>, but from phase
              <literal>k</literal> onwards do not inline it.
@@ -5263,29 +7362,83 @@ happen.
       </sect3>
     </sect2>
 
-    <sect2 id="language-pragma">
-      <title>LANGUAGE pragma</title>
-
-      <indexterm><primary>LANGUAGE</primary><secondary>pragma</secondary></indexterm>
-      <indexterm><primary>pragma</primary><secondary>LANGUAGE</secondary></indexterm>
-
-      <para>This allows language extensions to be enabled in a portable way.
-       It is the intention that all Haskell compilers support the
-       <literal>LANGUAGE</literal> pragma with the same syntax, although not
-       all extensions are supported by all compilers, of
-       course.  The <literal>LANGUAGE</literal> pragma should be used instead
-       of <literal>OPTIONS_GHC</literal>, if possible.</para>
-
-      <para>For example, to enable the FFI and preprocessing with CPP:</para>
-
-<programlisting>{-# LANGUAGE ForeignFunctionInterface, CPP #-}</programlisting>
-
-      <para>Any extension from the <literal>Extension</literal> type defined in
-       <ulink
-         url="../libraries/Cabal/Language-Haskell-Extension.html"><literal>Language.Haskell.Extension</literal></ulink> may be used.  GHC will report an error if any of the requested extensions are not supported.</para>
+    <sect2 id="annotation-pragmas">
+      <title>ANN pragmas</title>
+      
+      <para>GHC offers the ability to annotate various code constructs with additional
+      data by using three pragmas.  This data can then be inspected at a later date by
+      using GHC-as-a-library.</para>
+            
+      <sect3 id="ann-pragma">
+        <title>Annotating values</title>
+        
+        <indexterm><primary>ANN</primary></indexterm>
+        
+        <para>Any expression that has both <literal>Typeable</literal> and <literal>Data</literal> instances may be attached to a top-level value
+        binding using an <literal>ANN</literal> pragma. In particular, this means you can use <literal>ANN</literal>
+        to annotate data constructors (e.g. <literal>Just</literal>) as well as normal values (e.g. <literal>take</literal>).
+        By way of example, to annotate the function <literal>foo</literal> with the annotation <literal>Just "Hello"</literal>
+        you would do this:</para>
+        
+<programlisting>
+{-# ANN foo (Just "Hello") #-}
+foo = ...
+</programlisting>
+        
+        <para>
+          A number of restrictions apply to use of annotations:
+          <itemizedlist>
+            <listitem><para>The binder being annotated must be at the top level (i.e. no nested binders)</para></listitem>
+            <listitem><para>The binder being annotated must be declared in the current module</para></listitem>
+            <listitem><para>The expression you are annotating with must have a type with <literal>Typeable</literal> and <literal>Data</literal> instances</para></listitem>
+            <listitem><para>The <ulink linkend="using-template-haskell">Template Haskell staging restrictions</ulink> apply to the
+            expression being annotated with, so for example you cannot run a function from the module being compiled.</para>
+            
+            <para>To be precise, the annotation <literal>{-# ANN x e #-}</literal> is well staged if and only if <literal>$(e)</literal> would be 
+            (disregarding the usual type restrictions of the splice syntax, and the usual restriction on splicing inside a splice - <literal>$([|1|])</literal> is fine as an annotation, albeit redundant).</para></listitem>
+          </itemizedlist>
+          
+          If you feel strongly that any of these restrictions are too onerous, <ulink url="http://hackage.haskell.org/trac/ghc/wiki/MailingListsAndIRC">
+          please give the GHC team a shout</ulink>.
+        </para>
+        
+        <para>However, apart from these restrictions, many things are allowed, including expressions which are not fully evaluated!
+        Annotation expressions will be evaluated by the compiler just like Template Haskell splices are. So, this annotation is fine:</para>
+        
+<programlisting>
+{-# ANN f SillyAnnotation { foo = (id 10) + $([| 20 |]), bar = 'f } #-}
+f = ...
+</programlisting>
+      </sect3>
+      
+      <sect3 id="typeann-pragma">
+        <title>Annotating types</title>
+        
+        <indexterm><primary>ANN type</primary></indexterm>
+        <indexterm><primary>ANN</primary></indexterm>
+        
+        <para>You can annotate types with the <literal>ANN</literal> pragma by using the <literal>type</literal> keyword. For example:</para>
+        
+<programlisting>
+{-# ANN type Foo (Just "A `Maybe String' annotation") #-}
+data Foo = ...
+</programlisting>
+      </sect3>
+      
+      <sect3 id="modann-pragma">
+        <title>Annotating modules</title>
+        
+        <indexterm><primary>ANN module</primary></indexterm>
+        <indexterm><primary>ANN</primary></indexterm>
+        
+        <para>You can annotate modules with the <literal>ANN</literal> pragma by using the <literal>module</literal> keyword. For example:</para>
+        
+<programlisting>
+{-# ANN module (Just "A `Maybe String' annotation") #-}
+</programlisting>
+      </sect3>
     </sect2>
 
-
     <sect2 id="line-pragma">
       <title>LINE pragma</title>
 
@@ -5305,22 +7458,6 @@ happen.
       pragma.</para>
     </sect2>
 
-    <sect2 id="options-pragma">
-      <title>OPTIONS_GHC pragma</title>
-      <indexterm><primary>OPTIONS_GHC</primary>
-      </indexterm>
-      <indexterm><primary>pragma</primary><secondary>OPTIONS_GHC</secondary>
-      </indexterm>
-
-      <para>The <literal>OPTIONS_GHC</literal> pragma is used to specify
-      additional options that are given to the compiler when compiling
-      this source file.  See <xref linkend="source-file-options"/> for
-      details.</para>
-
-      <para>Previous versions of GHC accepted <literal>OPTIONS</literal> rather
-       than <literal>OPTIONS_GHC</literal>, but that is now deprecated.</para>
-    </sect2>
-
     <sect2 id="rules">
       <title>RULES pragma</title>
 
@@ -5366,7 +7503,7 @@ happen.
 <programlisting>
   {-# SPECIALIZE f :: &lt;type&gt; #-}
 </programlisting>
-      is valid if and only if the defintion
+      is valid if and only if the definition
 <programlisting>
   f_spec :: &lt;type&gt;
   f_spec = f
@@ -5382,7 +7519,7 @@ happen.
 
   h :: Eq a => a -> a -> a
   {-# SPECIALISE h :: (Eq a) => [a] -> [a] -> [a] #-}
-</programlisting>  
+</programlisting>
 The last of these examples will generate a 
 RULE with a somewhat-complex left-hand side (try it yourself), so it might not fire very
 well.  If you use this kind of specialisation, let us know how well it works.
@@ -5391,7 +7528,7 @@ well.  If you use this kind of specialisation, let us know how well it works.
 <para>A <literal>SPECIALIZE</literal> pragma can optionally be followed with a
 <literal>INLINE</literal> or <literal>NOINLINE</literal> pragma, optionally 
 followed by a phase, as described in <xref linkend="inline-noinline-pragma"/>.
-The <literal>INLINE</literal> pragma affects the specialised verison of the
+The <literal>INLINE</literal> pragma affects the specialised version of the
 function (only), and applies even if the function is recursive.  The motivating
 example is this:
 <programlisting>
@@ -5499,14 +7636,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>
 
@@ -5520,6 +7657,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 ======================== -->
@@ -5533,23 +7679,19 @@ data S = S {-# UNPACK #-} !Int {-# UNPACK #-} !Int
 
 <para>
 The programmer can specify rewrite rules as part of the source program
-(in a pragma).  GHC applies these rewrite rules wherever it can, provided (a) 
-the <option>-O</option> flag (<xref linkend="options-optimise"/>) is on, 
-and (b) the <option>-frules-off</option> flag
-(<xref linkend="options-f"/>) is not specified, and (c) the
-<option>-fglasgow-exts</option> (<xref linkend="options-language"/>)
-flag is active.
-</para>
-
-<para>
+(in a pragma).  
 Here is an example:
 
 <programlisting>
   {-# RULES
-        "map/map"       forall f g xs. map f (map g xs) = map (f.g) xs
-  #-}
+  "map/map"    forall f g xs.  map f (map g xs) = map (f.g) xs
+    #-}
 </programlisting>
-
+</para>
+<para>
+Use the debug flag <option>-ddump-simpl-stats</option> to see what rules fired.
+If you need more information, then <option>-ddump-rule-firings</option> shows you
+each individual rule firing in detail.
 </para>
 
 <sect2>
@@ -5559,15 +7701,32 @@ Here is an example:
 From a syntactic point of view:
 
 <itemizedlist>
-<listitem>
 
+<listitem>
 <para>
- There may be zero or more rules in a <literal>RULES</literal> pragma.
+ There may be zero or more rules in a <literal>RULES</literal> pragma, separated by semicolons (which
+ may be generated by the layout rule).
 </para>
 </listitem>
 
 <listitem>
+<para>
+The layout rule applies in a pragma.
+Currently no new indentation level
+is set, so if you put several rules in single RULES pragma and wish to use layout to separate them,
+you must lay out the starting in the same column as the enclosing definitions.
+<programlisting>
+  {-# RULES
+  "map/map"    forall f g xs.  map f (map g xs) = map (f.g) xs
+  "map/append" forall f xs ys. map f (xs ++ ys) = map f xs ++ map f ys
+    #-}
+</programlisting>
+Furthermore, the closing <literal>#-}</literal>
+should start in a column to the right of the opening <literal>{-#</literal>.
+</para>
+</listitem>
 
+<listitem>
 <para>
  Each rule has a name, enclosed in double quotes.  The name itself has
 no significance at all.  It is only used when reporting how many times the rule fired.
@@ -5581,7 +7740,7 @@ immediately after the name of the rule.  Thus:
 <programlisting>
   {-# RULES
         "map/map" [2]  forall f g xs. map f (map g xs) = map (f.g) xs
-  #-}
+    #-}
 </programlisting>
 The "[2]" means that the rule is active in Phase 2 and subsequent phases.  The inverse
 notation "[~2]" is also accepted, meaning that the rule is active up to, but not including,
@@ -5590,17 +7749,8 @@ Phase 2.
 </listitem>
 
 
-<listitem>
-
-<para>
- Layout applies in a <literal>RULES</literal> pragma.  Currently no new indentation level
-is set, so you must lay out your rules starting in the same column as the
-enclosing definitions.
-</para>
-</listitem>
 
 <listitem>
-
 <para>
  Each variable mentioned in a rule must either be in scope (e.g. <function>map</function>),
 or bound by the <literal>forall</literal> (e.g. <function>f</function>, <function>g</function>, <function>xs</function>).  The variables bound by
@@ -5649,17 +7799,40 @@ variables it mentions, though of course they need to be in scope.
 <listitem>
 
 <para>
- Rules are automatically exported from a module, just as instance declarations are.
+ All rules are implicitly exported from the module, and are therefore
+in force in any module that imports the module that defined the rule, directly
+or indirectly.  (That is, if A imports B, which imports C, then C's rules are
+in force when compiling A.)  The situation is very similar to that for instance
+declarations.
+</para>
+</listitem>
+
+<listitem>
+
+<para>
+Inside a RULE "<literal>forall</literal>" is treated as a keyword, regardless of
+any other flag settings.  Furthermore, inside a RULE, the language extension
+<option>-XScopedTypeVariables</option> is automatically enabled; see 
+<xref linkend="scoped-type-variables"/>.
 </para>
 </listitem>
+<listitem>
 
+<para>
+Like other pragmas, RULE pragmas are always checked for scope errors, and
+are typechecked. Typechecking means that the LHS and RHS of a rule are typechecked, 
+and must have the same type.  However, rules are only <emphasis>enabled</emphasis>
+if the <option>-fenable-rewrite-rules</option> flag is 
+on (see <xref linkend="rule-semantics"/>).
+</para>
+</listitem>
 </itemizedlist>
 
 </para>
 
 </sect2>
 
-<sect2>
+<sect2 id="rule-semantics">
 <title>Semantics</title>
 
 <para>
@@ -5667,9 +7840,17 @@ From a semantic point of view:
 
 <itemizedlist>
 <listitem>
-
 <para>
-Rules are only applied if you use the <option>-O</option> flag.
+Rules are enabled (that is, used during optimisation)
+by the <option>-fenable-rewrite-rules</option> flag.
+This flag is implied by <option>-O</option>, and may be switched
+off (as usual) by <option>-fno-enable-rewrite-rules</option>.
+(NB: enabling <option>-fenable-rewrite-rules</option> without <option>-O</option> 
+may not do what you expect, though, because without <option>-O</option> GHC 
+ignores all optimisation information in interface files;
+see <option>-fignore-interface-pragmas</option>, <xref linkend="options-f"/>.)
+Note that <option>-fenable-rewrite-rules</option> is an <emphasis>optimisation</emphasis> flag, and
+has no effect on parsing or typechecking.
 </para>
 </listitem>
 
@@ -5686,14 +7867,6 @@ expression by substituting for the pattern variables.
 <listitem>
 
 <para>
- The LHS and RHS of a rule are typechecked, and must have the
-same type.
-
-</para>
-</listitem>
-<listitem>
-
-<para>
  GHC makes absolutely no attempt to verify that the LHS and RHS
 of a rule have the same meaning.  That is undecidable in general, and
 infeasible in most interesting cases.  The responsibility is entirely the programmer's!
@@ -5707,7 +7880,7 @@ infeasible in most interesting cases.  The responsibility is entirely the progra
 terminating.  For example:
 
 <programlisting>
-  "loop"        forall x,y.  f x y = f y x
+  "loop"        forall x y.  f x y = f y x
 </programlisting>
 
 This rule will cause the compiler to go into an infinite loop.
@@ -5760,48 +7933,32 @@ not be substituted, and the rule would not fire.
 <listitem>
 
 <para>
- In the earlier phases of compilation, GHC inlines <emphasis>nothing
-that appears on the LHS of a rule</emphasis>, because once you have substituted
-for something you can't match against it (given the simple minded
-matching).  So if you write the rule
-
+Ordinary inlining happens at the same time as rule rewriting, which may lead to unexpected
+results.  Consider this (artificial) example
 <programlisting>
-        "map/map"       forall f,g.  map f . map g = map (f.g)
-</programlisting>
+f x = x
+{-# RULES "f" f True = False #-}
 
-this <emphasis>won't</emphasis> match the expression <literal>map f (map g xs)</literal>.
-It will only match something written with explicit use of ".".
-Well, not quite.  It <emphasis>will</emphasis> match the expression
+g y = f y
 
-<programlisting>
-wibble f g xs
+h z = g True
 </programlisting>
-
-where <function>wibble</function> is defined:
-
+Since <literal>f</literal>'s right-hand side is small, it is inlined into <literal>g</literal>,
+to give
 <programlisting>
-wibble f g = map f . map g
+g y = y
 </programlisting>
-
-because <function>wibble</function> will be inlined (it's small).
-
-Later on in compilation, GHC starts inlining even things on the
-LHS of rules, but still leaves the rules enabled.  This inlining
-policy is controlled by the per-simplification-pass flag <option>-finline-phase</option><emphasis>n</emphasis>.
-
+Now <literal>g</literal> is inlined into <literal>h</literal>, but <literal>f</literal>'s RULE has
+no chance to fire.  
+If instead GHC had first inlined <literal>g</literal> into <literal>h</literal> then there
+would have been a better chance that <literal>f</literal>'s RULE might fire.  
 </para>
-</listitem>
-<listitem>
-
 <para>
- All rules are implicitly exported from the module, and are therefore
-in force in any module that imports the module that defined the rule, directly
-or indirectly.  (That is, if A imports B, which imports C, then C's rules are
-in force when compiling A.)  The situation is very similar to that for instance
-declarations.
+The way to get predictable behaviour is to use a NOINLINE 
+pragma on <literal>f</literal>, to ensure
+that it is not inlined until its RULEs have had a chance to fire.
 </para>
 </listitem>
-
 </itemizedlist>
 
 </para>
@@ -5899,12 +8056,6 @@ The following are good consumers:
 <listitem>
 
 <para>
- <function>length</function>
-</para>
-</listitem>
-<listitem>
-
-<para>
  <function>++</function> (on its first argument)
 </para>
 </listitem>
@@ -6093,7 +8244,7 @@ If you add <option>-dppr-debug</option> you get a more detailed listing.
 <listitem>
 
 <para>
- The definition of (say) <function>build</function> in <filename>GHC/Base.lhs</filename> looks llike this:
+ The definition of (say) <function>build</function> in <filename>GHC/Base.lhs</filename> looks like this:
 
 <programlisting>
         build   :: forall a. (forall b. (a -> b -> b) -> b -> b) -> [a]
@@ -6150,7 +8301,7 @@ g x = show x
 </para>
 
 <para>
-  However, when external for is generated (via
+  However, when external core is generated (via
   <option>-fext-core</option>), there will be Notes attached to the
   expressions <function>show</function> and <varname>x</varname>.
   The core function declaration for <function>f</function> is:
@@ -6190,112 +8341,10 @@ r) ->
 
 <sect1 id="special-ids">
 <title>Special built-in functions</title>
-<para>GHC has a few built-in funcions with special behaviour, 
-described in this section.  All are exported by
-<literal>GHC.Exts</literal>.</para>
-
-<sect2> <title>The <literal>seq</literal> function </title>
-<para>
-The function <literal>seq</literal> is as described in the Haskell98 Report.
-<programlisting>
-  seq :: a -> b -> b
-</programlisting>
-It evaluates its first argument to head normal form, and then returns its
-second argument as the result.  The reason that it is documented here is 
-that, despite <literal>seq</literal>'s polymorphism, its 
-second argument can have an unboxed type, or
-can be an unboxed tuple; for example <literal>(seq x 4#)</literal>
-or <literal>(seq x (# p,q #))</literal>.  This requires <literal>b</literal>
-to be instantiated to an unboxed type, which is not usually allowed.
-</para>
-</sect2>
-
-<sect2> <title>The <literal>inline</literal> function </title>
-<para>
-The <literal>inline</literal> function is somewhat experimental.
-<programlisting>
-  inline :: a -> a
-</programlisting>
-The call <literal>(inline f)</literal> arranges that <literal>f</literal> 
-is inlined, regardless of its size.  More precisely, the call
-<literal>(inline f)</literal> rewrites to the right-hand side of <literal>f</literal>'s 
-definition.  
-This allows the programmer to control inlining from 
-a particular <emphasis>call site</emphasis>
-rather than the <emphasis>definition site</emphasis> of the function 
-(c.f. <literal>INLINE</literal> pragmas <xref linkend="inline-noinline-pragma"/>).
-</para>
-<para>
-This inlining occurs regardless of the argument to the call
-or the size of <literal>f</literal>'s definition; it is unconditional.
-The main caveat is that <literal>f</literal>'s definition must be
-visible to the compiler.  That is, <literal>f</literal> must be
-let-bound in the current scope.
-If no inlining takes place, the <literal>inline</literal> function
-expands to the identity function in Phase zero; so its use imposes
-no overhead.</para>
-
-<para> If the function is defined in another
-module, GHC only exposes its inlining in the interface file if the
-function is sufficiently small that it <emphasis>might</emphasis> be
-inlined by the automatic mechanism.  There is currently no way to tell
-GHC to expose arbitrarily-large functions in the interface file.  (This
-shortcoming is something that could be fixed, with some kind of pragma.)
-</para>
-</sect2>
-
-<sect2> <title>The <literal>lazy</literal> function </title>
-<para>
-The <literal>lazy</literal> function restrains strictness analysis a little:
-<programlisting>
-  lazy :: a -> a
-</programlisting>
-The call <literal>(lazy e)</literal> means the same as <literal>e</literal>, 
-but <literal>lazy</literal> has a magical property so far as strictness
-analysis is concerned: it is lazy in its first argument,
-even though its semantics is strict.  After strictness analysis has run,
-calls to <literal>lazy</literal> are inlined to be the identity function.
-</para>
-<para>
-This behaviour is occasionally useful when controlling evaluation order.
-Notably, <literal>lazy</literal> is used in the library definition of
-<literal>Control.Parallel.par</literal>:
-<programlisting>
-  par :: a -> b -> b
-  par x y = case (par# x) of { _ -> lazy y }
-</programlisting>
-If <literal>lazy</literal> were not lazy, <literal>par</literal> would
-look strict in <literal>y</literal> which would defeat the whole 
-purpose of <literal>par</literal>.
-</para>
-<para>
-Like <literal>seq</literal>, the argument of <literal>lazy</literal> can have
-an unboxed type.
-</para>
-
-</sect2>
-
-<sect2> <title>The <literal>unsafeCoerce#</literal> function </title>
-<para>
-The function <literal>unsafeCoerce#</literal> allows you to side-step the
-typechecker entirely.  It has type
-<programlisting>
-  unsafeCoerce# :: a -> b
-</programlisting>
-That is, it allows you to coerce any type into any other type.  If you use this
-function, you had better get it right, otherwise segmentation faults await. 
-It is generally used when you want to write a program that you know is
-well-typed, but where Haskell's type system is not expressive enough to prove
-that it is well typed.
-</para>
-<para>
-The argument to <literal>unsafeCoerce#</literal> can have unboxed types,
-although extremely bad things will happen if you coerce a boxed type 
-to an unboxed type.
-</para>
-
-</sect2>
-
+<para>GHC has a few built-in functions with special behaviour.  These
+are now described in the module <ulink
+url="../libraries/ghc-prim/GHC-Prim.html"><literal>GHC.Prim</literal></ulink>
+in the library documentation.</para>
 </sect1>
 
 
@@ -6352,7 +8401,7 @@ where clause and over-ride whichever methods you please.
       <itemizedlist>
        <listitem>
          <para>Use the flags <option>-fglasgow-exts</option> (to enable the extra syntax), 
-                <option>-fgenerics</option> (to generate extra per-data-type code),
+                <option>-XGenerics</option> (to generate extra per-data-type code),
                 and <option>-package lang</option> (to make the <literal>Generics</literal> library
                 available.  </para>
        </listitem>
@@ -6462,7 +8511,7 @@ So this too is illegal:
     op2 :: a -> Bool
     op2 {| p :*: q |} (x :*: y) = False
 </programlisting>
-(The reason for this restriction is that we gather all the equations for a particular type consructor
+(The reason for this restriction is that we gather all the equations for a particular type constructor
 into a single generic instance declaration.)
 </para>
 </listitem>
@@ -6493,7 +8542,7 @@ Here, op1, op2, op3 are OK, but op4 is rejected, because it has a type variable
 inside a list.  
 </para>
 <para>
-This restriction is an implementation restriction: we just havn't got around to
+This restriction is an implementation restriction: we just haven't got around to
 implementing the necessary bidirectional maps over arbitrary type constructors.
 It would be relatively easy to add specific type constructors, such as Maybe and list,
 to the ones that are allowed.</para>
@@ -6561,21 +8610,21 @@ carried out at let and where bindings.
 
 <sect2>
 <title>Switching off the dreaded Monomorphism Restriction</title>
-          <indexterm><primary><option>-fno-monomorphism-restriction</option></primary></indexterm>
+          <indexterm><primary><option>-XNoMonomorphismRestriction</option></primary></indexterm>
 
 <para>Haskell's monomorphism restriction (see 
-<ulink url="http://haskell.org/onlinereport/decls.html#sect4.5.5">Section
+<ulink url="http://www.haskell.org/onlinereport/decls.html#sect4.5.5">Section
 4.5.5</ulink>
 of the Haskell Report)
 can be completely switched off by
-<option>-fno-monomorphism-restriction</option>.
+<option>-XNoMonomorphismRestriction</option>.
 </para>
 </sect2>
 
 <sect2>
 <title>Monomorphic pattern bindings</title>
-          <indexterm><primary><option>-fno-mono-pat-binds</option></primary></indexterm>
-          <indexterm><primary><option>-fmono-pat-binds</option></primary></indexterm>
+          <indexterm><primary><option>-XNoMonoPatBinds</option></primary></indexterm>
+          <indexterm><primary><option>-XMonoPatBinds</option></primary></indexterm>
 
          <para> As an experimental change, we are exploring the possibility of
          making pattern bindings monomorphic; that is, not generalised at all.  
@@ -6591,7 +8640,7 @@ can be completely switched off by
   [x] = e                    -- A pattern binding
 </programlisting>
 Experimentally, GHC now makes pattern bindings monomorphic <emphasis>by
-default</emphasis>.  Use <option>-fno-mono-pat-binds</option> to recover the
+default</emphasis>.  Use <option>-XNoMonoPatBinds</option> to recover the
 standard behaviour.
 </para>
 </sect2>
@@ -6603,6 +8652,7 @@ standard behaviour.
      ;;; Local Variables: ***
      ;;; mode: xml ***
      ;;; sgml-parent-document: ("users_guide.xml" "book" "chapter" "sect1") ***
+     ;;; ispell-local-dictionary: "british" ***
      ;;; End: ***
  -->