Improve documentation of INLINE pragmas

diff --git a/docs/users_guide/glasgow_exts.xml b/docs/users_guide/glasgow_exts.xml
index 9a9cd38..e5b7154 100644 (file)
--- a/docs/users_guide/glasgow_exts.xml
+++ b/docs/users_guide/glasgow_exts.xml
@@ -5010,63 +5010,58 @@ key_function :: Int -> String -> (Bool, Double)
         If you use <option>-dverbose-core2core</option> you'll see the
         sequence of phase numbers for successive runs of the
         simplifier.  In an INLINE pragma you can optionally specify a
-        phase number, thus:</para>
-
+        phase number, thus:
        <itemizedlist>
          <listitem>
-           <para>You can say "inline <literal>f</literal> in Phase 2
-            and all subsequent phases":
-<programlisting>
-  {-# INLINE [2] f #-}
-</programlisting>
-            </para>
-         </listitem>
-
+           <para>"<literal>INLINE[k] f</literal>" means: do not inline
+           <literal>f</literal>
+             until phase <literal>k</literal>, but from phase
+             <literal>k</literal> onwards be very keen to inline it.
+            </para></listitem>
          <listitem>
-           <para>You can say "inline <literal>g</literal> in all
-            phases up to, but not including, Phase 3":
-<programlisting>
-  {-# INLINE [~3] g #-}
-</programlisting>
-            </para>
-         </listitem>
-
+           <para>"<literal>INLINE[~k] f</literal>" means: be very keen to inline
+           <literal>f</literal>
+             until phase <literal>k</literal>, but from phase
+             <literal>k</literal> onwards do not inline it.
+            </para></listitem>
          <listitem>
-           <para>If you omit the phase indicator, you mean "inline in
-            all phases".</para>
-         </listitem>
+           <para>"<literal>NOINLINE[k] f</literal>" means: do not inline
+           <literal>f</literal>
+             until phase <literal>k</literal>, but from phase
+             <literal>k</literal> onwards be willing to inline it (as if
+             there was no pragma).
+            </para></listitem>
+           <listitem>
+           <para>"<literal>INLINE[~k] f</literal>" means: be willing to inline
+           <literal>f</literal>
+             until phase <literal>k</literal>, but from phase
+             <literal>k</literal> onwards do not inline it.
+            </para></listitem>
        </itemizedlist>
-
-       <para>You can use a phase number on a NOINLINE pragma too:</para>
-
-       <itemizedlist>
-         <listitem>
-           <para>You can say "do not inline <literal>f</literal>
-            until Phase 2; in Phase 2 and subsequently behave as if
-            there was no pragma at all":
+The same information is summarised here:
 <programlisting>
-  {-# NOINLINE [2] f #-}
-</programlisting>
-            </para>
-         </listitem>
+                           -- Before phase 2     Phase 2 and later
+  {-# INLINE   [2]  f #-}  --      No                 Yes
+  {-# INLINE   [~2] f #-}  --      Yes                No
+  {-# NOINLINE [2]  f #-}  --      No                 Maybe
+  {-# NOINLINE [~2] f #-}  --      Maybe              No
 
-         <listitem>
-           <para>You can say "do not inline <literal>g</literal> in
-            Phase 3 or any subsequent phase; before that, behave as if
-            there was no pragma":
-<programlisting>
-  {-# NOINLINE [~3] g #-}
+  {-# INLINE   f #-}       --      Yes                Yes
+  {-# NOINLINE f #-}       --      No                 No
 </programlisting>
-            </para>
-         </listitem>
-
-         <listitem>
-           <para>If you omit the phase indicator, you mean "never
-            inline this function".</para>
-         </listitem>
-       </itemizedlist>
-
-       <para>The same phase-numbering control is available for RULES
+By "Maybe" we mean that the usual heuristic inlining rules apply (if the
+function body is small, or it is applied to interesting-looking arguments etc).
+Another way to understand the semantics is this:
+<itemizedlist>
+<listitem><para>For both INLINE and NOINLINE, the phase number says
+when inlining is allowed at all.</para></listitem>
+<listitem><para>The INLINE pragma has the additional effect of making the
+function body look small, so that when inlining is allowed it is very likely to
+happen.
+</para></listitem>
+</itemizedlist>
+</para>
+<para>The same phase-numbering control is available for RULES
        (<xref linkend="rewrite-rules"/>).</para>
       </sect3>
     </sect2>