Rework the GHCi debugger docs

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

diff --git a/docs/users_guide/using.xml b/docs/users_guide/using.xml
index c09fa35..544a6e8 100644 (file)
--- a/docs/users_guide/using.xml
+++ b/docs/users_guide/using.xml
@@ -138,6 +138,11 @@ module X where
     
     <para>The flag reference tables (<xref
     linkend="flag-reference"/>) lists the status of each flag.</para>
+
+    <para>There are a few flags that are static except that they can
+    also be used with GHCi's <literal>:set</literal> command; these
+    are listed as &ldquo;static/<literal>:set</literal>&rdquo; in the
+    table.</para> 
   </sect1>
 
   <sect1 id="file-suffixes">
@@ -305,7 +310,7 @@ module X where
          <para>Dependency-generation mode.  In this mode, GHC can be
          used to generate dependency information suitable for use in
          a <literal>Makefile</literal>.  See <xref
-         linkend="sec-makefile-dependencies"/>.</para>
+         linkend="makefile-dependencies"/>.</para>
        </listitem>
       </varlistentry>
 
@@ -338,10 +343,11 @@ module X where
       <varlistentry>
        <term>
           <cmdsynopsis>
-          <command>ghc --version</command> <command>ghc -V</command> 
+            <command>ghc --version</command>
+            <command>ghc -V</command>
+          </cmdsynopsis>
           <indexterm><primary><option>-V</option></primary></indexterm>
           <indexterm><primary><option>&ndash;&ndash;version</option></primary></indexterm>
-           </cmdsynopsis>
         </term>
        <listitem>
          <para>Print a one-line string including GHC's version number.</para>
@@ -351,9 +357,9 @@ module X where
       <varlistentry>
        <term>
           <cmdsynopsis>
-          <command>ghc --numeric-version</command>
+            <command>ghc --numeric-version</command>
+          </cmdsynopsis>
           <indexterm><primary><option>&ndash;&ndash;numeric-version</option></primary></indexterm>
-           </cmdsynopsis>
         </term>
        <listitem>
          <para>Print GHC's numeric version number only.</para>
@@ -363,9 +369,9 @@ module X where
       <varlistentry>
        <term>
          <cmdsynopsis>
-          <command>ghc --print-libdir</command>
+            <command>ghc --print-libdir</command>
+          </cmdsynopsis>
           <indexterm><primary><option>&ndash;&ndash;print-libdir</option></primary></indexterm>
-           </cmdsynopsis>
         </term>
        <listitem>
          <para>Print the path to GHC's library directory.  This is
@@ -625,8 +631,8 @@ ghc -c Foo.hs</screen>
     <indexterm><primary>help options</primary></indexterm>
     <indexterm><primary>verbosity options</primary></indexterm>
 
-    See also the <option>--help</option>, <option>--version</option>, <option>--numeric-version</option>,
-    and <option>--print-libdir</option> modes in <xref linkend="modes"/>.
+    <para>See also the <option>--help</option>, <option>--version</option>, <option>--numeric-version</option>,
+    and <option>--print-libdir</option> modes in <xref linkend="modes"/>.</para>
     <variablelist>
       <varlistentry>
        <term>
@@ -833,7 +839,17 @@ ghc -c Foo.hs</screen>
        <term><option>-Wall</option>:</term>
        <listitem>
          <indexterm><primary><option>-Wall</option></primary></indexterm>
-         <para>Turns on all warning options.</para>
+         <para>Turns on all warning options that indicate potentially
+         suspicious code.  The warnings that are
+         <emphasis>not</emphasis> enabled by <option>-Wall</option>
+         are:</para>
+          <itemizedlist>
+            <listitem><option>-fwarn-simple-patterns</option></listitem>
+            <listitem><option>-fwarn-tabs</option></listitem>
+            <listitem><option>-fwarn-incomplete-record-updates</option></listitem>
+            <listitem><option>-fwarn-monomorphism-restriction</option></listitem>
+            <listitem><option>-fwarn-implicit-prelude</option></listitem>
+          </itemizedlist>
        </listitem>
       </varlistentry>
 
