X-Git-Url: http://git.megacz.com/?a=blobdiff_plain;f=ghc%2Fdocs%2Fusers_guide%2Fusing.sgml;h=8d6d658536eb2fc272279133e5e36c73d2b01107;hb=9cd3ca368ac5342202ad286885b1ac9c196ecd7c;hp=844a0f8cd4cfec94c8086f2ffe4dd513aefde77b;hpb=43194a1df3c68cf426a4b782befa526163e88ee6;p=ghc-hetmet.git

diff --git a/ghc/docs/users_guide/using.sgml b/ghc/docs/users_guide/using.sgml
index 844a0f8..8d6d658 100644
--- a/ghc/docs/users_guide/using.sgml
+++ b/ghc/docs/users_guide/using.sgml
@@ -358,13 +358,79 @@ standard <Filename>.hi</Filename>/<Filename>.o</Filename> suffixes; add <Option>
 <Command>make</Command> rule for GHC compiling&hellip;
 </Para>
 
-<Para>
-FURTHER EXOTICA: If you are doing a normal <Filename>.hs</Filename>-to-<Filename>.o</Filename> compilation
-but would like to hang onto the intermediate <Filename>.hc</Filename> C file, just
-throw in a <Option>-keep-hc-file-too</Option> option<IndexTerm><Primary>-keep-hc-file-too option</Primary></IndexTerm>.
-If you would like to look at the assembler output, toss in a
-<Option>-keep-s-file-too</Option>,<IndexTerm><Primary>-keep-s-file-too option</Primary></IndexTerm> too.
-</Para>
+    <sect2 id="keeping-intermediates">
+      <title>Keeping Intermediate Files</title>
+      <indexterm><primary>intermediate files, saving</primary>
+      </indexterm>
+      <indexterm><primary><literal>.hc</literal> files, saving</primary>
+      </indexterm>
+      <indexterm><primary><literal>.s</literal> files, saving</primary>
+      </indexterm>
+
+      <para>The following options are useful for keeping certain
+      intermediate files around, when normally GHC would throw these
+      away after compilation:</para>
+
+      <variablelist>
+	<varlistentry>
+	  <term><literal>-keep-hc-files</literal></term>
+	  <indexterm>
+	    <primary><literal>-keep-hc-files</literal></primary>
+	  </indexterm>
+	  <listitem>
+	    <para>Keep intermediate <literal>.hc</literal> files when
+	    doing <literal>.hs</literal>-to-<literal>.o</literal>
+	    compilations via C (NOTE: <literal>.hc</literal> files
+	    aren't generated when using the native code generator, you
+	    may need to use <literal>-fvia-C</literal> to force them
+	    to be produced).</para>
+	  </listitem>
+	</varlistentry>
+
+	<varlistentry>
+	  <term><literal>-keep-s-files</literal></term>
+	  <indexterm>
+	    <primary><literal>-keep-s-files</literal></primary>
+	  </indexterm>
+	  <listitem>
+	    <para>Keep intermediate <literal>.s</literal> files.</para>
+	  </listitem>
+	</varlistentry>
+
+	<varlistentry>
+	  <term><literal>-keep-raw-s-files</literal></term>
+	  <indexterm>
+	    <primary><literal>-keep-raw-s-files</literal></primary>
+	  </indexterm>
+	  <listitem>
+	    <para>Keep intermediate <literal>.raw-s</literal> files.
+	    These are the direct output from the C compiler, before
+	    GHC does &ldquo;assembly mangling&rdquo; to produce the
+	    <literal>.s</literal> file.  Again, these are not produced
+	    when using the native code generator.</para>
+	  </listitem>
+	</varlistentry>
+
+	<varlistentry>
+	  <term><literal>-keep-tmp-files</literal></term>
+	  <indexterm>
+	    <primary><literal>-keep-tmp-files</literal></primary>
+	  </indexterm>
+	  <indexterm>
+	    <primary>temporary files</primary>
+	    <secondary>keeping</secondary>
+	  </indexterm>
+	  <listitem>
+	    <para>Instructs the GHC driver not to delete any of its
+	    temporary files, which it normally keeps in
+	    <literal>/tmp</literal> (or possibly elsewhere; see <xref
+	    linkend="temp-files">).  Running GHC with
+	    <literal>-v</literal> will show you what temporary files
+	    were generated along the way.</para>
+	  </listitem>
+	</varlistentry>
+      </variablelist>
+    </sect2>
 
 <Sect2 id="saving-ghc-stderr">
 <Title>Saving GHC's standard error output
@@ -387,23 +453,27 @@ output to a particular log file with a <Option>-odump &lt;blah&gt;</Option><Inde
 <Title>Redirecting temporary files
 </Title>
 
-<Para>
-<IndexTerm><Primary>temporary files, redirecting</Primary></IndexTerm>
-</Para>
+      <indexterm>
+	<primary>temporary files</primary>
+	<secondary>redirecting</secondary>
+      </indexterm>
 
 <Para>
-If you have trouble because of running out of space in <Filename>/tmp</Filename> (or
-wherever your installation thinks temporary files should go), you may
-use the <Option>-tmpdir &lt;dir&gt;</Option><IndexTerm><Primary>-tmpdir &lt;dir&gt; option</Primary></IndexTerm> option
-to specify an alternate directory.  For example, <Option>-tmpdir .</Option> says to
-put temporary files in the current working directory.
+If you have trouble because of running out of space in
+<Filename>/tmp</Filename> (or wherever your installation thinks
+temporary files should go), you may use the <Option>-tmpdir
+&lt;dir&gt;</Option><IndexTerm><Primary>-tmpdir &lt;dir&gt;
+option</Primary></IndexTerm> option to specify an alternate directory.
+For example, <Option>-tmpdir .</Option> says to put temporary files in
+the current working directory.
 </Para>
 
 <Para>
-Alternatively, use your <Constant>TMPDIR</Constant> environment variable.<IndexTerm><Primary>TMPDIR
-environment variable</Primary></IndexTerm> Set it to the name of the directory where
-temporary files should be put.  GCC and other programs will honour the
-<Constant>TMPDIR</Constant> variable as well.
+Alternatively, use your <Constant>TMPDIR</Constant> environment
+variable.<IndexTerm><Primary>TMPDIR environment
+variable</Primary></IndexTerm> Set it to the name of the directory
+where temporary files should be put.  GCC and other programs will
+honour the <Constant>TMPDIR</Constant> variable as well.
 </Para>
 
 <Para>
