[project @ 2002-09-28 07:12:55 by erkok]

clarifications on the mdo documentation.

diff --git a/ghc/docs/users_guide/glasgow_exts.sgml b/ghc/docs/users_guide/glasgow_exts.sgml
index bcc7d1e..b98d10b 100644 (file)
--- a/ghc/docs/users_guide/glasgow_exts.sgml
+++ b/ghc/docs/users_guide/glasgow_exts.sgml
@@ -4045,12 +4045,31 @@ the do-notation, and this extension provides the necessary syntactic support.
 Here is a simple (yet contrived) example:
 </para>
 <programlisting>
-import Control.Monad.MonadRec
-
 justOnes = mdo xs <- Just (1:xs)
                return xs
 </programlisting>
 <para>
+As you can guess <literal>justOnes</literal> will evaluate to <literal>Just [1,1,1,...</literal>.
+</para>
+
+<para>
+The MonadRec library introduces the <literal>MonadRec</literal> class. It's definition is:
+</para>
+<programlisting>
+class Monad m => MonadRec m where
+   mfix :: (a -> m a) -> m a
+</programlisting>
+<para>
+The function <literal>mfix</literal>
+dictates how the required recursion operation should be performed. If recursive bindings are required for a monad,
+then that monad must be declared an instance of the <literal>MonadRec</literal> class.
+For details, see the above mentioned reference.
+</para>
+<para>
+The <literal>MonadRec</literal> library automatically declares List, Maybe, IO, and
+state monads (both lazy and strict) as instances of the <literal>MonadRec</literal> class.
+</para>
+<para>
 There are three important points in using the recursive-do notation:
 <itemizedlist>
 <listitem><para>
@@ -4059,7 +4078,13 @@ than <literal>do</literal>).
 </para></listitem>
 
 <listitem><para>
-The scripts using <literal>mdo</literal> should <literal>import Control.Monad.MonadRec</literal>
+If you want to declare an instance of the <literal>MonadRec</literal> class for one of 
+your own monads, or you need to refer to the class name <literal>MonadRec</literal> in any other way (for instance in
+writing a type constraint), then your program should <literal>import Control.Monad.MonadRec</literal>.
+Otherwise, you don't need to import any special libraries to use the mdo-notation. That is,
+as long as you only use the predefined instances mentioned above, the mdo-notation will
+be automatically available. (Note: This differs from the Hugs implementation, where
+<literal>MonadRec</literal> should always be imported.)
 </para></listitem>
 
 <listitem><para>
@@ -4068,23 +4093,6 @@ As with other extensions, ghc should be given the flag <literal>-fglasgow-exts</
 </itemizedlist>
 </para>
 
-<para>
-The MonadRec library introduces the <literal>MonadRec</literal> class. It's definition is:
-</para>
-<programlisting>
-class Monad m => MonadRec m where
-   mfix :: (a -> m a) -> m a
-</programlisting>
-<para>
-The <literal>MonadRec</literal> class declares the function <literal>mfix</literal>, 
-which dictates how the recursion should behave. If recursive bindings are required for a monad,
-then that monad must be declared an instance of the <literal>MonadRec</literal> class.
-For details, see the above mentione reference.
-</para>
-<para>
-The MonadRec library automatically declares List, Maybe, IO, and
-state monads (both lazy and strict) as instances of the <literal>MonadRec</literal> class.
-</para>
 
 <para>
 The web page: <ulink url="http://www.cse.ogi.edu/PacSoft/projects/rmb">http://www.cse.ogi.edu/PacSoft/projects/rmb</ulink>