[project @ 2004-01-12 10:02:51 by simonpj]

[ghc-hetmet.git] / ghc / docs / users_guide / glasgow_exts.sgml

diff --git a/ghc/docs/users_guide/glasgow_exts.sgml b/ghc/docs/users_guide/glasgow_exts.sgml
index a4813b0..025a923 100644 (file)
--- a/ghc/docs/users_guide/glasgow_exts.sgml
+++ b/ghc/docs/users_guide/glasgow_exts.sgml
@@ -1597,9 +1597,9 @@ declarations
   instance context2 => C type2 where ...
 </programlisting>
 
+"overlap" if <literal>type1</literal> and <literal>type2</literal> unify.
 
-"overlap" if <literal>type1</literal> and <literal>type2</literal> unify
-
+<para>
 However, if you give the command line option
 <option>-fallow-overlapping-instances</option><indexterm><primary>-fallow-overlapping-instances
 option</primary></indexterm> then overlapping instance declarations are permitted.
@@ -3105,17 +3105,24 @@ where
   <literal>S</literal> is a type constructor, 
 </para></listitem>
 <listitem><para>
-  <literal>t1...tk</literal> are types,
+  The <literal>t1...tk</literal> are types,
 </para></listitem>
 <listitem><para>
-  <literal>vk+1...vn</literal> are type variables which do not occur in any of
+  The <literal>vk+1...vn</literal> are type variables which do not occur in any of
   the <literal>ti</literal>, and
 </para></listitem>
 <listitem><para>
-  the <literal>ci</literal> are partial applications of
+  The <literal>ci</literal> are partial applications of
   classes of the form <literal>C t1'...tj'</literal>, where the arity of <literal>C</literal>
   is exactly <literal>j+1</literal>.  That is, <literal>C</literal> lacks exactly one type argument.
 </para></listitem>
+<listitem><para>
+  None of the <literal>ci</literal> is <literal>Read</literal>, <literal>Show</literal>, 
+               <literal>Typeable</literal>, or <literal>Data</literal>.  These classes
+               should not "look through" the type or its constructor.  You can still
+               derive these classes for a newtype, but it happens in the usual way, not 
+               via this new mechanism.  
+</para></listitem>
 </itemizedlist>
 Then, for each <literal>ci</literal>, the derived instance
 declaration is:
@@ -3781,7 +3788,7 @@ a new <literal>form</literal> keyword.
 Although only GHC implements arrow notation directly,
 there is also a preprocessor
 (available from the 
-<ulink url="http://www.haskell.org/arrows/">arrows web page></ulink>)
+<ulink url="http://www.haskell.org/arrows/">arrows web page</ulink>)
 that translates arrow notation into Haskell 98
 for use with other Haskell systems.
 You would still want to check arrow programs with GHC;
@@ -3936,7 +3943,7 @@ Assertion failures can be caught, see the documentation for the
 
       <para>The DEPRECATED pragma lets you specify that a particular
       function, class, or type, is deprecated.  There are two
-      forms.</para>
+      forms.
 
       <itemizedlist>
        <listitem>
@@ -3961,7 +3968,15 @@ Assertion failures can be caught, see the documentation for the
           message.</para>
        </listitem>
       </itemizedlist>
-
+      Any use of the deprecated item, or of anything from a deprecated
+      module, will be flagged with an appropriate message.  However,
+      deprecations are not reported for
+      (a) uses of a deprecated function within its defining module, and
+      (b) uses of a deprecated function in an export list.
+      The latter reduces spurious complaints within a library
+      in which one module gathers together and re-exports 
+      the exports of several others.
+      </para>
       <para>You can suppress the warnings with the flag
       <option>-fno-warn-deprecations</option>.</para>
     </sect2>
@@ -4250,12 +4265,12 @@ of the pragma.
     <sect2 id="unpack-pragma">
       <title>UNPACK pragma</title>
 
-      <indexterm><primary>UNPACK</primary> </indexterm>
+      <indexterm><primary>UNPACK</primary></indexterm>
       
-      <para>There is another use for the <literal>UNPACK</literal>
-      pragma: to indicate that the compiler should unpack the contents
-      of a constructor field into the constructor itself, removing a
-      level of indirection.  For example:</para>
+      <para>The <literal>UNPACK</literal> indicates to the compiler
+      that it should unpack the contents of a constructor field into
+      the constructor itself, removing a level of indirection.  For
+      example:</para>
 
 <ProgramListing>
 data T = T {-# UNPACK #-} !Float
@@ -4300,7 +4315,12 @@ data S = S {-# UNPACK #-} !Int {-# UNPACK #-} !Int
 </ProgramListing>
 
       <para>will store two unboxed <literal>Int&num;</literal>s
-      directly in the <Function>T</Function> constructor.</para>
+      directly in the <Function>T</Function> constructor.  The
+      unpacker can see through newtypes, too.</para>
+
+      <para>If a field cannot be unpacked, you will not get a warning,
+      so it might be an idea to check the generated code with
+      <option>-ddump-simpl</option>.</para>
 
       <para>See also the <option>-funbox-strict-fields</option> flag,
       which essentially has the effect of adding