@@ -704,9 +774,6 @@ sanity, not yours.)
 <IndexTerm><Primary>separate compilation</Primary></IndexTerm>
 <IndexTerm><Primary>recompilation checker</Primary></IndexTerm>
 <IndexTerm><Primary>make and recompilation</Primary></IndexTerm>
-</Para>
-
-<Para>
 This section describes how GHC supports separate compilation.
 </Para>
 
@@ -822,23 +889,41 @@ resets the &ldquo;import directories&rdquo; list back to nothing.
 <Para>
 <IndexTerm><Primary>-fno-implicit-prelude option</Primary></IndexTerm>
 GHC normally imports <Filename>Prelude.hi</Filename> files for you.  If you'd rather it
-didn't, then give it a <Option>-fno-implicit-prelude</Option> option.  You are
-unlikely to get very far without a Prelude, but, hey, it's a free
-country.
+didn't, then give it a <Option>-fno-implicit-prelude</Option> option.  
+The idea is that you can then import a Prelude of your own.  (But don't call it <Literal>Prelude</Literal>;
+the Haskell module namespace is flat, and you must not conflict with any Prelude module.)
+</Para>
+<Para>
+Even though you have not imported the Prelude, all the built-in syntax still refers to 
+the built-in Haskell Prelude types and values, as specified by the Haskell Report.  
+For example, the type <Literal>[Int]</Literal>
+still means <Literal>Prelude.[] Int</Literal>; tuples continue to refer to the standard Prelude
+tuples; the translation for list comprehensions continues to use <Literal>Prelude.map</Literal> etc.
+</Para>
+<Para> With one group of exceptions!  You may want to define your own numeric class hierarchy.
+It completely defeats that purpose if the literal "1" means "<Literal>Prelude.fromInteger 1</Literal>",
+which is what the Haskell Report specifies.  So the <Option>-fno-implicit-prelude</Option> flag causes
+the following pieces of built-in syntax to refer to whatever is in scope, not the Prelude versions:
+<ItemizedList>
+<ListItem>
+<Para>
+Integer and fractional literals mean "<Literal>fromInteger 1</Literal>" and "<Literal>fromRational 3.2</Literal>",
+not the Prelude-qualified versions; both in expressions and in patterns.
+</Para>
+</ListItem>
+<ListItem>
+<Para>
+Negation (e.g. "<Literal>- (f x)</Literal>") means "<Literal>negate (f x)</Literal>" (not <Literal>Prelude.negate</Literal>).
 </Para>
 </ListItem>
-</VarListEntry>
-
-<VarListEntry>
-<Term><Option>-syslib &lt;lib&gt;</Option></Term>
 <ListItem>
 <Para>
-<IndexTerm><Primary>-syslib &lt;lib&gt; option</Primary></IndexTerm>
-If you are using a system-supplied non-Prelude library (e.g., the
-POSIX library), just use a <Option>-syslib posix</Option> option (for
-example).  The right interface files should then be available.  The
-accompanying HsLibs document lists the libraries available by this
-mechanism.
+In an n+k pattern, the standard Prelude <Literal>Ord</Literal> class is used for comparison, but the 
+necessary subtraction uses 
+whatever "<Literal>(-)</Literal>" is in scope (not "<Literal>Prelude.(-)</Literal>").
+</Para>
+</ListItem>
+</ItemizedList>
 </Para>
 </ListItem>
 </VarListEntry>
@@ -935,9 +1020,19 @@ Haskell libraries.
 <IndexTerm><Primary><option>-recomp</option> option</Primary></IndexTerm>
 <ListItem>
 <Para>
-Turn on recompilation checking.  This will stop compilation early,
-leaving an existing <filename>.o</filename> file in place, if it can
-be determined that the module does not need to be recompiled.
+(On by default) Turn on recompilation checking.  This will stop
+compilation early, leaving an existing <filename>.o</filename> file in
+place, if it can be determined that the module does not need to be
+recompiled.
+</Para>
+</ListItem>
+</VarListEntry>
+<VarListEntry>
+<Term><Option>-no-recomp</Option></Term>
+<IndexTerm><Primary><option>-recomp</option> option</Primary></IndexTerm>
+<ListItem>
+<Para>
+Turn off recompilation checking.
 </Para>
 </ListItem>
 </VarListEntry>
@@ -980,34 +1075,13 @@ sight!
 </Para>
 
 <Para>
-GHC <Emphasis>only</Emphasis> keeps detailed dependency information
-for &ldquo;user&rdquo; modules, not for &ldquo;library&rdquo; modules.
-It distinguishes the two by a hack: a module whose
-<Filename>.hi</Filename> file has an absolute path name is considered
-a library module, while a relative path name indicates a user module.
-So if you have a multi-directory application, use
-<Emphasis>relative</Emphasis> path names in your <Option>-i</Option>
-path, to force GHC to record detailed dependency information.  Use
-absolute path names only for directories containing slowly-changing
-library modules.
-</Para>
-
-<Para>
-A path is considered &ldquo;absolute&rdquo; if it starts with
-&ldquo;<Filename>/</Filename>&rdquo;, or
-&ldquo;<Filename>A:/</Filename>&rdquo;, or
-&ldquo;<Filename>A:\</Filename>&rdquo; (or
-&ldquo;<Filename>B:/</Filename>&rdquo;,
-&ldquo;<Filename>B:\</Filename>&rdquo; etc).
-</Para>
-
-<Para>
 Patrick Sansom had a workshop paper about how all this is done (though
 the details have changed quite a bit). <ULink URL="mailto:sansom@dcs.gla.ac.uk">Ask him</ULink> if you want a copy.
 </Para>
 
 </Sect2>
 
+
 <Sect2 id="using-make">
 <Title>Using <Command>make</Command>
 </Title>
@@ -1017,8 +1091,7 @@ the details have changed quite a bit). <ULink URL="mailto:sansom@dcs.gla.ac.uk">
 </Para>
 
 <Para>
-It is reasonably straightforward to set up a <Filename>Makefile</Filename> to use with
-GHC, assuming you name your source files the same as your modules.
+It is reasonably straightforward to set up a <Filename>Makefile</Filename> to use with GHC, assuming you name your source files the same as your modules.
 Thus:
 </Para>
 
