[project @ 2004-06-22 13:47:27 by simonpj]

Clarify words about the -package flag

ghc/docs/users_guide/packages.sgml

@@ -25,7 +25,8 @@
       <indexterm><primary>packages</primary>
 	<secondary>using</secondary></indexterm>
       
-      <para>Some packages are automatically available: you don't need
+      <para>Some packages,  called <emphasis>auto packages</emphasis>, 
+      are automatically available: you don't need
       to specify any extra flags to use them (except in certain
       circumstances; see below).  All the packages which contain
       hierarchical libraries fall into this category.</para>
@@ -46,13 +47,20 @@
 	    be imported in your Haskell source, however).  It also
 	    causes the relevant libraries to be linked when linking is
 	    being done.</para>
+      	    <para>Some packages depend on other packages, for example the
+      	    <literal>text</literal> package makes use of some of the modules
+      	    in the <literal>lang</literal> package.  The package system
+      	    takes care of all these dependencies, so that when you say
+      	    <literal>-package text</literal> on the command line, you
+      	    automatically get <literal>-package lang</literal> too.</para>
 	  </listitem>
 	</varlistentry>
       </variablelist>
 
       <para>There's one case where you need to use the
       <option>-package</option> option even for auto packages: when
-      linking a program in batch mode<footnote><para>This is because
+      linking a program in batch mode mode (<xref linkend="options-order">) 
+      <footnote><para>This is because
       GHC can't figure out from the object files which packages are
       required; in <option>&ndash;&ndash;make</option> mode and in
       GHCi the compiler has more information available to figure out
@@ -60,18 +68,20 @@
       in the future.</para></footnote>.  For example, to link a
       program consisting of objects <filename>Foo.o</filename> and
       <filename>Main.o</filename>, where we made use of the
-      <literal>network</literal> package:</para>
+      <literal>network</literal> package, we need to give GHC the <literal>-package</literal> flag thus: 
 
 <screen>$ ghc -o myprog Foo.o Main.o -package network</screen>
 
-      <para>Some packages depend on other packages, for example the
-      <literal>text</literal> package makes use of some of the modules
-      in the <literal>lang</literal> package.  The package system
-      takes care of all these dependencies, so that when you say
-      <literal>-package text</literal> on the command line, you
-      automatically get <literal>-package lang</literal> too.</para>
+    The same flag is necessary even if we compiled the modules from source, because GHC still
+    reckons it's in batch mode:
+<screen>$ ghc -o myprog Foo.hs Main.hs -package network</screen>
+In <literal>--make</literal> and <literal>--interactive</literal> modes (<xref linkend="modes">), however, GHC figures out 
+the auto packages required for linking without further assistance.
+</para>
+
     </sect2>
 
+
     <sect2 id="using-local-packages">
       <title>Maintaining a local set of packages</title>
       

ghc/docs/users_guide/using.sgml

@@ -405,7 +405,7 @@ olleh
     <sect2 id="options-order">
       <title>Batch compiler mode</title>
       
-      <para>In this mode, GHC will compile one or more source files
+      <para>In <emphasis>batch mode</emphasis>, GHC will compile one or more source files
       given on the command line.</para>
       
       <para>The first phase to run is determined by each input-file