@@ -899,6 +915,31 @@ ghc -c Foo.hs</screen>
       </varlistentry>
 
       <varlistentry>
+        <term><option>-fwarn-implicit-prelude</option>:</term>
+        <listitem>
+          <indexterm><primary><option>-fwarn-implicit-prelude</option></primary></indexterm>
+          <indexterm><primary>implicit prelude, warning</primary></indexterm>
+          <para>Have the compiler warn if the Prelude is implicitly
+          imported.  This happens unless either the Prelude module is
+          explicitly imported with an <literal>import ... Prelude ...</literal>
+          line, or this implicit import is disabled (either by
+          <option>-fno-implicit-prelude</option> or a
+          <literal>LANGUAGE NoImplicitPrelude</literal> pragma).</para>
+
+          <para>Note that no warning is given for syntax that implicitly
+          refers to the Prelude, even if <option>-fno-implicit-prelude</option>
+          would change whether it refers to the Prelude.
+          For example, no warning is given when
+          <literal>368</literal> means
+          <literal>Prelude.fromInteger (368::Prelude.Integer)</literal>
+          (where <literal>Prelude</literal> refers to the actual Prelude module,
+          regardless of the imports of the module being compiled).</para>
+
+          <para>This warning is off by default.</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
        <term><option>-fwarn-incomplete-patterns</option>:</term>
        <listitem>
          <indexterm><primary><option>-fwarn-incomplete-patterns</option></primary></indexterm>
@@ -1000,7 +1041,8 @@ f foo = foo { x = 6 }
 
          <para>If you would like GHC to check that every top-level
           function/value has a type signature, use the
-          <option>-fwarn-missing-signatures</option> option.  This
+          <option>-fwarn-missing-signatures</option> option.  As part of
+           the warning GHC also reports the inferred type.  The
           option is off by default.</para>
        </listitem>
       </varlistentry>
@@ -1018,7 +1060,7 @@ f foo = foo { x = 6 }
           in the inadvertent cyclic definition <literal>let x = ... x
           ... in</literal>.</para>
 
-         <para>Consequently, this option does
+         <para>Consequently, this option
           <emphasis>will</emphasis> complain about cyclic recursive
           definitions.</para>
        </listitem>
@@ -1129,6 +1171,20 @@ f "2"    = 2
       </varlistentry>
 
       <varlistentry>
+       <term><option>-fwarn-monomorphism-restriction</option>:</term>
+       <listitem>
+         <indexterm><primary><option>-fwarn-monomorphism-restriction</option></primary></indexterm>
+         <indexterm><primary>monomorphism restriction, warning</primary></indexterm>
+         <para>Have the compiler warn/inform you where in your source
+          the Haskell Monomorphism Restriction is applied.  If applied silently
+         the MR can give rise to unexpected behaviour, so it can be helpful
+         to have an explicit warning that it is being applied.</para>
+
+         <para>This warning is off by default.</para>
+       </listitem>
+      </varlistentry>
+
+      <varlistentry>
        <term><option>-fwarn-unused-binds</option>:</term>
        <listitem>
          <indexterm><primary><option>-fwarn-unused-binds</option></primary></indexterm>
@@ -1362,7 +1418,7 @@ f "2"    = 2
            <literal>Exception.assert</literal> in source code (in
            other words, rewriting <literal>Exception.assert p
            e</literal> to <literal>e</literal> (see <xref
-           linkend="sec-assertions"/>).  This flag is turned on by
+           linkend="assertions"/>).  This flag is turned on by
            <option>-O</option>.
            </para>
          </listitem>
@@ -1517,7 +1573,7 @@ f "2"    = 2
   
   &phases;  
   
-  <sect1 id="sec-using-concurrent">
+  <sect1 id="using-concurrent">
     <title>Using Concurrent Haskell</title>
     <indexterm><primary>Concurrent Haskell</primary><secondary>using</secondary></indexterm>
 
@@ -1547,7 +1603,7 @@ f "2"    = 2
     </variablelist>
   </sect1>
 
-  <sect1 id="sec-using-smp">
+  <sect1 id="using-smp">
     <title>Using SMP parallelism</title>
     <indexterm><primary>parallelism</primary>
     </indexterm>