@@ -1031,7 +1104,7 @@ HC_OPTS = -cpp $(EXTRA_HC_OPTS)
 SRCS = Main.lhs Foo.lhs Bar.lhs
 OBJS = Main.o   Foo.o   Bar.o
 
-.SUFFIXES : .o .hi .lhs .hc .s
+.SUFFIXES : .o .hs .hi .lhs .hc .s
 
 cool_pgm : $(OBJS)
         rm $@
@@ -1100,65 +1173,201 @@ a rule to do so; one of the preceding suffix rules does the job
 nicely.
 </Para>
 
-<Para>
-Putting inter-dependencies of the form <Literal>Foo.o : Bar.hi</Literal> into your
-<Filename>Makefile</Filename> by hand is rather error-prone.  Don't worry&mdash;never fear,
-<Command>mkdependHS</Command> is here! (and is distributed as part of GHC) Add the
-following to your <Filename>Makefile</Filename>:
-</Para>
+    </sect2>
 
-<Para>
+    <sect2 id="sec-makefile-dependencies">
+      <title>Dependency generation</title>
+      <indexterm><primary>dependencies in Makefiles</primary></indexterm>
+      <indexterm><primary>Makefile dependencies</primary></indexterm>
+
+      <para>Putting inter-dependencies of the form <Literal>Foo.o :
+      Bar.hi</Literal> into your <Filename>Makefile</Filename> by hand
+      is rather error-prone.  Don't worry, GHC has support for
+      automatically generating the required dependencies.  Add the
+      following to your <Filename>Makefile</Filename>:</para>
 
 <ProgramListing>
 depend :
-        mkdependHS -- $(HC_OPTS) -- $(SRCS)
+        ghc -M $(HC_OPTS) $(SRCS)
 </ProgramListing>
 
