Documentation only: update External Core section of user guide

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

diff --git a/docs/users_guide/using.xml b/docs/users_guide/using.xml
index 5d92ab2..c12f76b 100644 (file)
--- a/docs/users_guide/using.xml
+++ b/docs/users_guide/using.xml
@@ -342,6 +342,20 @@ module X where
       <varlistentry>
        <term>
           <cmdsynopsis>
+            <command>ghc --show-iface <replaceable>file</replaceable></command>
+          </cmdsynopsis>
+          <indexterm><primary><option>&ndash;&ndash;--show-iface</option></primary></indexterm>
+        </term>
+       <listitem>
+             <para>Read the interface in
+             <replaceable>file</replaceable> and dump it as text to
+             <literal>stdout</literal>. For example <literal>ghc --show-iface M.hi</literal>.</para>
+       </listitem>
+      </varlistentry>
+
+      <varlistentry>
+       <term>
+          <cmdsynopsis>
             <command>ghc --supported-languages</command>
           </cmdsynopsis>
           <indexterm><primary><option>&ndash;&ndash;supported-languages</option></primary></indexterm>
@@ -408,20 +422,6 @@ module X where
        </listitem>
       </varlistentry>
 
-      <varlistentry>
-       <term>
-         <cmdsynopsis>
-            <command>ghc --print-docdir</command>
-          </cmdsynopsis>
-          <indexterm><primary><option>&ndash;&ndash;print-docdir</option></primary></indexterm>
-        </term>
-       <listitem>
-         <para>Print the path to GHC's documentation directory. Note that
-      some distributions do no include the documentation, in which case
-      this directory may be empty or may not exist.</para>
-       </listitem>
-      </varlistentry>
-
     </variablelist>
 
     <sect2 id="make-mode">
@@ -1602,24 +1602,6 @@ f "2"    = 2
 
        <varlistentry>
          <term>
-            <option>-funfolding-update-in-place=<replaceable>n</replaceable></option>
-            <indexterm><primary><option>-funfolding-update-in-place</option></primary></indexterm>
-          </term>
-         <listitem>
-           <para>Switches on an experimental "optimisation".
-            Switching it on makes the compiler a little keener to
-            inline a function that returns a constructor, if the
-            context is that of a thunk.
-<programlisting>
-   x = plusInt a b
-</programlisting>
-            If we inlined plusInt we might get an opportunity to use
-            update-in-place for the thunk 'x'.</para>
-         </listitem>
-       </varlistentry>
-
-       <varlistentry>
-         <term>
             <option>-funfolding-creation-threshold=<replaceable>n</replaceable></option>:
            <indexterm><primary><option>-funfolding-creation-threshold</option></primary></indexterm>
            <indexterm><primary>inlining, controlling</primary></indexterm>
@@ -1824,16 +1806,15 @@ statements or clauses.
   <indexterm><primary>intermediate code generation</primary></indexterm>
 
   <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. Core files, which are given the suffix
-  <filename>.hcr</filename>, can be read and processed by non-GHC back-end
-  tools.  The Core format is formally described in <ulink url="http://www.haskell.org/ghc/docs/papers/core.ps.gz">
+  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">
   <citetitle>An External Representation for the GHC Core Language</citetitle></ulink>, 
-  and sample tools (in Haskell)
-  for manipulating Core files are available in the GHC source distribution 
-  directory <literal>/fptools/ghc/utils/ext-core</literal>.  
+  and sample tools
+  for manipulating Core files (in Haskell) are in the GHC source distribution 
+  directory under <literal>utils/ext-core</literal>.  
   Note that the format of <literal>.hcr</literal> 
-  files is <emphasis>different</emphasis> (though similar) to the Core output format generated 
-  for debugging purposes (<xref linkend="options-debugging"/>).</para>
+  files is <emphasis>different</emphasis> from the Core output format that GHC generates 
+  for debugging purposes (<xref linkend="options-debugging"/>), though the two formats appear somewhat similar.</para>
 
   <para>The Core format natively supports notes which you can add to
   your source code using the <literal>CORE</literal> pragma (see <xref
@@ -1853,10 +1834,8 @@ statements or clauses.
 
     </variablelist>
 
-<para>GHC can also read in External Core files as source; just give the <literal>.hcr</literal> file on
-the command line, instead of the <literal>.hs</literal> or <literal>.lhs</literal> Haskell source.
-A current infelicity is that you need to give the <literal>-fglasgow-exts</literal> flag too, because
-ordinary Haskell 98, when translated to External Core, uses things like rank-2 types.</para>
+<para>Currently (as of version 6.8.2), GHC does not have the ability to read in External Core files as source. If you would like GHC to have this ability, please <ulink url="http://hackage.haskell.org/trac/ghc/wiki/MailingListsAndIRC">make your wishes known to the GHC Team</ulink>.</para>
+
 </sect1>
 
 &debug;