Documentation for -fprint-explicit-foralls and -fprint-explicit-kinds
authorSimon Peyton Jones <simonpj@microsoft.com>
Tue, 1 Oct 2013 18:18:27 +0000 (19:18 +0100)
committerSimon Peyton Jones <simonpj@microsoft.com>
Tue, 1 Oct 2013 18:18:27 +0000 (19:18 +0100)
Plus a tidy-up of the flag documentation in the immediate area

docs/users_guide/flags.xml
docs/users_guide/using.xml

index 8020f2d..d990f02 100644 (file)
@@ -8,9 +8,7 @@
     (if available).</para>
 
   <sect2>
-    <title>Help and verbosity options</title>
-
-    <para><xref linkend="options-help"/></para>
+    <title>Verbosity options</title>
 
     <informaltable>
       <tgroup cols="4" align="left" colsep="1" rowsep="1">
         </thead>
         <tbody>
           <row>
-            <entry><option>-?</option></entry>
-            <entry>help</entry>
-            <entry>mode</entry>
-            <entry>-</entry>
-          </row>
-          <row>
-            <entry><option>--help</option></entry>
-            <entry>help</entry>
-            <entry>mode</entry>
-            <entry>-</entry>
-          </row>
-          <row>
             <entry><option>-v</option></entry>
             <entry>verbose mode (equivalent to <option>-v3</option>)</entry>
             <entry>dynamic</entry>
             <entry>-</entry>
           </row>
           <row>
-            <entry><option>-V</option></entry>
-            <entry>display GHC version</entry>
-            <entry>mode</entry>
-            <entry>-</entry>
-          </row>
-          <row>
-            <entry><option>--supported-extensions</option> or <option>--supported-languages</option></entry>
-            <entry>display the supported languages and language extensions</entry>
-            <entry>mode</entry>
-            <entry>-</entry>
-          </row>
-          <row>
-            <entry><option>--show-options</option></entry>
-            <entry>display the supported command line options</entry>
-            <entry>mode</entry>
-            <entry>-</entry>
-          </row>
-          <row>
-            <entry><option>--info</option></entry>
-            <entry>display information about the compiler</entry>
-            <entry>mode</entry>
-            <entry>-</entry>
-          </row>
-          <row>
-            <entry><option>--version</option></entry>
-            <entry>display GHC version</entry>
-            <entry>mode</entry>
-            <entry>-</entry>
-          </row>
-          <row>
-            <entry><option>--numeric-version</option></entry>
-            <entry>display GHC version (numeric only)</entry>
-            <entry>mode</entry>
-            <entry>-</entry>
+            <entry><option>-fprint-explicit-foralls</option></entry>
+            <entry>print explicit <literal>forall</literal> quantification in types</entry>
+            <entry>dynamic</entry>
+            <entry>-fno-print-explicit-foralls</entry>
           </row>
           <row>
-            <entry><option>--print-libdir</option></entry>
-            <entry>display GHC library directory</entry>
-            <entry>mode</entry>
-            <entry>-</entry>
+            <entry><option>-fprint-explicit-kinds</option></entry>
+            <entry>print explicit kind foralls and kind arguments in types</entry>
+            <entry>dynamic</entry>
+            <entry>-fno-print-explicit-kinds</entry>
           </row>
           <row>
             <entry><option>-ferror-spans</option></entry>
 
   </sect2>
   <sect2>
-    <title>Which phases to run</title>
+    <title>Alternative modes of operation</title>
 
-    <para><xref linkend="options-order"/></para>
+    <para><xref linkend="options-help"/></para>
+    <para><xref linkend="modes"/></para>
 
     <informaltable>
       <tgroup cols="4" align="left" colsep="1" rowsep="1">
         </thead>
         <tbody>
           <row>
-            <entry><option>-E</option></entry>
-            <entry>Stop after preprocessing (<literal>.hspp</literal> file)</entry>
+            <entry><option>--help</option>,<option>-?</option></entry>
+            <entry>Disply help</entry>
             <entry>mode</entry>
             <entry>-</entry>
           </row>
