diff --git a/ghc/docs/users_guide/using.vsgml b/ghc/docs/users_guide/using.vsgml
index 254eb0d362785c95ef5871c20e67b9988adc7a3c..d2b35a11c829537903dc693a0ef68642759be29e 100644
--- a/ghc/docs/users_guide/using.vsgml
+++ b/ghc/docs/users_guide/using.vsgml
@@ -457,26 +457,38 @@ In your program, you import a module @Foo@ by saying
It has a builtin list of directories (notably including @.@) where
it looks.
-The @-i<dirs>@ option<nidx>-i<dirs> option</nidx> prepends a
-colon-separated list of @dirs@ to the ``import directories'' list.
+<descrip>
+
+<tag>@-i<dirs>@</tag><nidx>-i<dirs> option</nidx> This flag
+prepends a colon-separated list of @dirs@ to the ``import
+directories'' list.
+
+<tag>@-i@</tag> resets the ``import directories'' list back to nothing.
+
+<tag>@-fno-implicit-prelude@
+<nidx>-fno-implicit-prelude option</nidx>
+GHC normally imports @Prelude.hi@ files for you. If you'd rather it
+didn't, then give it a @-fno-implicit-prelude@ option. You are
+unlikely to get very far without a Prelude, but, hey, it's a free
+country.
-A plain @-i@ resets the ``import directories'' list back to nothing.
+<tag>@-syslib <lib>@</tag>
+<nidx>-syslib <lib> option</nidx>
-GHC normally imports @Prelude.hi@ files for you. If you'd rather
-it didn't, then give it a @-fno-implicit-prelude@
-option<nidx>-fno-implicit-prelude option</nidx>. You are unlikely to get
-very far without a Prelude, but, hey, it's a free country.
+If you are using a system-supplied non-Prelude library (e.g., the
+POSIX library), just use a @-syslib posix@ option (for example). The
+right interface files should then be available. Section <ref
+name="The GHC Prelude and Libraries" id="ghc-prelude"> lists the
+libraries available by this mechanism.
-If you are using a system-supplied non-Prelude library (e.g., the HBC
-library), just use a @-syslib hbc@<nidx>-syslib <lib> option</nidx>
-option (for example). The right interface files should then be
-available.
+<tag>@-I<dir>@</tag>
+<nidx>-I<dir> option</nidx>
Once a Haskell module has been compiled to C (@.hc@ file), you may
-wish to specify where GHC tells the C compiler to look for @.h@
-files. (Or, if you are using the @-cpp@ option<nidx>-cpp option</nidx>,
-where it tells the C pre-processor to look...) For this purpose, use
-a @-I<dir>@<nidx>-I<dir> option</nidx> in the usual C-ish way.
+wish to specify where GHC tells the C compiler to look for @.h@ files.
+(Or, if you are using the @-cpp@ option<nidx>-cpp option</nidx>, where
+it tells the C pre-processor to look...) For this purpose, use a @-I@
+option in the usual C-ish way.
%************************************************************************
%* *
@@ -523,8 +535,9 @@ turned off with @-fno-prune-tydecls@ and @-fno-prune-instdecls@.
<nidx>-fno-prune-tydecls option</nidx><nidx>-fno-prune-instdecls
option</nidx>
-See also Section <ref name="Linking and consistency-checking" id="options-linker">, which describes how the linker
-finds standard Haskell libraries.
+See also Section <ref name="Linking and consistency-checking"
+id="options-linker">, which describes how the linker finds standard
+Haskell libraries.
%************************************************************************
%* *
@@ -669,6 +682,90 @@ again, it may take multiple iterations to ``settle.''
</itemize>
+%************************************************************************
+%* *
+<sect2>How to compile mutually recursive modules
+<label id="mutual-recursion">
+<p>
+<nidx>module system, recursion</nidx>
+<nidx>recursion, between modules</nidx>
+%* *
+%************************************************************************
+
+Currently, the compiler does not have proper support for dealing with
+mutually recursive modules:
+
+<tscreen><verb>
+module A where
+
+import B
+
+newtype A = A Int
+
+f :: B -> A
+f (B x) = A x
+--------
+module B where
+
+import A
+
+data B = B !Int
+
+g :: A -> B
+g (A x) = B x
+</verb></tscreen>
+
+When compiling either module A and B, the compiler will try (in vain)
+to look for the interface file of the other. So, to get mutually
+recursive modules off the ground, you need to hand write an interface
+file for A or B, so as to break the loop. These hand-written
+interface files are called @hi-boot@ files, and are placed in a file
+called @<module>.hi-boot@. To import from an @hi-boot@ file instead
+of the standard @.hi@ file, use the following syntax in the importing module:
+<nidx>hi-boot files</nidx>
+<nidx>importing, hi-boot files</nidx>
+
+<tscreen> <verb>
+import {-# SOURCE #-} A
+</verb> <tscreen>
+
+The hand-written interface need only contain the bare minimum of
+information needed to get the bootstrapping process started. For
+example, it doesn't need to contain declarations for <em/everything/
+that module @A@ exports, only the things required by the module that
+imports @A@ recursively.
+
+For the example at hand, the boot interface file for A would like the
+following:
+
+<tscreen><verb>
+_interface_ A 1
+_exports_
+A(A);
+_declarations_
+1 newtype A = A PrelBase.Int ;
+</verb></tscreen>
+
+The syntax is essentially the same as a normal @.hi@ file
+(unfortunately), but you can usually tailor an existing @.hi@ file to
+make a @.hi-boot@ file.
+
+Notice that we only put the declaration for the newtype @A@ in the
+@hi-boot@ file, not the signature for @f@, since @f@ isn't used by
+@B@.
+
+The number ``1'' at the beginning of a declaration is the <em>version
+number</em> of that declaration: for the purposes of @.hi-boot@ files
+these can all be set to 1. All names must be fully qualified with the
+<em/original/ module that an object comes from: for example, the
+reference to @Int@ in the interface for @A@ comes from @PrelBase@,
+which is a module internal to GHC's prelude. It's a pain, but that's
+the way it is.
+
+<bf>Note:</bf> This is all a temporary solution, a version of the
+compiler that handles mutually recursive properly without the manual
+construction of interface file, is in the works.
+
%************************************************************************
%* *
<sect1>Optimisation (code improvement)