Improve links from flag reference to the relevant section; and improve doc of RankN...

diff --git a/docs/users_guide/flags.xml b/docs/users_guide/flags.xml
index 27c0dda..d4b6bcc 100644 (file)
--- a/docs/users_guide/flags.xml
+++ b/docs/users_guide/flags.xml
@@ -786,11 +786,23 @@
            </row>
            <row>
              <entry><option>-XPolymorphicComponents</option></entry>
-             <entry>Enable polymorphic components.</entry>
+             <entry>Enable <link linkend="universal-quantification">polymorphic components for data constructors</link>.</entry>
              <entry>dynamic</entry>
              <entry><option>-XNoPolymorphicComponents</option></entry>
            </row>
            <row>
+             <entry><option>-XRank2Types</option></entry>
+             <entry>Enable <link linkend="universal-quantification">rank-2 types</link>.</entry>
+             <entry>dynamic</entry>
+             <entry><option>-XNoRank2Types</option></entry>
+           </row>
+           <row>
+             <entry><option>-XRankNTypes</option></entry>
+             <entry>Enable <link linkend="universal-quantification">rank-N types</link>.</entry>
+             <entry>dynamic</entry>
+             <entry><option>-XNoRankNTypes</option></entry>
+           </row>
+           <row>
              <entry><option>-XExistentialQuantification</option></entry>
              <entry>Enable <link linkend="existential-quantification">existential quantification</link>.</entry>
              <entry>dynamic</entry>
@@ -833,18 +845,6 @@
              <entry><option>-XNoLiberalTypeSynonyms</option></entry>
            </row>
            <row>
-             <entry><option>-XRank2Types</option></entry>
-             <entry>Enable rank-2 types.</entry>
-             <entry>dynamic</entry>
-             <entry><option>-XNoRank2Types</option></entry>
-           </row>
-           <row>
-             <entry><option>-XRankNTypes</option></entry>
-             <entry>Enable rank-N types.</entry>
-             <entry>dynamic</entry>
-             <entry><option>-XNoRankNTypes</option></entry>
-           </row>
-           <row>
              <entry><option>-XTypeOperators</option></entry>
              <entry>Enable type operators.</entry>
              <entry>dynamic</entry>
@@ -864,19 +864,19 @@
            </row>
            <row>
              <entry><option>-XRecordWildCards</option></entry>
-             <entry>Enable record wildcards.</entry>
+             <entry>Enable <link linkend="record-wildcards">record wildcards</link>.</entry>
              <entry>dynamic</entry>
              <entry><option>-XNoRecordWildCards</option></entry>
            </row>
            <row>
              <entry><option>-XRecordPuns</option></entry>
-             <entry>Enable record puns.</entry>
+             <entry>Enable <link linkend="record-puns">record puns</link>.</entry>
              <entry>dynamic</entry>
              <entry><option>-XNoRecordPuns</option></entry>
            </row>
            <row>
              <entry><option>-XDisambiguateRecordFields</option></entry>
-             <entry>Enable the <link linkend="disambiguate-fields">disambiguate fields.</link> exception</entry>
+             <entry>Enable  <link linkend="disambiguate-fields">record field disambiguation</link>. </entry>
              <entry>dynamic</entry>
              <entry><option>-XNoDisambiguateRecordFields</option></entry>
            </row>
@@ -912,19 +912,19 @@
            </row>
            <row>
              <entry><option>-XFlexibleContexts</option></entry>
-             <entry>Enable flexible contexts.</entry>
+             <entry>Enable <link linkend="flexible-contexts">flexible contexts</link>.</entry>
              <entry>dynamic</entry>
              <entry><option>-XNoFlexibleContexts</option></entry>
            </row>
            <row>
              <entry><option>-XFlexibleInstances</option></entry>
-             <entry>Enable flexible instances.</entry>
+             <entry>Enable <link linkend="instance-rules">flexible instances</link>.</entry>
              <entry>dynamic</entry>
              <entry><option>-XNoFlexibleInstances</option></entry>
            </row>
            <row>
              <entry><option>-XConstrainedClassMethods</option></entry>
-             <entry>Enable constrained class methods.</entry>
+             <entry>Enable <link linkend="class-method-types">constrained class methods</link>.</entry>
              <entry>dynamic</entry>
              <entry><option>-XNoConstrainedClassMethods</option></entry>
            </row>

diff --git a/docs/users_guide/glasgow_exts.xml b/docs/users_guide/glasgow_exts.xml
index a01dea4..0687646 100644 (file)
--- a/docs/users_guide/glasgow_exts.xml
+++ b/docs/users_guide/glasgow_exts.xml
@@ -2689,7 +2689,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>
 
 
@@ -3036,7 +3036,7 @@ 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
+The <option>-XFlexibleInstances</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
 (well-kinded) assertions <literal>(C t1 ... tn)</literal> subject only to the
@@ -3442,7 +3442,7 @@ to work since it gets translated into an equality comparison.
 <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
@@ -4078,9 +4078,18 @@ 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 argment 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>
@@ -4092,6 +4101,8 @@ 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>