+
           <row>
-            <entry><option>-C</option></entry>
-            <entry>Stop after generating C (<literal>.hc</literal> file)</entry>
+            <entry><option>--interactive</option></entry>
+            <entry>Interactive mode - normally used by just running <command>ghci</command>;
+              see <xref linkend="ghci"/> for details.</entry>
             <entry>mode</entry>
             <entry>-</entry>
           </row>
           <row>
-            <entry><option>-S</option></entry>
-            <entry>Stop after generating assembly (<literal>.s</literal> file)</entry>
+            <entry><option>--make</option></entry>
+            <entry>Build a multi-module Haskell program, automatically figuring out dependencies. Likely to be much easier, and faster, than using <command>make</command>;
+              see <xref linkend="make-mode"/> for details..</entry>
             <entry>mode</entry>
             <entry>-</entry>
           </row>
           <row>
-            <entry><option>-c</option></entry>
-            <entry>Do not link</entry>
-            <entry>dynamic</entry>
+            <entry><option>-e <replaceable>expr</replaceable></option></entry>
+            <entry>Evaluate <replaceable>expr</replaceable>;
+              see <xref linkend="eval-mode"/> for details.</entry>
+            <entry>mode</entry>
             <entry>-</entry>
           </row>
+
           <row>
-            <entry><option>-x</option> <replaceable>suffix</replaceable></entry>
-            <entry>Override default behaviour for source files</entry>
-            <entry>static</entry>
+            <entry><option>--show-iface</option></entry>
+            <entry>Display the contents of an interface file.</entry>
+            <entry>mode</entry>
             <entry>-</entry>
           </row>
+
+          <row>
+            <entry><option>-M</option></entry>
+            <entry>Generate dependency information suitable for use in a <filename>Makefile</filename>;
+              see <xref linkend="makefile-dependencies"/> for details.</entry>
+            <entry>mode</entry>
+            <entry>-</entry>
+          </row>
+
+
+          <row>
+            <entry><option>--supported-extensions</option>, <option>--supported-languages</option></entry>
+            <entry>display the supported language extensions</entry>
+            <entry>mode</entry>
+            <entry>-</entry>
+          </row>
+          <row>
+            <entry><option>--show-options</option></entry>
+            <entry>display the supported command line options</entry>
+            <entry>mode</entry>
+            <entry>-</entry>
+          </row>
+          <row>
+            <entry><option>--info</option></entry>
+            <entry>display information about the compiler</entry>
+            <entry>mode</entry>
+            <entry>-</entry>
+          </row>
+          <row>
+            <entry><option>--version, -V</option></entry>
+            <entry>display GHC version</entry>
+            <entry>mode</entry>
+            <entry>-</entry>
+          </row>
+          <row>
+            <entry><option>--numeric-version</option></entry>
+            <entry>display GHC version (numeric only)</entry>
+            <entry>mode</entry>
+            <entry>-</entry>
+          </row>
+          <row>
+            <entry><option>--print-libdir</option></entry>
+            <entry>display GHC library directory</entry>
+            <entry>mode</entry>
+            <entry>-</entry>
+          </row>
+
         </tbody>
       </tgroup>
     </informaltable>
   </sect2>
 
   <sect2>
-    <title>Alternative modes of operation</title>
+    <title>Which phases to run</title>
 
-    <para><xref linkend="modes"/></para>
+    <para><xref linkend="options-order"/></para>
 
     <informaltable>
       <tgroup cols="4" align="left" colsep="1" rowsep="1">
         </thead>
         <tbody>
           <row>
-            <entry><option>--interactive</option></entry>
-            <entry>Interactive mode - normally used by just running <command>ghci</command>;
-              see <xref linkend="ghci"/> for details.</entry>
+            <entry><option>-E</option></entry>
+            <entry>Stop after preprocessing (<literal>.hspp</literal> file)</entry>
             <entry>mode</entry>
             <entry>-</entry>
           </row>
           <row>