-</Para>
-
-<Para>
-Now, before you start compiling, and any time you change the <Literal>imports</Literal>
-in your program, do <Command>make depend</Command> before you do <Command>make cool&lowbar;pgm</Command>.
-<Command>mkdependHS</Command> will append the needed dependencies to your <Filename>Makefile</Filename>.
-<Command>mkdependHS</Command> is fully described in <XRef LinkEnd="mkdependHS">.
-</Para>
-
-<Para>
-A few caveats about this simple scheme:
-</Para>
-
-<Para>
-
-<ItemizedList>
-<ListItem>
-
-<Para>
- You may need to compile some modules explicitly to create their
-interfaces in the first place (e.g., <Command>make Bar.o</Command> to create <Filename>Bar.hi</Filename>).
-
-</Para>
-</ListItem>
-<ListItem>
-
-<Para>
- You may have to type <Command>make</Command> more than once for the dependencies
-to have full effect.  However, a <Command>make</Command> run that does nothing
-<Emphasis>does</Emphasis> mean &ldquo;everything's up-to-date.&rdquo;
-
-</Para>
-</ListItem>
-<ListItem>
-
-<Para>
- This scheme will work with mutually-recursive modules but,
-again, it may take multiple iterations to &ldquo;settle.&rdquo;
-
-</Para>
-</ListItem>
-
-</ItemizedList>
-
-</Para>
+      <para>Now, before you start compiling, and any time you change
+      the <Literal>imports</Literal> in your program, do <Command>make
+      depend</Command> before you do <Command>make
+      cool&lowbar;pgm</Command>.  <Command>ghc -M</Command> will append
+      the needed dependencies to your
+      <Filename>Makefile</Filename>.</Para>
+
+      <para>In general, if module <Literal>A</Literal> contains the
+      line
+
+<programlisting>
+import B ...blah...
+</programlisting>
+
+       then <command>ghc -M</command> will generate a dependency
+       line of the form:
+
+<programlisting>
+A.o : B.hi
+</programlisting>
+
+       If module <literal>A</literal> contains the line 
+
+<programlisting>
+import {-# SOURCE #-} B ...blah...
+</programlisting>
+
+       then <command>ghc -M</command> will generate a dependency
+       line of the form:
+
+<programlisting>
+A.o : B.hi-boot
+</programlisting>
+
+       (See <xref linkend="hi-files"> for details of interface files.)
+       If <literal>A</literal> imports multiple modules, then there
+       will be multiple lines with <filename>A.o</filename> as the
+       target.</para>
+
+      <para>By default, <Command>ghc -M</Command> generates all the
+      dependencies, and then concatenates them onto the end of
+      <Filename>makefile</Filename> (or <Filename>Makefile</Filename>
+      if <Filename>makefile</Filename> doesn't exist) bracketed by the
+      lines "<Literal>&num; DO NOT DELETE: Beginning of Haskell
+      dependencies</Literal>" and "<Literal>&num; DO NOT DELETE: End
+      of Haskell dependencies</Literal>".  If these lines already
+      exist in the <Filename>makefile</Filename>, then the old
+      dependencies are deleted first.</para>
+
+      <para>Internally, GHC uses a script to generate the
+      dependencies, called <command>mkdependHS</command>.  This script
+      has some options of its own, which you might find useful.
+      Options can be passed directly to <command>mkdependHS</command>
+      with GHC's <literal>-optdep</literal> option.  For example, to
+      generate the dependencies into a file called
+      <literal>.depend</literal> instead of
+      <literal>Makefile</literal>:</para>
+
+<screen>
+ghc -M -optdep-f optdep.depend ...
+</screen>
+      
+      <para>The full list of options accepted by
+      <command>mkdependHS</command> is:</para>
+
+      <variablelist>
+
+	<varlistentry>
+	  <term><option>-w</option></term>
+	  <listitem>
+	    <para>Turn off warnings about interface file shadowing.</para>
+	  </listitem>
+	</varlistentry>
+
+	<varlistentry>
+	  <term><option>-f blah</option></term>
+	  <listitem>
+	    <para>Use <Filename>blah</Filename> as the makefile,
+            rather than <Filename>makefile</Filename> or
+            <Filename>Makefile</Filename>.  If
+            <Filename>blah</Filename> doesn't exist,
+            <Command>mkdependHS</Command> creates it.  We often use
+            <Option>-f .depend</Option> to put the dependencies in
+            <Filename>.depend</Filename> and then
+            <Command>include</Command> the file
+            <Filename>.depend</Filename> into
+            <Filename>Makefile</Filename>.</para>
+	  </listitem>
+	</varlistentry>
+
+	<varlistentry>
+	  <term><option>-o &lt;osuf&gt;</option></term>
+	  <listitem>
+	    <para>Use <Filename>.&lt;osuf&gt;</Filename> as the
+            "target file" suffix ( default: <Literal>o</Literal>).
+            Multiple <Option>-o</Option> flags are permitted (GHC2.05
+            onwards).  Thus "<Option>-o hc -o o</Option>" will
+            generate dependencies for <Filename>.hc</Filename> and
+            <Filename>.o</Filename> files.</para>
+	  </listitem>
+	</varlistentry>
+
+	<varlistentry>
+	  <term><option>-s &lt;suf&gt;</option></term>
+	  <listitem>
+	    <para>Make extra dependencies that declare that files with
+            suffix
+            <Filename>.&lt;suf&gt;&lowbar;&lt;osuf&gt;</Filename>
+            depend on interface files with suffix
+            <Filename>.&lt;suf&gt;&lowbar;hi</Filename>, or (for
+            <Literal>&lcub;-&num; SOURCE &num;-&rcub;</Literal>
+            imports) on <Filename>.hi-boot</Filename>.  Multiple
+            <Option>-s</Option> flags are permitted.  For example,
+            <Option>-o hc -s a -s b</Option> will make dependencies
+            for <Filename>.hc</Filename> on <Filename>.hi</Filename>,
+            <Filename>.a&lowbar;hc</Filename> on
+            <Filename>.a&lowbar;hi</Filename>, and
+            <Filename>.b&lowbar;hc</Filename> on
+            <Filename>.b&lowbar;hi</Filename>.  (Useful in conjunction
+            with NoFib "ways".)</para>
+	  </listitem>
+	</varlistentry>
+
+	<varlistentry>
+	  <term><option>--exclude-module=&lt;file&gt;</option></term>
+	  <listitem>
+	    <para>Regard <Filename>&lt;file&gt;</Filename> as
+            "stable"; i.e., exclude it from having dependencies on
+            it.</para>
+	  </listitem>
+	</varlistentry>
+
+	<varlistentry>
+	  <term><option>-x</option></term>
+	  <listitem>
+	    <para>same as <option>--exclude-module</option></para>
+	  </listitem>
+	</varlistentry>
+
+	<varlistentry>
+	  <term><option>--exclude-directory=&lt;dirs&gt;</option></term>
+	  <listitem>
+	    <para>Regard the colon-separated list of directories
+            <Filename>&lt;dirs&gt;</Filename> as containing stable,
+            don't generate any dependencies on modules therein.</para>
+	  </listitem>
+	</varlistentry>
+
+	<varlistentry>
+	  <term><option>-xdirs</option></term>
+	  <listitem>
+	    <para>same as <Option>--exclude-directory</Option>.</para>
+	  </listitem>
+	</varlistentry>
+
+	<varlistentry>
+	  <term><option>--include-module=&lt;file&gt;</option></term>
+	  <listitem>
+	    <para>Regard <Filename>&lt;file&gt;</Filename> as not
+            "stable"; i.e., generate dependencies on it (if any). This
+            option is normally used in conjunction with the
+            <Option>--exclude-directory</Option> option.</para>
+	  </listitem>
+	</varlistentry>
+
+	<varlistentry>
+	  <term><option>--include-prelude</option></term>
+	  <listitem>
+	    <para>Regard prelude libraries as unstable, i.e., generate
+            dependencies on the prelude modules used (including
+            <Literal>Prelude</Literal>).  This option is normally only
+            used by the various system libraries. If a
+            <Option>-package</Option> option is used, dependencies will
+            also be generated on the library's interfaces.</para>
+	  </listitem>
+	</varlistentry>
+      </variablelist>
 
 </Sect2>
 
@@ -1302,6 +1511,360 @@ construction of interface files, is (allegedly) in the works.
 
 </Sect1>
 
+  <sect1 id="packages">
+    <title>Packages</title>
+    <indexterm><primary>packages</primary></indexterm>
+
+    <para>Packages are collections of libraries, conveniently grouped
+    together as a single entity.  The package system is flexible: a
+    package may consist of Haskell code, foreign language code (eg. C
+    libraries), or a mixture of the two.  A package is a good way to
+    group together related Haskell modules, and is essential if you
+    intend to make the modules into a Windows DLL (see below).</para>
+
+    <para>Because packages can contain both Haskell and C libraries, they
+    are also a good way to provide convenient access to a Haskell
+    layer over a C library.</para>
+
+    <para>GHC comes with several packages (see <xref
+    linkend="book-hslibs">), and packages can be added/removed from an
+    existing GHC installation.</para>
+
+    <sect2 id="listing-packages">
+      <title>Listing the available packages</title>
+      <indexterm><primary>packages</primary>
+	<secondary>listing</secondary></indexterm>
+
+      <para>To see what packages are currently installed, use the
+      <literal>--list-packages</literal> option:</para>
+      <indexterm><primary><literal>--list-packages</literal></primary>
+      </indexterm>
+
+<screen>
+  $ ghc --list-packages
+  gmp, rts, std, lang, concurrent, data, net, posix, text, util
+</screen>
+
+      <para>Note that your GHC installation might have a slightly
+      different set of packages installed.</para>
+
+      <para>The <literal>gmp</literal> and <literal>rts</literal>
+      packages are always present, and represent the multi-precision
+      integer and runtime system libraries respectively.  The
+      <literal>std</literal> package contains the Haskell prelude.
+      The rest of the packages are optional libraries.</para>
+
+    </sect2>
+
+    <sect2 id="using-packages">
+      <title>Using a package</title>
+      <indexterm><primary>packages</primary>
+	<secondary>using</secondary></indexterm>
+      
+      <para>To use a package, add the <literal>-package</literal> flag
+      to the command line:</para>
+
+      <variablelist>
+	<varlistentry>
+	  <term><option>-package &lt;lib&gt;</option></term>
+	  <indexterm><primary>-package &lt;lib&gt; option</primary></indexterm>
+	  <listitem>
+	    <para>This option brings into scope all the modules from
+	    package <literal>&lt;lib&gt;</literal> (they still have to
+	    be imported in your Haskell source, however).  It also
+	    causes the relevant libraries to be linked when linking is
+	    being done.</para>
+	  </listitem>
+	</varlistentry>
+      </variablelist>
+
+      <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>
+    </sect2>
+
+    <sect2 id="building-packages">
+      <title>Building a package from Haskell source</title>
+      <indexterm><primary>packages</primary>
+	<secondary>building</secondary></indexterm>
+
+      <para>It takes some special considerations to build a new
+      package:</para>
+
+      <itemizedlist>
+	<listitem>
+	  <para>A package may contain several Haskell modules. A
+          package may span many directories, or many packages may
+          exist in a single directory. Packages may not be mutually
+          recursive.</para>
+	</listitem>
+
+	<listitem>
+	  <para>A package has a name
+  	  (e.g. <filename>std</filename>)</para>
+	</listitem>
+
+	<listitem>
+	  <para>The Haskell code in a package may be built into one or
+	  more Unix libraries (e.g. <Filename>libHSfoo.a</Filename>),
+	  or a single DLL on Windows
+	  (e.g. <Filename>HSfoo.dll</Filename>).  The restriction to a
+	  single DLL on Windows is that the package system is used to
+	  tell the compiler when it should make an inter-DLL call
+	  rather than an intra-DLL call (inter-DLL calls require an
+	  extra indirection).</para>
+	</listitem>
+
+	<listitem>
+	  <para>GHC does not maintain detailed cross-package
+          dependency information.  It does remember which modules in
+          other packages the current module depends on, but not which
+          things within those imported things.</para>
+	</listitem>
+      </itemizedlist>
+
+      <para>To compile a module which is to be part of a new package,
+      use the <literal>-package-name</literal> option:</para>
+
+      <variablelist>
+	<varlistentry>
+	  <term><option>-package-name &lt;foo&gt;</option></term>
+	  <indexterm><primary><literal>-package-name</literal></primary>
+	    <secondary>option</secondary></indexterm>
+	  <listitem>
+	    <para>This option is added to the command line when
+	    compiling a module that is destined to be part of package
+	    <literal>foo</literal>.  If this flag is omitted then the
+	    default package <literal>Main</literal> is assumed.</para>
+	  </listitem>
+	</varlistentry>
+      </variablelist>
+
+      <para>Failure to use the <literal>-package-name</literal> option
+      when compiling a package will result in disaster on Windows, but
+      is relatively harmless on Unix at the moment (it will just cause
+      a few extra dependencies in some interface files).  However,
+      bear in mind that we might add support for Unix shared libraries
+      at some point in the future.</para>
+
+      <para>It is worth noting that on Windows, because each package
+      is built as a DLL, and a reference to a DLL costs an extra
+      indirection, intra-package references are cheaper than
+      inter-package references. Of course, this applies to the
+      <Filename>Main</Filename> package as well.</para>
+
+    </sect2>
+    <sect2 id="package-management">
+      <title>Package management</title>
+      <indexterm><primary>packages</primary>
+	<secondary>management</secondary></indexterm>
+      
+      <para>GHC uses a package configuration file, called
+      <literal>packages.conf</literal>, which can be found in your GHC
+      install directory.  This file isn't intended to be edited
+      directly, instead GHC provides options for adding & removing
+      packages:</para>
+
+      <variablelist>
+	<varlistentry>
+	  <term><option>--add-package</option></term>
+	  <indexterm><primary><literal>--add-package</literal></primary>
+	      <secondary>option</secondary></indexterm>
+	  <listitem>
+	    <para>Reads a package specification (see below) on stdin,
+	    and adds it to the database of installed packages.  The
+	    package specification must be a package that isn't already
+	    installed.</para>
+	  </listitem>
+	</varlistentry>
+
+	<varlistentry>
+	  <term><option>--delete-package &lt;foo&gt;</option></term>
+	  <indexterm><primary><literal>--delete-package</literal></primary>
+	      <secondary>option</secondary></indexterm>
+	  <listitem>
+	    <para>Removes the specified package from the installed
+	    configuration.</para>
+	  </listitem>
+	</varlistentry>
+      </variablelist>
+
+      <para>In both cases, the old package configuration file is saved
+      in <literal>packages.conf.old</literal> in your GHC install
+      directory, so in an emergency you can always copy this file into
+      <literal>package.conf</literal> to restore the old
+      settings.</para>
+
+      <para>A package specification looks like this:</para>
+
+<screen>
+  Package {
+     name            = "mypkg",
+     import_dirs     = ["/usr/local/lib/imports/mypkg"],
+     library_dirs    = ["/usr/local/lib"],
+     hs_libraries    = ["HSmypkg" ],
+     extra_libraries = ["HSmypkg_cbits"],
+     include_dirs    = [],
+     c_includes      = ["HsMyPkg.h"],
+     package_deps    = ["text", "data"],
+     extra_ghc_opts  = [],
+     extra_cc_opts   = [],
+     extra_ld_opts   = ["-lmy_clib"]
+  }
+</screen>
+
+      <para>Components of a package specification may be specified in
+      any order, and are:</para>
+
+      <variablelist>
+	<varlistentry>
+	  <term><literal>name</literal></term>
+	  <indexterm><primary><literal>name</literal></primary>
+	    <secondary>package specification</secondary></indexterm>
+	  <listitem>
+            <para>The package's name, for use with
+            the <literal>-package</literal> flag and as listed in the
+            <literal>--list-packages</literal> list. 
+            </para>
+	  </listitem>
+	</varlistentry>
+
+	<varlistentry>
+	  <term><literal>import_dirs</literal></term>
+	  <indexterm><primary><literal>import_dirs</literal></primary>
+	    <secondary>package specification</secondary></indexterm>
+	  <listitem>
+	    <para>A list of directories containing interface files
+	    (<literal>.hi</literal> files) for this package.</para>
+	  </listitem>
+	</varlistentry>
+
+	<varlistentry>
+	  <term><literal>library_dirs</literal></term>
+	  <indexterm><primary><literal>library_dirs</literal></primary>
+	    <secondary>package specification</secondary></indexterm>
+	  <listitem>
+	    <para>A list of directories containing libraries for this
+	    package.</para>
+	  </listitem>
+	</varlistentry>
+
+	<varlistentry>
+	  <term><literal>hs_libraries</literal></term>
+	  <indexterm><primary><literal>hs_libraries</literal></primary>
+	    <secondary>package specification</secondary></indexterm>
+	  <listitem>
+	    <para>A list of libraries containing Haskell code for this
+	    package, with the <literal>.a</literal> or
+	    <literal>.dll</literal> suffix omitted.  On Unix, the
+	    <literal>lib</literal> prefix is also omitted.</para>
+	  </listitem>
+	</varlistentry>
+
+	<varlistentry>
+	  <term><literal>extra_libraries</literal></term>
+	  <indexterm><primary><literal>extra_libraries</literal></primary>
+	    <secondary>package specification</secondary></indexterm>
+	  <listitem>
+	    <para>A list of extra libraries for this package.  The
+	    difference between <literal>hs_libraries</literal> and
+	    <literal>extra_libraries</literal> is that
+	    <literal>hs_libraries</literal> normally have several
+	    versions, to support profiling, parallel and other build
+	    options.  The various versions are given different
+	    suffixes to distinguish them, for example the profiling
+	    version of the standard prelude library is named
+	    <filename>libHSstd_p.a</filename>, with the
+	    <literal>_p</literal> indicating that this is a profiling
+	    version.  The suffix is added automatically by GHC for
+	    <literal>hs_libraries</literal> only, no suffix is added
+	    for libraries in
+	    <literal>extra_libraries</literal>.</para>
+
+	    <para>Also, <literal>extra_libraries</literal> are placed
+	    on the linker command line before the
+	    <literal>hs_libraries</literal> for the same package.  If
+	    your package has dependencies in the other direction, you
+	    might need to make two separate packages.</para>
+	  </listitem>
+	</varlistentry>
+
+	<varlistentry>
+	  <term><literal>include_dirs</literal></term>
+	  <indexterm><primary><literal>include_dirs</literal></primary>
+	    <secondary>package specification</secondary></indexterm>
+	  <listitem>
+	    <para>A list of directories containing C includes for this
+	    package (maybe the empty list).</para>
+	  </listitem>
+	</varlistentry>
+
+	<varlistentry>
+	  <term><literal>c_includes</literal></term>
+	  <indexterm><primary><literal>c_includes</literal></primary>
+	    <secondary>package specification</secondary></indexterm>
+	  <listitem>
+	    <para>A list of files to include for via-C compilations
+	    using this package.  Typically this include file will
+	    contain function prototypes for any C functions used in
+	    the package, in case they end up being called as a result
+	    of Haskell functions from the package being
+	    inlined.</para>
+	  </listitem>
+	</varlistentry>
+
+	<varlistentry>
+	  <term><literal>package_deps</literal></term>
+	  <indexterm><primary><literal>package_deps</literal></primary>
+	    <secondary>package specification</secondary></indexterm>
+	  <listitem>
+	    <para>A list of packages which this package depends
+	    on.</para>
+	  </listitem>
+	</varlistentry>
+
+	<varlistentry>
+	  <term><literal>extra_ghc_opts</literal></term>
+	  <indexterm><primary><literal>extra_ghc_opts</literal></primary>
+	    <secondary>package specification</secondary></indexterm>
+	  <listitem>
+	    <para>Extra arguments to be added to the GHC command line
+	    when this package is being used.</para>
+	  </listitem>
+	</varlistentry>
+
+	<varlistentry>
+	  <term><literal>extra_cc_opts</literal></term>
+	  <indexterm><primary><literal>extra_cc_opts</literal></primary>
+	    <secondary>package specification</secondary></indexterm>
+	  <listitem>
+	    <para>Extra arguments to be added to the gcc command line
+	    when this package is being used (only for via-C
+	    compilations).</para>
+	  </listitem>
+	</varlistentry>
+
+	<varlistentry>
+	  <term><literal>extra_ld_opts</literal></term>
+	  <indexterm><primary><literal>extra_ld_opts</literal></primary>
+	    <secondary>package specification</secondary></indexterm>
+	  <listitem>
+	    <para>Extra arguments to be added to the gcc command line
+	    (for linking) when this package is being used.</para>
+	  </listitem>
+	</varlistentry>
+      </variablelist>
+
+      <para>For examples of more package specifications, take a look
+      at the <literal>package.conf</literal> in your GHC
+      installation.</para>
+    </sect2>
+  </sect1>
+
+
 <Sect1 id="options-optimise">
 <Title>Optimisation (code improvement)
 </Title>
@@ -1348,9 +1911,9 @@ safely (see <XRef LinkEnd="recomp">).
 
 <VarListEntry>
 <Term>No <Option>-O*</Option>-type option specified:</Term>
+<IndexTerm><Primary>-O* not specified</Primary></IndexTerm>
 <ListItem>
 <Para>
-<IndexTerm><Primary>-O* not specified</Primary></IndexTerm>
 This is taken to mean: &ldquo;Please compile quickly; I'm not over-bothered
 about compiled-code quality.&rdquo;  So, for example: <Command>ghc -c Foo.hs</Command>
 </Para>
@@ -1358,22 +1921,22 @@ about compiled-code quality.&rdquo;  So, for example: <Command>ghc -c Foo.hs</Co
 </VarListEntry>
 <VarListEntry>
 <Term><Option>-O</Option> or <Option>-O1</Option>:</Term>
-<ListItem>
-<Para>
 <IndexTerm><Primary>-O option</Primary></IndexTerm>
 <IndexTerm><Primary>-O1 option</Primary></IndexTerm>
-<IndexTerm><Primary>optimise normally</Primary></IndexTerm>
-Means: &ldquo;Generate good-quality code without taking too long about it.&rdquo;
-Thus, for example: <Command>ghc -c -O Main.lhs</Command>
+<IndexTerm><Primary>optimise</Primary><secondary>normally</secondary></IndexTerm>
+<ListItem>
+<Para>
+Means: &ldquo;Generate good-quality code without taking too long about
+it.&rdquo; Thus, for example: <Command>ghc -c -O Main.lhs</Command>
 </Para>
 </ListItem>
 </VarListEntry>
 <VarListEntry>
 <Term><Option>-O2</Option>:</Term>
+<IndexTerm><Primary>-O2 option</Primary></IndexTerm>
+<IndexTerm><Primary>optimise</Primary><secondary>aggressively</secondary></IndexTerm>
 <ListItem>
 <Para>
-<IndexTerm><Primary>-O2 option</Primary></IndexTerm>
-<IndexTerm><Primary>optimise aggressively</Primary></IndexTerm>
 Means: &ldquo;Apply every non-dangerous optimisation, even if it means
 significantly longer compile times.&rdquo;
 </Para>
@@ -1392,12 +1955,9 @@ better code than <Option>-O</Option>.
 </VarListEntry>
 <VarListEntry>
 <Term><Option>-O2-for-C</Option>:</Term>
-<ListItem>
-<Para>
 <IndexTerm><Primary>-O2-for-C option</Primary></IndexTerm>
 <IndexTerm><Primary>gcc, invoking with -O2</Primary></IndexTerm>
-</Para>
-
+<ListItem>
 <Para>
 Says to run GCC with <Option>-O2</Option>, which may be worth a few percent in
 execution speed.  Don't forget <Option>-fvia-C</Option>, lest you use the native-code
@@ -1407,35 +1967,33 @@ generator and bypass GCC altogether!
 </VarListEntry>
 <VarListEntry>
 <Term><Option>-Onot</Option>:</Term>
-<ListItem>
-<Para>
 <IndexTerm><Primary>-Onot option</Primary></IndexTerm>
 <IndexTerm><Primary>optimising, reset</Primary></IndexTerm>
-</Para>
-
+<ListItem>
 <Para>
-This option will make GHC &ldquo;forget&rdquo; any <Option>-O</Option>ish options it has seen so
-far.  Sometimes useful; for example: <Command>make all EXTRA&lowbar;HC&lowbar;OPTS=-Onot</Command>.
+This option will make GHC &ldquo;forget&rdquo; any
+<Option>-O</Option>ish options it has seen so far.  Sometimes useful;
+for example: <Command>make all
+EXTRA&lowbar;HC&lowbar;OPTS=-Onot</Command>.
 </Para>
 </ListItem>
 </VarListEntry>
 <VarListEntry>
 <Term><Option>-Ofile &lt;file&gt;</Option>:</Term>
-<ListItem>
-<Para>
 <IndexTerm><Primary>-Ofile &lt;file&gt; option</Primary></IndexTerm>
 <IndexTerm><Primary>optimising, customised</Primary></IndexTerm>
-</Para>
-
+<ListItem>
 <Para>
-For those who need <Emphasis>absolute</Emphasis> control over <Emphasis>exactly</Emphasis>
-what options are used (e.g., compiler writers, sometimes :-), a list
-of options can be put in a file and then slurped in with <Option>-Ofile</Option>.
+For those who need <Emphasis>absolute</Emphasis> control over
+<Emphasis>exactly</Emphasis> what options are used (e.g., compiler
+writers, sometimes :-), a list of options can be put in a file and
+then slurped in with <Option>-Ofile</Option>.
 </Para>
 
 <Para>
-In that file, comments are of the <Literal>&num;</Literal>-to-end-of-line variety; blank
-lines and most whitespace is ignored.
+In that file, comments are of the
+<Literal>&num;</Literal>-to-end-of-line variety; blank lines and most
+whitespace is ignored.
 </Para>
 
 <Para>
@@ -1528,10 +2086,12 @@ Here are some &ldquo;dangerous&rdquo; optimisations you <Emphasis>might</Emphasi
 </Para>
 
 <Para>
-Compile via C, and don't use the native-code generator.  (There are
-many cases when GHC does this on its own.)  You might pick up a little
-bit of speed by compiling via C.  If you use <Function>&lowbar;ccall&lowbar;gc&lowbar;</Function>s or
-<Function>&lowbar;casm&lowbar;</Function>s, you probably <Emphasis>have</Emphasis> to use <Option>-fvia-C</Option>.
+Compile via C, and don't use the native-code generator.  (There are many
+cases when GHC does this on its own.) You might pick up a little bit of
+speed by compiling via C (e.g. for floating-point intensive code on Intel).
+If you use <Function>&lowbar;casm&lowbar;</Function>s (which are utterly
+deprecated), you probably <Emphasis>have</Emphasis> to use
+<Option>-fvia-C</Option>.
 </Para>
 
 <Para>
