Improve documentation of RULES pragmas

1 files changed, 24 insertions, 16 deletions

diff --git a/docs/users_guide/glasgow_exts.xml b/docs/users_guide/glasgow_exts.xml
index e42bf79f92..f6ca80ee87 100644
--- a/docs/users_guide/glasgow_exts.xml
+++ b/docs/users_guide/glasgow_exts.xml
@@ -6046,7 +6046,8 @@ Assertion failures can be caught, see the documentation for the
     <replaceable>word</replaceable> that GHC understands are described
     in the following sections; any pragma encountered with an
     unrecognised <replaceable>word</replaceable> is (silently)
-    ignored.</para>
+    ignored. The layout rule applies in pragmas, so the closing <literal>#-}</literal>
+    should start in a column to the right of the opening <literal>{-#</literal>. </para> 
 
     <para>Certain pragmas are <emphasis>file-header pragmas</emphasis>.  A file-header
       pragma must precede the <literal>module</literal> keyword in the file.  
@@ -6598,10 +6599,9 @@ Here is an example:
 
 <programlisting>
   {-# RULES
-        "map/map"       forall f g xs. map f (map g xs) = map (f.g) xs
-  #-}
+  "map/map"    forall f g xs.  map f (map g xs) = map (f.g) xs
+    #-}
 </programlisting>
-
 </para>
 
 <sect2>
@@ -6611,15 +6611,32 @@ Here is an example:
 From a syntactic point of view:
 
 <itemizedlist>
-<listitem>
 
+<listitem>
 <para>
- There may be zero or more rules in a <literal>RULES</literal> pragma.
+ There may be zero or more rules in a <literal>RULES</literal> pragma, separated by semicolons (which
+ may be generated by the layout rule).
 </para>
 </listitem>
 
 <listitem>
+<para>
+The layout rule applies in a pragma.
+Currently no new indentation level
+is set, so if you put several rules in single RULES pragma and wish to use layout to separate them,
+you must lay out the starting in the same column as the enclosing definitions.
+<programlisting>
+  {-# RULES
+  "map/map"    forall f g xs.  map f (map g xs) = map (f.g) xs
+  "map/append" forall f xs ys. map f (xs ++ ys) = map f xs ++ map f ys
+    #-}
+</programlisting>
+Furthermore, the closing <literal>#-}</literal>
+should start in a column to the right of the opening <literal>{-#</literal>.
+</para>
+</listitem>
 
+<listitem>
 <para>
  Each rule has a name, enclosed in double quotes.  The name itself has
 no significance at all.  It is only used when reporting how many times the rule fired.
@@ -6633,7 +6650,7 @@ immediately after the name of the rule.  Thus:
 <programlisting>
   {-# RULES
         "map/map" [2]  forall f g xs. map f (map g xs) = map (f.g) xs
-  #-}
+    #-}
 </programlisting>
 The "[2]" means that the rule is active in Phase 2 and subsequent phases.  The inverse
 notation "[~2]" is also accepted, meaning that the rule is active up to, but not including,
@@ -6642,17 +6659,8 @@ Phase 2.
 </listitem>
 
 
-<listitem>
-
-<para>
- Layout applies in a <literal>RULES</literal> pragma.  Currently no new indentation level
-is set, so you must lay out your rules starting in the same column as the
-enclosing definitions.
-</para>
-</listitem>
 
 <listitem>
-
 <para>
  Each variable mentioned in a rule must either be in scope (e.g. <function>map</function>),
 or bound by the <literal>forall</literal> (e.g. <function>f</function>, <function>g</function>, <function>xs</function>).  The variables bound by