-            <entry><option>--make</option></entry>
-            <entry>Build a multi-module Haskell program, automatically figuring out dependencies. Likely to be much easier, and faster, than using <command>make</command>;
-              see <xref linkend="make-mode"/> for details..</entry>
+            <entry><option>-C</option></entry>
+            <entry>Stop after generating C (<literal>.hc</literal> file)</entry>
             <entry>mode</entry>
             <entry>-</entry>
           </row>
           <row>
-            <entry><option>-e <replaceable>expr</replaceable></option></entry>
-            <entry>Evaluate <replaceable>expr</replaceable>;
-              see <xref linkend="eval-mode"/> for details.</entry>
+            <entry><option>-S</option></entry>
+            <entry>Stop after generating assembly (<literal>.s</literal> file)</entry>
             <entry>mode</entry>
             <entry>-</entry>
           </row>
           <row>
-            <entry><option>-M</option></entry>
-            <entry>Generate dependency information suitable for use in a <filename>Makefile</filename>;
-              see <xref linkend="makefile-dependencies"/> for details.</entry>
-            <entry>mode</entry>
+            <entry><option>-c</option></entry>
+            <entry>Do not link</entry>
+            <entry>dynamic</entry>
+            <entry>-</entry>
+          </row>
+          <row>
+            <entry><option>-x</option> <replaceable>suffix</replaceable></entry>
+            <entry>Override default behaviour for source files</entry>
+            <entry>static</entry>
             <entry>-</entry>
           </row>
         </tbody>
index fc3f61b..97a650a 100644 (file)
@@ -308,6 +308,7 @@ module X where
 
   <sect1 id="modes">
     <title>Modes of operation</title>
+    <indexterm><primary>help options</primary></indexterm>
 
     <para>
       GHC's behaviour is firstly controlled by a mode flag.  Only one
@@ -791,9 +792,8 @@ ghc -c Foo.hs
   </sect1>
 
   <sect1 id="options-help">
-    <title>Help and verbosity options</title>
+    <title>Verbosity options</title>
 
-    <indexterm><primary>help options</primary></indexterm>
     <indexterm><primary>verbosity options</primary></indexterm>
 
     <para>See also the <option>--help</option>, <option>--version</option>, <option>--numeric-version</option>,
@@ -881,6 +881,43 @@ ghc -c Foo.hs
         </listitem>
       </varlistentry>
 
+
+      <varlistentry>
+        <term><option>--fprint-explicit-foralls, -fprint-explicit-kinds</option>
+          <indexterm><primary><option>-fprint-explicit-foralls</option></primary></indexterm>
+          <indexterm><primary><option>-fprint-explicit-kinds</option></primary></indexterm>
+        </term>
+        <listitem>
+          <para>These two flags control the way in which GHC displays types, in error messages and in GHCi.
+          Using <option>-fprint-explicit-foralls</option> makes GHC print explicit <literal>forall</literal>
+          quantification at the top level of a type; normally this is suppressed.  For example, in GHCi:
+<screen>
+ghci> let f x = x
+ghci> :t f
+f :: a -> a
+ghci> :set -fprint-explicit-foralls
+ghci> :t f
+f :: forall a. a -> a
+</screen>
+         Using <option>-fprint-explicit-kinds</option> makes GHC print kind-foralls and kind applications
+         in types, which are normally suppressed.  This can be important when you are using kind polymorphism.
+         For example:
+<screen>
+ghci> :set -XPolyKinds
+ghci> data T a = MkT
+ghci> :t MkT
+MkT :: T b
+ghci> :set -fprint-explicit-foralls
+ghci> :t MkT
+MkT :: forall (b::k). T b
+ghci> :set -fprint-explicit-kinds
+ghci> :t MkT
+MkT :: forall (k::BOX) (b:k). T b
+</screen>
+         </para>
+        </listitem>
+      </varlistentry>
+
       <varlistentry>
         <term><option>-ferror-spans</option>
           <indexterm><primary><option>-ferror-spans</option></primary>