[project @ 2005-02-01 17:49:02 by simonpj]

Finish docs for hs-boot files; please review!

diff --git a/ghc/docs/users_guide/separate_compilation.xml b/ghc/docs/users_guide/separate_compilation.xml
index cb80aad..17a896c 100644 (file)
--- a/ghc/docs/users_guide/separate_compilation.xml
+++ b/ghc/docs/users_guide/separate_compilation.xml
@@ -653,20 +653,6 @@ version of <filename>A.hs</filename>, thus:
 module A where
     newtype TA = MkTA Int
 </programlisting>
-A <filename>hs-boot</filename> file is compiled by GHC, just like a <filename>hs</filename> file:
-<programlisting>
-  ghc -c A.hs-boot
-</programlisting>
-Just as compiling <filename>A.hs</filename> produces an
-interface file <filename>A.hi</filename>, and an object file
-<filename>A.o</filename>, so compiling <filename>A.hs-boot</filename>
-produces an interface file
-<filename>A.hi-boot</filename>, and an pseudo-object file
-<filename>A.o-boot</filename>.  The interface file
-<filename>A.hi-boot</filename> has exactly the same format as any
-other interface file.  The pseudo-object file is empty (don't link it!), but it is
-very useful when using a Makefile, to record when the <filename>A.hi-boot</filename> was
-last brought up to date.
 </para>
 <para>To compile these three files, issue the following commands:
 <programlisting>
@@ -681,26 +667,44 @@ last brought up to date.
 <listitem>
   <para>The file <filename>A.hs-boot</filename> is a programmer-written source file.
   It must live in the same directory as its parent source file <filename>A.hs</filename>.
-  (Currently, if you use a literate source file <filename>A.lhs</filename> you must
-  also use a literate boot file, <filename>A.lhs-boot</filename>.)
+  Currently, if you use a literate source file <filename>A.lhs</filename> you must
+  also use a literate boot file, <filename>A.lhs-boot</filename>; and vice versa.
   </para></listitem>
 
-  <listitem><para> The <filename>hi-boot</filename> generated by compiling a <filename>hs-boot</filename>
-  file is in machine-generated binary format.
-  You can display its contents with <command>ghc --show-iface</commaond>. If you 
-  specify a directory for interface files, the <option>-ohidir</option> flag, then that affects
-  <filename>hi-boot</filename> files too.</para></listitem>b
-
-   <listitem><para> Hs-boot files are written in a subset of Haskell.  In particular, the module
-   exports and imports, and the scoping rules are exactly the same as in Haskell. Hence, to
-   mention a non-Prelude type or class, you must import it.</para></listitem>
-   
-   <listitem><para> When a hs-boot file <filename>A.hs-boot</filename> 
+<listitem><para>
+  A <filename>hs-boot</filename> file is compiled by GHC, just like a <filename>hs</filename> file:
+<programlisting>
+  ghc -c A.hs-boot
+</programlisting>
+When a hs-boot file <filename>A.hs-boot</filename> 
    is compiled, it is checked for scope and type errors.
    When its parent module <filename>A.hs</filename> is compiled, the two are compared, and
    an error is reported if the two are inconsistent.
    </para></listitem>
    
+<listitem><para> Just as compiling <filename>A.hs</filename> produces an
+interface file <filename>A.hi</filename>, and an object file
+<filename>A.o</filename>, so compiling <filename>A.hs-boot</filename>
+produces an interface file
+<filename>A.hi-boot</filename>, and an pseudo-object file
+<filename>A.o-boot</filename>:  
+<itemizedlist>
+<listitem><para>
+The pseudo-object file <filename>A.o-boot</filename> is empty (don't link it!), but it is
+very useful when using a Makefile, to record when the <filename>A.hi-boot</filename> was
+last brought up to date (see <xref linkend="using-make"/>).
+</para>
+</listitem>
+
+  <listitem><para> The <filename>hi-boot</filename> generated by compiling a <filename>hs-boot</filename>
+  file is in the same machine-generated binary format as any other
+  GHC-generated interface file (e.g. <filename>B.hi</filename>).
+  You can display its contents with <command>ghc --show-iface</command>. If you 
+  specify a directory for interface files, the <option>-ohidir</option> flag, then that affects
+  <filename>hi-boot</filename> files too.</para></listitem>b
+</itemizedlist>
+</para></listitem>
+
    <listitem><para> If hs-boot files are considered distinct from their parent source
    files, and if a <literal>{-# SOURCE #-}</literal> import is considered to refer to the
    hs-boot file, then the module import graph must have no cycles.  The <command>ghc -M</command>
@@ -717,7 +721,10 @@ A hs-boot file need only contain the bare
       module that imports <literal>A</literal> recursively.</para>
 <para>A hs-boot file is written in a subset of Haskell:
 <itemizedlist>
-<listitem><para> The module header, and import statements, are exactly as in Haskell.</para></listitem>
+<listitem><para> The module header (including the export list), and import statements, are exactly as in
+Haskell, and so are the scoping rules.  
+   Hence, to mention a non-Prelude type or class, you must import it.</para></listitem>
+   
 <listitem><para> There must be no value declarations, but there can be type signatures for
 values.  For example:
 <programlisting>
@@ -823,16 +830,16 @@ Main.o Main.hc Main.s : Foo.hi Baz.hi   # Main imports Foo and Baz
       doing&hellip;nothing.  Which is true.</para>
       <para> Note that the suffix rules are all repeated twice, once
       for normal Haskell source files, and once for <filename>hs-boot</filename>
-      files (see <xref linkend="mutual-recursion"/>).
+      files (see <xref linkend="mutual-recursion"/>).</para>
 
-      <para>Note the inter-module dependencies at the end of the
-      Makefile, which take the form</para>
+      <para>Note also the inter-module dependencies at the end of the
+      Makefile, which take the form
 
 <programlisting>
 Foo.o Foo.hc Foo.s    : Baz.hi          # Foo imports Baz
 </programlisting>
 
-      <para>They tell <command>make</command> that if any of
+      They tell <command>make</command> that if any of
       <literal>Foo.o</literal>, <literal>Foo.hc</literal> or
       <literal>Foo.s</literal> have an earlier modification date than
       <literal>Baz.hi</literal>, then the out-of-date file must be