Fix flaggery for RULES (cf Trac #2497)

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

diff --git a/docs/users_guide/glasgow_exts.xml b/docs/users_guide/glasgow_exts.xml
index 63c5dbd..0bccb9e 100644 (file)
--- a/docs/users_guide/glasgow_exts.xml
+++ b/docs/users_guide/glasgow_exts.xml
@@ -1568,6 +1568,29 @@ necessary to enable them.
 </para>
 </sect2>
 
+<sect2 id="package-imports">
+  <title>Package-qualified imports</title>
+
+  <para>With the <option>-XPackageImports</option> flag, GHC allows
+  import declarations to be qualified by the package name that the
+    module is intended to be imported from.  For example:</para>
+
+<programlisting>
+import "network" Network.Socket
+</programlisting>
+  
+  <para>would import the module <literal>Network.Socket</literal> from
+    the package <literal>network</literal> (any version).  This may
+    be used to disambiguate an import when the same module is
+    available from multiple packages, or is present in both the
+    current package being built and an external package.</para>
+
+  <para>Note: you probably don't need to use this feature, it was
+    added mainly so that we can build backwards-compatible versions of
+    packages when APIs change.  It can lead to fragile dependencies in
+    the common case: modules occasionally move from one package to
+    another, rendering any package-qualified imports broken.</para>
+</sect2>
 </sect1>
 
 
@@ -6651,15 +6674,7 @@ data S = S {-# UNPACK #-} !Int {-# UNPACK #-} !Int
 
 <para>
 The programmer can specify rewrite rules as part of the source program
-(in a pragma).  GHC applies these rewrite rules wherever it can, provided (a) 
-the <option>-O</option> flag (<xref linkend="options-optimise"/>) is on, 
-and (b) the <option>-fno-rewrite-rules</option> flag
-(<xref linkend="options-f"/>) is not specified, and (c) the
-<option>-fglasgow-exts</option> (<xref linkend="options-language"/>)
-flag is active.
-</para>
-
-<para>
+(in a pragma).  
 Here is an example:
 
 <programlisting>
@@ -6779,17 +6794,40 @@ variables it mentions, though of course they need to be in scope.
 <listitem>
 
 <para>
- Rules are automatically exported from a module, just as instance declarations are.
+ All rules are implicitly exported from the module, and are therefore
+in force in any module that imports the module that defined the rule, directly
+or indirectly.  (That is, if A imports B, which imports C, then C's rules are
+in force when compiling A.)  The situation is very similar to that for instance
+declarations.
+</para>
+</listitem>
+
+<listitem>
+
+<para>
+Inside a RULE "<literal>forall</literal>" is treated as a keyword, regardless of
+any other flag settings.  Furthermore, inside a RULE, the language extension
+<option>-XScopedTypeVariables</option> is automatically enabled; see 
+<xref linkend="scoped-type-variables"/>.
 </para>
 </listitem>
+<listitem>
 
+<para>
+Like other pragmas, RULE pragmas are always checked for scope errors, and
+are typechecked. Typechecking means that the LHS and RHS of a rule are typechecked, 
+and must have the same type.  However, rules are only <emphasis>enabled</emphasis>
+if the <option>-fenable-rewrite-rules</option> flag is 
+on (see <xref linkend="rule-semantics"/>).
+</para>
+</listitem>
 </itemizedlist>
 
 </para>
 
 </sect2>
 
-<sect2>
+<sect2 id="rule-semantics">
 <title>Semantics</title>
 
 <para>
@@ -6797,9 +6835,17 @@ From a semantic point of view:
 
 <itemizedlist>
 <listitem>
-
 <para>
-Rules are only applied if you use the <option>-O</option> flag.
+Rules are enabled (that is, used during optimisation)
+by the <option>-fenable-rewrite-rules</option> flag.
+This flag is implied by <option>-O</option>, and may be switched
+off (as usual) by <option>-fno-enable-rewrite-rules</option>.
+(NB: enabling <option>-fenable-rewrite-rules</option> without <option>-O</option> 
+may not do what you expect, though, because without <option>-O</option> GHC 
+ignores all optimisation information in interface files;
+see <option>-fignore-interface-pragmas</option>, <xref linkend="options-f"/>.)
+Note that <option>-fenable-rewrite-rules</option> is an <emphasis>optimisation</emphasis> flag, and
+has no effect on parsing or typechecking.
 </para>
 </listitem>
 
@@ -6816,14 +6862,6 @@ expression by substituting for the pattern variables.
 <listitem>
 
 <para>
- The LHS and RHS of a rule are typechecked, and must have the
-same type.
-
-</para>
-</listitem>
-<listitem>
-
-<para>
  GHC makes absolutely no attempt to verify that the LHS and RHS
 of a rule have the same meaning.  That is undecidable in general, and
 infeasible in most interesting cases.  The responsibility is entirely the programmer's!
@@ -6916,17 +6954,6 @@ pragma on <literal>f</literal>, to ensure
 that it is not inlined until its RULEs have had a chance to fire.
 </para>
 </listitem>
-<listitem>
-
-<para>
- All rules are implicitly exported from the module, and are therefore
-in force in any module that imports the module that defined the rule, directly
-or indirectly.  (That is, if A imports B, which imports C, then C's rules are
-in force when compiling A.)  The situation is very similar to that for instance
-declarations.
-</para>
-</listitem>
-
 </itemizedlist>
 
 </para>