@@ -1589,27 +2149,23 @@ apply (see <Option>-funfolding-con-discount</Option>).
 </Para>
 </ListItem>
 </VarListEntry>
+
 <VarListEntry>
-<Term><Option>-funfolding-con-discount&lt;n&gt;</Option>:</Term>
+<Term><Option>-funfolding-update-in-place&lt;n&gt;</Option>:</Term>
 <ListItem>
 <Para>
-<IndexTerm><Primary>-funfolding-con-discount option</Primary></IndexTerm>
-<IndexTerm><Primary>inlining, controlling</Primary></IndexTerm>
-<IndexTerm><Primary>unfolding, controlling</Primary></IndexTerm>
-(Default: 2) If the compiler decides that it can eliminate some
-computation by performing an unfolding, then this is a discount factor
-that it applies to the funciton size before deciding whether to unfold
-it or not.
-</Para>
-
-<Para>
-OK, folks, these magic numbers `30', `8', and '2' are mildly
-arbitrary; they are of the &ldquo;seem to be OK&rdquo; variety.  The `8' is the
-more critical one; it's what determines how eager GHC is about
-expanding unfoldings.
+Switches on an experimental "optimisation".  Switching it on makes the compiler
+a little keener to inline a function that returns a constructor, if the context is
+that of a thunk.
+<ProgramListing>
+   x = plusInt a b
+</ProgramListing>
+If we inlined plusInt we might get an opportunity to use update-in-place for
+the thunk 'x'.
 </Para>
 </ListItem>
 </VarListEntry>
+
 <VarListEntry>
 <Term><Option>-funbox-strict-fields</Option>:</Term>
 <ListItem>
@@ -1707,6 +2263,18 @@ We have not played with <Option>-fsemi-tagging</Option> enough to recommend it.
 </Para>
 </ListItem>
 </VarListEntry>
+<VarListEntry>
+<Term><Option>-fexcess-precision</Option>:</Term>
+<ListItem>
+<Para>
+When this option is given, intermediate floating point values can have
+a <Emphasis>greater</Emphasis> precision/range than the final type.
+Generally this is a good thing, but some programs may rely on the
+exact precision/range of <Literal>Float</Literal>/<Literal>Double</Literal>
+values and should not use this option for their compilation.
+</Para>
+</ListItem>
+</VarListEntry>
 </VariableList>
 </Para>
 
@@ -2026,7 +2594,7 @@ THIS MAY CHANGE.  Meanwhile, options so sent are:
 </Para>
 
 <Para>
-If you are compiling with lots of <Literal>ccalls</Literal>, etc., you may need to
+If you are compiling with lots of foreign calls, you may need to
 tell the C&nbsp;compiler about some <Literal>&num;include</Literal> files.  There is no real
 pretty way to do this, but you can use this hack from the
 command-line:
@@ -2131,16 +2699,17 @@ libraries automatically; these are:
 </ListItem>
 </VarListEntry>
 <VarListEntry>
-<Term><Option>-syslib &lt;name&gt;</Option>:</Term>
+<Term><Option>-package &lt;name&gt;</Option>:</Term>
 <ListItem>
 <Para>
-<IndexTerm><Primary>-syslib &lt;name&gt; option</Primary></IndexTerm>
+<IndexTerm><Primary>-package &lt;name&gt; option</Primary></IndexTerm>
 </Para>
 
 <Para>
-If you are using a Haskell &ldquo;system library&rdquo; (e.g., the POSIX
-library), just use the <Option>-syslib posix</Option> option, and the correct code
-should be linked in.
+If you are using a Haskell &ldquo;package&rdquo; (e.g., the POSIX
+library), just use the <Option>-package posix</Option> option, and the
+correct code should be linked in.  See <xref linkend="packages"> for
+more details.
 </Para>
 </ListItem>
 </VarListEntry>
@@ -2212,7 +2781,7 @@ options the driver passes through to the linker.
 
 </Sect1>
 
-<Sect1>
+<Sect1 id="sec-using-concurrent">
 <Title>Using Concurrent Haskell</Title>
 
 <Para>
@@ -2223,22 +2792,25 @@ options the driver passes through to the linker.
 GHC (as of version 4.00) supports Concurrent Haskell by default,
 without requiring a special option or libraries compiled in a certain
 way.  To get access to the support libraries for Concurrent Haskell
-(i.e. <Literal>Concurrent</Literal> and friends), use the <Option>-syslib concurrent</Option> option.
+(i.e. <Literal>Concurrent</Literal> and friends), use the
+<Option>-package concurrent</Option> option.
 </Para>
 
 <Para>
 Three RTS options are provided for modifying the behaviour of the
-threaded runtime system.  See the descriptions of <Option>-C[&lt;us&gt;]</Option>, <Option>-q</Option>,
-and <Option>-t&lt;num&gt;</Option> in <XRef LinkEnd="parallel-rts-opts">.
+threaded runtime system.  See the descriptions of
+<Option>-C[&lt;us&gt;]</Option>, <Option>-q</Option>, and
+<Option>-t&lt;num&gt;</Option> in <XRef LinkEnd="parallel-rts-opts">.
 </Para>
 
 <Para>
-Concurrent Haskell is described in more detail in <XRef LinkEnd="concurrent-and-parallel">.
+Concurrent Haskell is described in more detail in <XRef
+LinkEnd="sec-Concurrent">.
 </Para>
 
 </Sect1>
 
-<Sect1>
+<Sect1 id="sec-using-parallel">
 <Title>Using Parallel Haskell</Title>
 
 <Para>
@@ -2252,16 +2824,19 @@ Concurrent Haskell is described in more detail in <XRef LinkEnd="concurrent-and-
 
 <Para>
 To compile a Haskell program for parallel execution under PVM, use the
-<Option>-parallel</Option> option,<IndexTerm><Primary>-parallel option</Primary></IndexTerm> both when compiling
-<Emphasis>and linking</Emphasis>.  You will probably want to <Literal>import Parallel</Literal>
-into your Haskell modules.
+<Option>-parallel</Option> option,<IndexTerm><Primary>-parallel
+option</Primary></IndexTerm> both when compiling <Emphasis>and
+linking</Emphasis>.  You will probably want to <Literal>import
+Parallel</Literal> into your Haskell modules.
 </Para>
 
 <Para>
-To run your parallel program, once PVM is going, just invoke it &ldquo;as
-normal&rdquo;.  The main extra RTS option is <Option>-N&lt;n&gt;</Option>, to say how many
-PVM &ldquo;processors&rdquo; your program to run on.  (For more details of
-all relevant RTS options, please see <XRef LinkEnd="parallel-rts-opts">.)
+To run your parallel program, once PVM is going, just invoke it
+&ldquo;as normal&rdquo;.  The main extra RTS option is
+<Option>-N&lt;n&gt;</Option>, to say how many PVM
+&ldquo;processors&rdquo; your program to run on.  (For more details of
+all relevant RTS options, please see <XRef
+LinkEnd="parallel-rts-opts">.)
 </Para>
 
 <Para>
@@ -2450,21 +3025,16 @@ the default is 2.
 <Term><Option>-C[&lt;us&gt;]</Option>:</Term>
 <ListItem>
 <Para>
-<IndexTerm><Primary>-C&lt;us&gt; RTS option</Primary></IndexTerm>
-Sets the context switch interval to <Literal>&lt;us&gt;</Literal> microseconds.  A context
-switch will occur at the next heap allocation after the timer expires.
-With <Option>-C0</Option> or <Option>-C</Option>, context switches will occur as often as
-possible (at every heap allocation).  By default, context switches
-occur every 10 milliseconds.  Note that many interval timers are only
-capable of 10 millisecond granularity, so the default setting may be
-the finest granularity possible, short of a context switch at every
-heap allocation.
-</Para>
-
-<Para>
-&lsqb;NOTE: this option currently has no effect (version 4.00).  Context
-switches happen when the current heap block is full, i.e. every 4k of
-allocation].
+<IndexTerm><Primary>-C&lt;us&gt; RTS option</Primary></IndexTerm> Sets
+the context switch interval to <Literal>&lt;s&gt;</Literal> seconds.
+A context switch will occur at the next heap block allocation after
+the timer expires (a heap block allocation occurs every 4k of
+allocation).  With <Option>-C0</Option> or <Option>-C</Option>,
+context switches will occur as often as possible (at every heap block
+allocation).  By default, context switches occur every 20ms
+milliseconds.  Note that GHC's internal timer ticks every 20ms, and
+the context switch timer is always a multiple of this timer, so 20ms
+is the maximum granularity available for timed context switches.
 </Para>
 </ListItem>
 </VarListEntry>
@@ -2545,3 +3115,10 @@ computation speed.
 &debug
 
 </Chapter>
+
+<!-- Emacs stuff:
+     ;;; Local Variables: ***
+     ;;; mode: sgml ***
+     ;;; sgml-parent-document: ("users_guide.sgml" "book" "chapter") ***
+     ;;; End: ***
+ -->