+<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.
+
+%************************************************************************
+%* *