Update the users guide to point at the in-tree core.ps.gz

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

diff --git a/docs/users_guide/using.xml b/docs/users_guide/using.xml
index d805097..b2ac501 100644 (file)
--- a/docs/users_guide/using.xml
+++ b/docs/users_guide/using.xml
@@ -841,11 +841,13 @@ ghc -c Foo.hs</screen>
     of warnings which are generally likely to indicate bugs in your
     program.  These are:
     <option>-fwarn-overlapping-patterns</option>,
-    <option>-fwarn-deprecations</option>,
+    <option>-fwarn-warnings-deprecations</option>,
     <option>-fwarn-deprecated-flags</option>,
     <option>-fwarn-duplicate-exports</option>,
-    <option>-fwarn-missing-fields</option>, and
-    <option>-fwarn-missing-methods</option>.  The following flags are
+    <option>-fwarn-missing-fields</option>,
+    <option>-fwarn-missing-methods</option>, and
+    <option>-fwarn-dodgy-foreign-imports</option>.  The following
+    flags are
     simple ways to select standard &ldquo;packages&rdquo; of warnings:
     </para>
 
@@ -917,15 +919,16 @@ ghc -c Foo.hs</screen>
     <variablelist>
 
       <varlistentry>
-       <term><option>-fwarn-deprecations</option>:</term>
+       <term><option>-fwarn-warnings-deprecations</option>:</term>
        <listitem>
-         <indexterm><primary><option>-fwarn-deprecations</option></primary>
+         <indexterm><primary><option>-fwarn-warnings-deprecations</option></primary>
          </indexterm>
+         <indexterm><primary>warnings</primary></indexterm>
          <indexterm><primary>deprecations</primary></indexterm>
-         <para>Causes a warning to be emitted when a deprecated
-         function or type is used.  Entities can be marked as
-         deprecated using a pragma, see <xref
-         linkend="deprecated-pragma"/>.</para>
+         <para>Causes a warning to be emitted when a
+         module, function or type with a WARNING or DEPRECATED pragma
+      is used. See <xref linkend="warning-deprecated-pragma"/> for more
+      details on the pragmas.</para>
 
          <para>This option is on by default.</para>
        </listitem>
@@ -945,6 +948,30 @@ ghc -c Foo.hs</screen>
       </varlistentry>
 
       <varlistentry>
+       <term><option>-fwarn-dodgy-foreign-imports</option>:</term>
+       <listitem>
+         <indexterm><primary><option>-fwarn-dodgy-foreign-imports</option></primary>
+         </indexterm>
+         <para>Causes a warning to be emitted for foreign imports of
+         the following form:</para>
+<programlisting>
+foreign import "f" f :: FunPtr t
+</programlisting>
+          <para>on the grounds that it probably should be</para>
+<programlisting>
+foreign import "&amp;f" f :: FunPtr t
+</programlisting>
+          <para>The first form declares that `f` is a (pure) C
+          function that takes no arguments and returns a pointer to a
+          C function with type `t`, whereas the second form declares
+          that `f` itself is a C function with type `t`.  The first
+          declaration is usually a mistake, and one that is hard to
+          debug because it results in a crash, hence this
+          warning.</para>
+       </listitem>
+      </varlistentry>
+
+      <varlistentry>
        <term><option>-fwarn-dodgy-imports</option>:</term>
        <listitem>
          <indexterm><primary><option>-fwarn-dodgy-imports</option></primary>
@@ -1152,7 +1179,8 @@ f foo = foo { x = 6 }
          <para>The trouble with orphans is that GHC must pro-actively read the interface
            files for all orphan modules, just in case their instances or rules
            play a role, whether or not the module's interface would otherwise 
-           be of any use.  Other things being equal, avoid orphan modules.</para>
+           be of any use.  See <xref linkend="orphan-modules"/> for details.
+            </para>
        </listitem>
       </varlistentry>
 
@@ -1878,7 +1906,7 @@ statements or clauses.
 
   <para>GHC can dump its optimized intermediate code (said to be in &ldquo;Core&rdquo; format) 
   to a file as a side-effect of compilation. Non-GHC back-end tools can read and process Core files; these files have the suffix
-  <filename>.hcr</filename>. The Core format is described in <ulink url="http://www.haskell.org/ghc/docs/papers/core.ps.gz">
+  <filename>.hcr</filename>. The Core format is described in <ulink url="../ext-core/core.ps.gz">
   <citetitle>An External Representation for the GHC Core Language</citetitle></ulink>, 
   and sample tools
   for manipulating Core files (in Haskell) are in the GHC source distribution