[project @ 2002-06-25 12:05:14 by simonmar]

Various hacking on the User's Guide to knock it into shape for the release.

Committers: please take a look at the 5.04 release notes and feel free
to tweak or embelish the description for your favourite new feature.

diff --git a/ghc/docs/users_guide/5-02-notes.sgml b/ghc/docs/users_guide/5-02-notes.sgml
index 8a64c07..d577841 100644 (file)
--- a/ghc/docs/users_guide/5-02-notes.sgml
+++ b/ghc/docs/users_guide/5-02-notes.sgml
@@ -1,143 +1,21 @@
-<sect1 id="release-5-02">
-  <title>Release notes for version 5.02</title>
+<sect1 id="release-5-04">
+  <title>Release notes for version 5.04</title>
 
   <sect2>
     <title>User-visible compiler changes</title>
-
     <itemizedlist>
-
-      <listitem>
-       <para>Majorly improved support for Windows platforms.  Binary
-       builds are now entirely freestanding.  There is no longer any
-       need to install Cygwin or Mingwin to use it.  It's a
-       one-click-install-and-off-you-go story now.</para>
-      </listitem>
-
-      <listitem>
-       <para>Several small changes to bring GHC into line with the
-       newest Haskell&nbsp;98 report.</para>
-      </listitem>
-
-      <listitem>
-       <para>RTS options can now be specified using the environment
-       variable <envar>GHCRTS</envar>.</para>
-      </listitem>
-      
-      <listitem>
-       <para>The maximum heap size, set with 
-        <literal>+RTS -M<replaceable>size</replaceable></literal>,
-        now defaults to unlimited.  We recommend however that you set
-        a maximum heap size appropriate for your machine using the
-        <envar>GHCRTS</envar> variable.</para>
-      </listitem>
-
-      <listitem>
-       <para>Thanks to the heroic efforts of Ken Shan
-       <email>ken@digitas.harvard.edu</email>, GHC now works again on
-       the Alpha architecture (just Tru64 at the moment), and many
-       64-bit bugs have been shaken out.  Interactive mode and the
-        native code generator do not currently work, sorry.</para>
-      </listitem>
-
-      <listitem>
-       <para>New option: <option>-fno-code</option> which causes GHC
-       to omit code generation and all future compilation stages (see
-       <xref linkend="options-codegen">).</para>
-      </listitem>
-
-      <listitem>
-        <para>New option <option>-package-conf
-        <replaceable>file</replaceable></option>.  This makes GHC read
-        additional package descriptions from
-        <replaceable>file</replaceable>.  See <xref
-        linkend="using-local-packages">.</para>
-      </listitem>
-
-      <listitem>
-       <para><option>+RTS
-          -i<replaceable>seconds</replaceable></option> flag reinstated for heap
-          profiling.  See <xref linkend="rts-options-heap-prof">.</para>
-      </listitem>
-
-      <listitem>
-       <para><option>-funbox-strict-fields</option> now works
-       correctly.  See <xref linkend="options-f">.</para>
-      </listitem>
-
       <listitem>
-       <para>
-        Many bug fixes related to implicit-parameter support.</para>
+       <para></para>
       </listitem>
-
-      <listitem>
-       <para>
-        Data declarations with no constructors are allowed.  This
-        facilitates types whose only value is bottom, and which have
-        no representation.</para>
-      </listitem>
-
-      <listitem>
-       <para>
-        You can disconnect numeric syntax from the Prelude syntax.
-        Doing this means you can define your own arithmetic.  The
-        relevant flag is <option>-fno-implicit-prelude</option>.  See
-        <xref linkend="options-language">.
-        </para>
-      </listitem>
-
     </itemizedlist>
   </sect2>
 
   <sect2>
     <title>User-visible interpreter (GHCi) changes</title>
-
     <itemizedlist>
       <listitem>
-         <para>GHCi now works on Windows.</para>
-      </listitem>
-
-      <listitem>
-       <para>Partial FFI support in GHCi.  At the moment, foreign
-        import (static and dynamic) are supported on x86 and sparc
-        platforms.</para>
+       <para></para>
       </listitem>
-
-      <listitem>
-       <para>New interpreter command <literal>:add</literal>, to add
-       modules to the current bunch.  See
-        <xref linkend="ghci-commands">.</para>
-      </listitem>
-
-      <listitem>
-       <para>New interpreter command <literal>:info</literal>, to provide
-       information on values, types and classes, a la Hugs.  See
-        <xref linkend="ghci-commands">.</para>
-      </listitem>
-
-      <listitem>
-       <para>Multiple target modules are supported.  You may specify
-       multiple modules for the <literal>:add</literal> and
-       <literal>:load</literal> commands.  From the command line, you
-       may specify multiple modules when starting GHCi and when
-       compiling in <option>&ndash;&ndash;make</option> mode.  See
-        <xref linkend="ghci-commands">.</para>
-      </listitem>
-
-      <listitem>
-       <para>New flags <option>-ignore-dot-ghci</option> and
-       <option>-read-dot-ghci</option>.  See
-        <xref linkend="ghci-dot-files">.</para>
-      </listitem>
-
-      <listitem>
-       <para>When starting GHCi from the command line, you may now
-       use the flags
-       <option>-L<replaceable>library-path</replaceable></option> and
-       <option>-l<replaceable>library-name</replaceable></option> to
-       specify libraries to be loaded into the interactive
-       session.  See <xref linkend="ghci-invokation">.</para>
-      </listitem>
-
     </itemizedlist>
   </sect2>
 
@@ -145,134 +23,16 @@
     <title>User-visible library changes</title>
     <itemizedlist>
       <listitem>
-       <para>The <literal>SocketPrim</literal> and
-       <literal>BSD</literal> modules in the <literal>net</literal>
-       package have been re-written to use the FFI, be more portable,
-       and be more thread-safe.  There are minor user-visible
-       changes: the functions <function>writeSocket</function>,
-       <function>readSocket</function> and
-       <function>readSocketAll</function> have been removed (use
-       <function>socketToHandle</function> and
-       <literal>Handle</literal> operations instead).</para>
-      </listitem>
-
-      <listitem>
-       <para>New function: <function>Exception.throwDynTo</function>.
-       See <xref linkend="sec-Dynamic-Exceptions">.</para>
-      </listitem>
-
-      <listitem>
-       <para><literal>BlockedOnDeadMVar</literal> and
-        <literal>ThreadKilled</literal> exceptions no longer generate
-        any output by default for forked threads.</para>
-      </listitem>
-
-      <listitem>
-       <para><literal>Weak.addForeignFinalizer</literal> is
-       deprecated; use the <literal>ForeignPtr</literal> library
-       instead.</para>
-      </listitem>
-
-      <listitem>
-       <para>The I/O library has been completely rewritten, using the
-       new FFI libraries and <command>hsc2hs</command>.  The main
-       improvement is to the way streams are handled: simultaneous
-       read and write with multiple threads using a socket or FIFO is
-       now possible, whereas before it was necessary to use two
-       separate handles.</para>
-      </listitem>
-
-      <listitem>
-       <para>As a result of the I/O rewrite, the extensions
-       <literal>IOExts.hConnectTo</literal> and
-       <literal>IOExts.withHandleFor</literal> have been removed.
-       Also, <literal>hGetBuf</literal> and
-       <literal>hPutBuf</literal> have been removed, and
-       <literal>hGetBufFull</literal> and
-       <literal>hPutBufFull</literal> have been renamed to
-       <literal>hGetBuf</literal> and <literal>hPutBuf</literal>
-       respectively (similary for the <literal>BA</literal>
-       versions of these functions).</para>
-      </listitem>
-
-      <listitem>
-       <para><literal>System.exitWith</literal> now throws
-       <literal>ExitException</literal> rather than causing the
-       program to exit immediately.  <literal>ExitException</literal>
-       is by default caught by the top level exception handler in the
-       main thread, where it causes the program to exit.  Hence, calling
-       <literal>System.exitWith</literal> in GHCi no longer causes
-       GHCi itself to exit.</para>
-      </listitem>
-
-      <listitem>
-       <para>New function: <literal>MVar.addMVarFinalizer</literal>
-       (see <xref linkend="sec-MVars">).</para>
-      </listitem>
-
-      <listitem>
-       <para>New module <literal>SystemExts</literal> for useful
-       system-ish functionality (see <xref
-       linkend="sec-SystemExts">).</para>
-      </listitem>
-
-      <listitem>
-       <para><literal>SocketPrim</literal>: added instances of
-       <literal>Eq</literal> and <literal>Show</literal> for the
-       <literal>Socket</literal> type.</para>
-      </listitem>
-
-      <listitem>
-       <para>The implementation of
-       <literal>MarsalAlloc.allocaBytes</literal> now uses GHC's
-       internal allocator and is much faster than before.  As a
-       result, the <literal>UnsafeCString</literal> type and
-       functions are no longer necessary and have been removed from
-       <literal>CString</literal>.</para>
+       <para></para>
       </listitem>
     </itemizedlist>
   </sect2>
 
   <sect2>
     <title>New experimental features</title>
-
     <itemizedlist>
-      <!-- don't forget: 31-bit support -->
-
-      <listitem>
-       <para>Partial support for hierarchical module names.</para>
-      </listitem>
-
       <listitem>
-         <para>Mucho hacking on the .NET code generator, including
-         some FFI extensions for .NET interop.  It's still
-         severely b0rk3d, so won't do anything useful.  Yet.</para>
-      </listitem>
-
-      <listitem>
-         <para>Emission of external Core format.  The goal is for
-         other tools to be able to grab the Core resulting from GHC's
-         front end manglings and optimisations.  Core format is
-         formally defined by the document <ulink url="http://www.haskell.org/ghc/docs/papers/core.ps.gz"
-         <citetitle>An External Representation for the GHC Core Language</citetitle></ulink>.
-         We also have sample
-         tools for reading, writing and typechecking external Core,
-         available in the source distribution directory <literal>/fptools/ghc/utils/ext-core</literal>.
-         Ultimately we plan that Core files can also be read by
-         GHC.  The relevant flag is <option>-fext-core</option>.
-         </para>
-      </listitem>
-
-      <listitem>
-       <para>A compacting garbage collector has been added.  It isn't
-       on by default, because it is somewhat slower than the existing
-       copying collector, but can be automatically enabled when
-       memory gets tight by setting the maximum heap size (see <xref
-       linkend="rts-options-gc">).  Compaction works together with
-       the existing generational scheme: it is only used on the
-       oldest generation.  Despite the "experimental"
-       classification, we've jumped up and down quite significantly
-       on this code, and it seems stable.</para>
+       <para></para>
       </listitem>
     </itemizedlist>
   </sect2>
@@ -281,24 +41,8 @@
     <title>Internal changes</title>
     <itemizedlist>
       <listitem>
-       <para>The implementation of the <literal>Array</literal>,
-       <literal>IArray</literal> and <literal>MArray</literal>
-       libraries have been rewritten so that bulk operations like
-       <literal>listArray</literal> and <literal>elems</literal> do
-       less range checking and hence go faster.</para>
-      </listitem>
-
-      <listitem>
-       <para>The <literal>CPUTime</literal> library has been replaced
-       by one written using the FFI.  No externally visible
-       changes.</para>
-      </listitem>
-
-      <listitem>
-       <para>The compiler has a new strictness-and-absence analyser,
-        which is alleged to help it generate better code.</para>
+       <para></para>
       </listitem>
-
     </itemizedlist>
   </sect2>
 

diff --git a/ghc/docs/users_guide/ffi-chap.sgml b/ghc/docs/users_guide/ffi-chap.sgml
index 9009a50..4534b07 100644 (file)
--- a/ghc/docs/users_guide/ffi-chap.sgml
+++ b/ghc/docs/users_guide/ffi-chap.sgml
@@ -30,9 +30,9 @@
     </listitem>
   </itemizedlist>
 
-  <para>The FFI libraries are documented in <xref
-  linkend="sec-Foreign">.</para>
-
+  <para>The FFI libraries are documented in the accompanying library
+  documentation; see for example the <literal>Foreign</literal>
+  module.</para>
 
   <sect1 id="sec-ffi-ghcexts">
     <title>GHC extensions to the FFI Addendum</title>

diff --git a/ghc/docs/users_guide/flags.sgml b/ghc/docs/users_guide/flags.sgml
index 8514c48..aaf87bf 100644 (file)
--- a/ghc/docs/users_guide/flags.sgml
+++ b/ghc/docs/users_guide/flags.sgml
@@ -299,6 +299,14 @@
              <entry>dynamic</entry>
              <entry>-</entry>
            </row>
+           <row>
+             <entry><option>--show-iface</option> <replaceable>file</replaceable></entry>
+             <entry>Read the interface in
+             <replaceable>file</replaceable> and dump it as text to
+             <literal>stdout</literal>.</entry>
+             <entry>static</entry>
+             <entry>-</entry>
+           </row>
          </tbody>
        </tgroup>
       </informaltable>
@@ -1092,17 +1100,17 @@
              <entry>-</entry>
            </row>
            <row>
-             <entry><option>-framework</option> <replaceable>name</replaceable></endtry>
+             <entry><option>-framework</option> <replaceable>name</replaceable></entry>
              <entry>On Darwin/MacOS X only, link in the framework <replaceable>name</replaceable>.
-               This option corresponds to the <option>-framework</option> option for Apple's Linker.
+               This option corresponds to the <option>-framework</option> option for Apple's Linker.</entry>
              <entry>static</entry>
              <entry>-</entry>
            </row>
            <row>
-             <entry><option>-framework-path</option> <replaceable>name</replaceable></endtry>
+             <entry><option>-framework-path</option> <replaceable>name</replaceable></entry>
              <entry>On Darwin/MacOS X only, add <replaceable>dir</replaceable> to the list of
                directories searched for frameworks.
-               This option corresponds to the <option>-F</option> option for Apple's Linker.
+               This option corresponds to the <option>-F</option> option for Apple's Linker.</entry>
              <entry>static</entry>
              <entry>-</entry>
            </row>

diff --git a/ghc/docs/users_guide/ghci.sgml b/ghc/docs/users_guide/ghci.sgml
index 14c1126..0919b20 100644 (file)
--- a/ghc/docs/users_guide/ghci.sgml
+++ b/ghc/docs/users_guide/ghci.sgml
@@ -9,11 +9,11 @@
     </footnote>
   is GHC's interactive environment, in which Haskell expressions can
   be interactively evaluated and programs can be interpreted.  If
-  you're famililar with Hugs<indexterm><primary>Hugs</primary>
+  you're famililar with <ulink url="http://www.haskell.org/hugs/">Hugs</ulink><indexterm><primary>Hugs</primary>
   </indexterm>, then you'll be right at home with GHCi.  However, GHCi
   also has support for interactively loading compiled code, as well as
   supporting all<footnote><para>except <literal>foreign export</literal>, at the moment</para>
-  </footnote>the language extensions that GHC provides.</para>
+  </footnote> the language extensions that GHC provides.</para>
   <indexterm><primary>FFI</primary><secondary>GHCi support</secondary></indexterm>
   <indexterm><primary>Foreign Function Interface</primary><secondary>GHCi support</secondary></indexterm>
 
@@ -27,11 +27,12 @@
 $ ghci
    ___         ___ _
   / _ \ /\  /\/ __(_)
- / /_\// /_/ / /  | |      GHC Interactive, version 5.00, For Haskell 98.
+ / /_\// /_/ / /  | |      GHC Interactive, version 5.04, for Haskell 98.
 / /_\\/ __  / /___| |      http://www.haskell.org/ghc/
 \____/\/ /_/\____/|_|      Type :? for help.
 
-Loading package std ... linking ... done.
+Loading package base ... linking ... done.
+Loading package haskell98 ... linking ... done.
 Prelude> 
 </screen>
 
@@ -42,23 +43,37 @@ Prelude>
 
 <screen>
  Commands available from the prompt:
-   &lt;stmt&gt;              evaluate/run &lt;stmt&gt;
-   :cd &lt;dir&gt;           change directory to &lt;dir&gt;
-   :def &lt;cmd&gt; &lt;expr&gt;   define a macro :&lt;cmd&gt;
-   :help, :?           display this list of commands
-   :load &lt;filename&gt;    load a module (and it dependents)
-   :module &lt;mod&gt;       set the context for expression evaluation to &lt;mod&gt;
-   :reload             reload the current module set
-   :set &lt;option&gt; ...   set options
-   :type &lt;expr&gt;        show the type of &lt;expr&gt;
-   :unset &lt;option&gt; ... unset options
-   :quit               exit GHCi
-   :!&lt;command&gt;         run the shell command &lt;command&gt;
+
+   %lt;stmt&gt;                     evaluate/run %lt;stmt&gt;
+   :add %lt;filename&gt; ...        add module(s) to the current target set
+   :browse [*]%lt;module&gt;        display the names defined by %lt;module&gt;
+   :cd %lt;dir&gt;                  change directory to %lt;dir&gt;
+   :def %lt;cmd&gt; %lt;expr&gt;          define a command :%lt;cmd&gt;
+   :help, :?                  display this list of commands
+   :info [%lt;name&gt; ...]         display information about the given names
+   :load %lt;filename&gt; ...       load module(s) and their dependents
+   :module [+/-] [*]%lt;mod&gt; ... set the context for expression evaluation
+   :reload                    reload the current module set
+
+   :set %lt;option&gt; ...          set options
+   :set args %lt;arg&gt; ...        set the arguments returned by System.getArgs
+   :set prog %lt;progname&gt;       set the value returned by System.getProgName
+
+   :show modules              show the currently loaded modules
+   :show bindings             show the current bindings made at the prompt
+
+   :type %lt;expr&gt;               show the type of %lt;expr&gt;
+   :undef %lt;cmd&gt;               undefine user-defined command :%lt;cmd&gt;
+   :unset %lt;option&gt; ...        unset options
+   :quit                      exit GHCi
+   :!%lt;command&gt;                run the shell command %lt;command&gt;
+
  Options for `:set' and `:unset':
+
     +r                 revert top-level expressions after each evaluation
     +s                 print timing/memory stats after each evaluation
     +t                 print type after evaluation
-    -&lt;flag&gt;            most GHC command line flags can also be set here
+    -%lt;flags&gt;           most GHC command line flags can also be set here
                          (eg. -v2, -fglasgow-exts, etc.)
 </screen>
 
@@ -203,8 +218,8 @@ Ok, modules loaded: Main.
     normally converted to byte-code and run using the interpreter.
     However, interpreted code can also run alongside compiled code in
     GHCi; indeed, normally when GHCi starts, it loads up a compiled
-    copy of package <literal>std</literal>, which contains the Prelude
-    and standard libraries.</para>
+    copy of the <literal>base</literal> package, which contains the
+    <literal>Prelude</literal>.</para>
 
     <para>Why should we want to run compiled code?  Well, compiled
     code is roughly 10x faster than interpreted code, but takes about
@@ -526,8 +541,9 @@ Prelude>
 </screen>
       <para>Any exceptions raised during the evaluation or execution
       of the statement are caught and printed by the GHCi command line
-      interface (see <xref linkend="sec-Exception"> for more
-      information on GHC's Exception support).</para>
+      interface (for more information on exceptions, see the module
+      <literal>Control.Exception</literal> in the libraries
+      documentation).</para>
 
       <para>Every new binding shadows any existing bindings of the
       same name, including entities that are in scope in the current
@@ -640,28 +656,25 @@ $ ghci Main.hs
       <indexterm><primary>packages</primary><secondary>with GHCi</secondary></indexterm>
 
       <para>GHCi can make use of all the packages that come with GHC,
-      For example, to start up GHCi with the <literal>text</literal>
+      For example, to start up GHCi with the <literal>network</literal>
       package loaded:</para>
 
 <screen>
-$ ghci -package text
+$ ghci -package network
    ___         ___ _
   / _ \ /\  /\/ __(_)
- / /_\// /_/ / /  | |      GHC Interactive, version 5.00, For Haskell 98.
+ / /_\// /_/ / /  | |      GHC Interactive, version 5.04, for Haskell 98.
 / /_\\/ __  / /___| |      http://www.haskell.org/ghc/
 \____/\/ /_/\____/|_|      Type :? for help.
 
-Loading package std ... linking ... done.
-Loading package lang ... linking ... done.
-Loading package text ... linking ... done.
+Loading package base ... linking ... done.
+Loading package haskell98 ... linking ... done.
+Loading package network ... linking ... done.
 Prelude> 
 </screen>      
 
-      <para>Note that GHCi also loaded the <literal>lang</literal>
-      package even though we didn't ask for it: that's because the
-      <literal>text</literal> package makes use of one or more of the
-      modules in <literal>lang</literal>, and therefore has a
-      dependency on it.</para>
+      <para>Note that GHCi will also automatically load any packages
+      on which the requested package depends.</para>
 
       <para>The following command works to load new packages into a
       running GHCi:</para>

diff --git a/ghc/docs/users_guide/glasgow_exts.sgml b/ghc/docs/users_guide/glasgow_exts.sgml
index 49d378b..012f922 100644 (file)
--- a/ghc/docs/users_guide/glasgow_exts.sgml
+++ b/ghc/docs/users_guide/glasgow_exts.sgml
@@ -19,8 +19,9 @@ performance because of the implementation costs of Haskell's
 Before you get too carried away working at the lowest level (e.g.,
 sloshing <literal>MutableByteArray&num;</literal>s around your
 program), you may wish to check if there are libraries that provide a
-&ldquo;Haskellised veneer&rdquo; over the features you want.  See
-<xref linkend="book-hslibs">.
+&ldquo;Haskellised veneer&rdquo; over the features you want.  The
+separate libraries documentation describes all the libraries that come
+with GHC.
 </para>
 
 <!-- LANGUAGE OPTIONS -->
@@ -163,14 +164,16 @@ program), you may wish to check if there are libraries that provide a
 
 <para>With the <option>-fglasgow-exts</option> flag, GHC lets you declare
 a data type with no constructors.  For example:</para>
+
 <programlisting>
   data S      -- S :: *
   data T a    -- T :: * -> *
 </programlisting>
+
 <para>Syntactically, the declaration lacks the "= constrs" part.  The 
-type can be parameterised, but only over ordinary types, of kind *; since
-Haskell does not have kind signatures, you cannot parameterise over higher-kinded
-types.</para>
+type can be parameterised over types of any kind, but if the kind is
+not <literal>*</literal> then an explicit kind annotation must be used
+(see <xref linkend="sec-kinding">).</para>
 
 <para>Such data types have only one value, namely bottom.
 Nevertheless, they can be useful when defining "phantom types".</para>
@@ -894,21 +897,19 @@ is <literal>(?x::a) => (a,a)</literal>, and not
 class constraints.
 </para>
 <para>
-An implicit parameter is bound using an expression of the form 
-<emphasis>expr</emphasis> <literal>with</literal> <emphasis>binds</emphasis>, 
-where <literal>with</literal> is a new keyword. This form binds the implicit
-parameters arising in the body, not the free variables as a <literal>let</literal> or
-<literal>where</literal> would do. For example, we define the <literal>min</literal> function by binding
-<literal>cmp</literal>.
+An implicit parameter is bound using the standard
+<literal>let</literal> binding form, where the bindings must be a
+collection of simple bindings to implicit-style variables (no
+function-style bindings, and no type signatures); these bindings are
+neither polymorphic or recursive. This form binds the implicit
+parameters arising in the body, not the free variables as a
+<literal>let</literal> or <literal>where</literal> would do. For
+example, we define the <literal>min</literal> function by binding
+<literal>cmp</literal>.</para>
 <programlisting>
   min :: [a] -> a
-  min  = least with ?cmp = (<=)
+  min  = let ?cmp = (<=) in least
 </programlisting>
-Syntactically, the <emphasis>binds</emphasis> part of a <literal>with</literal> construct must be a
-collection of simple bindings to variables (no function-style
-bindings, and no type signatures); these bindings are neither
-polymorphic or recursive.
-</para>
 <para>
 Note the following additional constraints:
 <itemizedlist>
@@ -1379,7 +1380,7 @@ for rank-2 types.
 </sect3>
 </sect2>
 
-<sect2>
+<sect2 id="type-synonyms">
 <title>Liberalised type synonyms 
 </title>
 
@@ -2346,21 +2347,24 @@ assert pred val ==> assertError "Main.hs|15" pred val
 
 <para>
 The rewrite is only performed by the compiler when it spots
-applications of <function>Exception.assert</function>, so you can still define and
-use your own versions of <function>assert</function>, should you so wish. If not,
-import <literal>Exception</literal> to make use <function>assert</function> in your code.
+applications of <function>Control.Exception.assert</function>, so you
+can still define and use your own versions of
+<function>assert</function>, should you so wish. If not, import
+<literal>Control.Exception</literal> to make use
+<function>assert</function> in your code.
 </para>
 
 <para>
 To have the compiler ignore uses of assert, use the compiler option
-<option>-fignore-asserts</option>. <indexterm><primary>-fignore-asserts option</primary></indexterm> That is,
-expressions of the form <literal>assert pred e</literal> will be rewritten to <literal>e</literal>.
+<option>-fignore-asserts</option>. <indexterm><primary>-fignore-asserts
+option</primary></indexterm> That is, expressions of the form
+<literal>assert pred e</literal> will be rewritten to
+<literal>e</literal>.
 </para>
 
 <para>
 Assertion failures can be caught, see the documentation for the
-<literal>Exception</literal> library (<xref linkend="sec-Exception">)
-for the details.
+<literal>Control.Exception</literal> library for the details.
 </para>
 
 </sect1>
@@ -2369,6 +2373,53 @@ for the details.
 <sect1 id="syntax-extns">
 <title>Syntactic extensions</title>
 
+<!-- ====================== HIERARCHICAL MODULES =======================  -->
+
+    <sect2 id="hierarchical-modules">
+      <title>Hierarchical Modules</title>
+
+      <para>GHC supports a small extension to the syntax of module
+      names: a module name is allowed to contain a dot
+      <literal>&lsquo;.&rsquo;</literal>.  This is also known as the
+      &ldquo;hierarchical module namespace&rdquo; extension, because
+      it extends the normally flat Haskell module namespace into a
+      more flexible hierarchy of modules.</para>
+
+      <para>A module name in the extended syntax consists of a
+      sequence of components, each separated by a dot.  When searching
+      for an interface file (or a source file, in the case of GHCi or
+      when using <option>--make</option>) for an imported module, GHC
+      interprets the dot as a path separator.  So for example, if a
+      module <literal>A.B.C</literal> is imported, then for each
+      directory <literal>D</literal> on the search path (see the
+      <option>-i</option> option, <xref
+      linkend="options-finding-imports">), GHC will look in the
+      directory <literal>D/A/B</literal><footnote><para>On Windows,
+      this would be <literal>D\A\B</literal>.</para></footnote> for an
+      interface file called <filename>C.hi</filename> or a source file
+      <filename>C.hs</filename> or <filename>C.lhs</filename>.</para>
+
+      <para>Note that as far as the compiler is concerned, module
+      names are always fully qualified; the hierarchy only has a
+      special meaning when searching for interface files and source
+      files in the filesystem.  In particular, this means that the
+      full module name must be given after the
+      <literal>module</literal> keyword at the beginning of the
+      module; for example, the module <literal>A.B.C</literal> must
+      begin</para>
+
+<programlisting>module A.B.C</programlisting>
+
+      <para>GHC comes with a large collection of libraries arranged
+      hierarchically; see the accompanying library documentation.
+      There is an ongoing project to create and maintain a stable set
+      of <quote>core</quote> libraries used by several Haskell
+      compilers, and the libraries that GHC comes with represent the
+      current status of that project.  For more details, see <ulink
+      url="http://www.haskell.org/~simonmar/libraries/libraries.html">.</ulink></para>
+
+    </sect2>
+
 <!-- ====================== PATTERN GUARDS =======================  -->
 
 <sect2 id="pattern-guards">
@@ -2554,14 +2605,18 @@ qualifier list has just one element, a boolean expression.
 <title>Rebindable syntax</title>
 
 
-           <para> Your 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 <emphasis>whatever
-            is in scope</emphasis>, not the Prelude versions:</para>
+      <para>GHC allows most kinds of built-in syntax to be rebound by
+      the user, to facilitate replacing the <literal>Prelude</literal>
+      with a home-grown version, for example.</para>
+
+            <para>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
+            <emphasis>whatever is in scope</emphasis>, not the Prelude
+            versions:</para>
 
            <itemizedlist>
              <listitem>
@@ -2587,11 +2642,12 @@ qualifier list has just one element, a boolean expression.
              </listitem>
 
              <listitem>
-             <para>"Do" notation is translated using whatever functions
-             <literal>(>>=)</literal>, <literal>(>>)</literal>, <literal>fail</literal>, 
-             and <literal>return</literal>, are in scope (not the Prelude versions).
-             List comprehensions, and parallel array comprehensions, are unaffected.
-            </para></listitem>
+         <para>"Do" notation is translated using whatever
+             functions <literal>(>>=)</literal>,
+             <literal>(>>)</literal>, <literal>fail</literal>, and
+             <literal>return</literal>, are in scope (not the Prelude
+             versions).  List comprehensions, and parallel array
+             comprehensions, are unaffected.  </para></listitem>
            </itemizedlist>
 
             <para>Be warned: this is an experimental facility, with fewer checks than

diff --git a/ghc/docs/users_guide/gone_wrong.sgml b/ghc/docs/users_guide/gone_wrong.sgml
index 93585da..2f0321c 100644 (file)
--- a/ghc/docs/users_guide/gone_wrong.sgml
+++ b/ghc/docs/users_guide/gone_wrong.sgml
@@ -174,10 +174,6 @@
          <para>Of course, if you have foreign calls in your program
           then all bets are off, because you can trash the heap, the
           stack, or whatever.</para>
-
-         <para>If you are interested in hard-core debugging of a
-          crashing GHC-compiled program, please see <xref
-          linkend="hard-core-debug">.</para>
        </listitem>
       </varlistentry>
 

diff --git a/ghc/docs/users_guide/installing.sgml b/ghc/docs/users_guide/installing.sgml
index 15d5aa8..42f48c1 100644 (file)
--- a/ghc/docs/users_guide/installing.sgml
+++ b/ghc/docs/users_guide/installing.sgml
@@ -44,10 +44,11 @@ but it's useful if you are changing the implementation.   </para>  </listitem>
 
       <variablelist>
        <varlistentry>
-         <term>RedHat Linux/x86</term>
+         <term>RedHat or SuSE Linux/x86</term>
          <listitem>
-           <para>RPM source & binary packages for RedHat Linux (x86
-           only) are available for most major releases.</para>
+           <para>RPM source & binary packages for RedHat and SuSE
+           Linux (x86 only) are available for most major
+           releases.</para>
          </listitem>
        </varlistentry>
 
@@ -95,8 +96,9 @@ Binary distributions come in &ldquo;bundles,&rdquo; one bundle per file called
 </Para>
 
 <Para>
-Then you should find a single directory, <Literal>fptools</Literal>, with the following
-structure:
+Then you should find a single directory,
+<Literal>ghc-<replaceable>version</replaceable></Literal>, with the
+following structure:
 </Para>
 
 <Para>

diff --git a/ghc/docs/users_guide/intro.sgml b/ghc/docs/users_guide/intro.sgml
index d1f838e..6e877b4 100644 (file)
--- a/ghc/docs/users_guide/intro.sgml
+++ b/ghc/docs/users_guide/intro.sgml
@@ -41,8 +41,8 @@
   details.</para>
 
   <para>GHC comes with a large collection of libraries, with
-  everything from parser combinators to networking.  These are all
-  described in <xref linkend="book-hslibs">.</para>
+  everything from parser combinators to networking.  The libraries are
+  described in separate documentation.</para>
 
   <Sect1 id="mailing-lists-GHC">
     <Title>Meta-information: Web sites, mailing lists, etc.</Title>
@@ -383,7 +383,7 @@
   </sect1>
 
 
-&relnotes
+&relnotes;
 
 </Chapter>
 

diff --git a/ghc/docs/users_guide/packages.sgml b/ghc/docs/users_guide/packages.sgml
index b778a50..6faac0a 100644 (file)
--- a/ghc/docs/users_guide/packages.sgml
+++ b/ghc/docs/users_guide/packages.sgml
@@ -13,8 +13,8 @@
     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 to or removed
+    <para>GHC comes with several packages (see the accompanying
+    library documentation), and packages can be added to or removed
     from an existing GHC installation, using the supplied
     <literal>ghc-pkg</literal><indexterm><primary><literal>ghc-pkg</literal></primary>
     </indexterm> tool, described in <xref
@@ -534,7 +534,7 @@
            <secondary>package specification</secondary></indexterm>
          <listitem>
            <para>On Darwin/MacOS X, a list of directories containing frameworks for this
-           package. This corresponds to the <option>-framework-path</options> option.
+           package. This corresponds to the <option>-framework-path</option> option.
            It is ignored on all other platforms.</para>
          </listitem>
        </varlistentry>

diff --git a/ghc/docs/users_guide/parallel.sgml b/ghc/docs/users_guide/parallel.sgml
index a7739bf..9a6502a 100644 (file)
--- a/ghc/docs/users_guide/parallel.sgml
+++ b/ghc/docs/users_guide/parallel.sgml
@@ -62,7 +62,8 @@ Web Page.
 
 <Para>
 Some details about Parallel Haskell follow.  For more information
-about concurrent Haskell, see <xref linkend="sec-Concurrent">.
+about concurrent Haskell, see the module
+<literal>Control.Concurrent</literal> in the library documentation.
 </Para>
 
 <Sect2>

diff --git a/ghc/docs/users_guide/phases.sgml b/ghc/docs/users_guide/phases.sgml
index b3f4883..81f5297 100644 (file)
--- a/ghc/docs/users_guide/phases.sgml
+++ b/ghc/docs/users_guide/phases.sgml
@@ -482,7 +482,7 @@ strmod = "\
            This option corresponds to the <option>-framework</option> option for Apple's Linker.
            Please note that frameworks and packages are two different things - frameworks don't
            contain any haskell code. Rather, they are Apple's way of packaging shared libraries.
-           To link to Apple's &ldquo;Carbon&qdquo; API, for example, you'd use
+           To link to Apple's &ldquo;Carbon&rdquo; API, for example, you'd use
            <option>-framework Carbon</option>.
            </para>
          </listitem>

diff --git a/ghc/docs/users_guide/primitives.sgml b/ghc/docs/users_guide/primitives.sgml
index aa68d27..f84794a 100644 (file)
--- a/ghc/docs/users_guide/primitives.sgml
+++ b/ghc/docs/users_guide/primitives.sgml
@@ -1172,7 +1172,8 @@ C.
 </para>
 
 <para>
-Please see <xref LinkEnd="sec-stable-pointers"> for more details.
+Please see the module <literal>Foreign.StablePtr</literal> in the
+library documentation for more details.
 </para>
 </listitem>
 </varlistentry>
@@ -1188,7 +1189,8 @@ memory when you're done with it.&rdquo;
 </para>
 
 <para>
-Please see <xref LinkEnd="sec-ForeignObj"> for more details.
+Please see module <literal>Foreign.ForeignPtr</literal> in the library
+documentatation for more details.
 </para>
 </listitem>
 </varlistentry>

diff --git a/ghc/docs/users_guide/separate_compilation.sgml b/ghc/docs/users_guide/separate_compilation.sgml
index 45e6c9c..5e0ce6c 100644 (file)
--- a/ghc/docs/users_guide/separate_compilation.sgml
+++ b/ghc/docs/users_guide/separate_compilation.sgml
@@ -18,11 +18,14 @@
       which contains a module <literal>A</literal>, say, it generates
       an object <filename>A.o</filename>, <emphasis>and</emphasis> a
       companion <emphasis>interface file</emphasis>
-      <filename>A.hi</filename>.  The interface file is not intended
-      for human consumption, as you'll see if you take a look at one.
-      It's merely there to help the compiler compile other modules in
-      the same program.</para>
-
+      <filename>A.hi</filename>.  The interface file is merely there
+      to help the compiler compile other modules in the same program.
+      Interfaces are in a binary format, so don't try to look at one;
+      however you <emphasis>can</emphasis> see the contents of an
+      interface file by using GHC with the
+      <option>--show-iface</option> option (see <xref
+      linkend="hi-options">, below).</para>
+      
       <para>NOTE: In general, the name of a file containing module
       <literal>M</literal> should be named <filename>M.hs</filename>
       or <literal>M.lhs</literal>.  The only exception to this rule is
@@ -163,8 +166,20 @@
             the labour.</para>
          </listitem>
        </varlistentry>
+
+       <varlistentry>
+         <term><option>--show-iface</option>
+         <replaceable>file</replaceable></term>
+         <indexterm><primary><option>--show-iface</option></primary>
+         </indexterm>
+         <listitem>
+           <para>Where <replaceable>file</replaceable> is the name of
+           an interface file, dumps the contents of that interface in
+           a human-readable (ish) format.</para>
+         </listitem>
+       </varlistentry>
       </variablelist>
-       
+
     </sect2>
 
     <sect2 id="recomp">
@@ -551,60 +566,47 @@ import {-# SOURCE #-} A
       would look like the following:</para>
 
 <ProgramListing>
-__interface A 1 0 where
-__export A TA{MkTA} ;
-1 newtype TA = MkTA PrelBase.Int ;
+module A where
+newtype TA = MkTA GHC.Base.Int
 </ProgramListing>
 
-      <para>The syntax is essentially the same as a normal
-      <filename>.hi</filename> file (unfortunately), so you can
-      usually tailor an existing <filename>.hi</filename> file to make
-      a <filename>.hi-boot</filename> file.</para>
+      <para>The syntax is similar to a normal Haskell source file, but
+      with some important differences:</para>
+
+      <itemizedlist>
+       <listitem>
+         <para>Non-local entities must be qualified with their
+         <emphasis>original</emphasis> defining module.  Qualifying
+         by a module which just re-exports the entity won't do.  In
+         particular, most <literal>Prelude</literal> entities aren't
+         actually defined in the <literal>Prelude</literal> (see for
+         example <literal>GHC.Base.Int</literal> in the above
+         example).</para>
+       </listitem>
+       <listitem>
+         <para>Only <literal>data</literal>, <literal>type</literal>,
+         <literal>newtype</literal>, <literal>class</literal>, and
+         type signature declarations may be included.</para>
+       </listitem>
+      </itemizedlist>
 
       <para>Notice that we only put the declaration for the newtype
       <literal>TA</literal> in the <literal>hi-boot</literal> file,
       not the signature for <Function>f</Function>, since
       <Function>f</Function> isn't used by <literal>B</literal>.</para>
 
-      <para>The number &ldquo;1&rdquo; after
-      &ldquo;&lowbar;&lowbar;interface A&rdquo; gives the version
-      number of module A; it is incremented whenever anything in A's
-      interface file changes.  In a normal interface file, the
-      &ldquo;0&rdquo; is the version number of the compiler which
-      generated the interface file; it is used to ensure that we don't
-      mix-and-match interface files between compiler versions.
-      Leaving it as zero in an <literal>hi-boot</literal> file turns
-      off this check.</para>
-
-      <para>The number &ldquo;1&rdquo; at the beginning of a
-      declaration is the <emphasis>version number</emphasis> of that
-      declaration: for the purposes of <filename>.hi-boot</filename>
-      files these can all be set to 1.  All names must be fully
-      qualified with the <emphasis>original</emphasis> module that an
-      object comes from: for example, the reference to
-      <literal>Int</literal> in the interface for <literal>A</literal>
-      comes from <literal>PrelBase</literal>, which is a module
-      internal to GHC's prelude.  It's a pain, but that's the way it
-      is.</para>
-
       <para>If you want an <literal>hi-boot</literal> file to export a
       data type, but you don't want to give its constructors (because
       the constructors aren't used by the SOURCE-importing module),
       you can write simply:</para>
 
 <ProgramListing>
-__interface A 1 0 where
-__export A TA;
-1 data TA
+module A where
+data TA
 </ProgramListing>
 
       <para>(You must write all the type parameters, but leave out the
       '=' and everything that follows it.)</para>
-
-      <para><emphasis>Note:</emphasis> This is all a temporary
-      solution, a version of the compiler that handles mutually
-      recursive modules properly without the manual construction of
-      interface files, is (allegedly) in the works.</para>
     </sect2>
 
 

diff --git a/ghc/docs/users_guide/ug-book.sgml b/ghc/docs/users_guide/ug-book.sgml
index 10dc11e..cf5dd38 100644 (file)
--- a/ghc/docs/users_guide/ug-book.sgml
+++ b/ghc/docs/users_guide/ug-book.sgml
@@ -1,5 +1,5 @@
 <BookInfo>
-<Title>The Glasgow Haskell Compiler User's Guide, Version 5.02</Title>
+<Title>The Glasgow Haskell Compiler User's Guide, Version 5.04</Title>
 <Author><OtherName>The GHC Team</OtherName></Author>
 <Address>
 <Email>glasgow-haskell-&lcub;bugs,users&rcub;-request@haskell.org</Email>

diff --git a/ghc/docs/users_guide/ug-ent.sgml b/ghc/docs/users_guide/ug-ent.sgml
index 56b36f8..ba5c617 100644 (file)
--- a/ghc/docs/users_guide/ug-ent.sgml
+++ b/ghc/docs/users_guide/ug-ent.sgml
@@ -3,7 +3,7 @@
 <!ENTITY flags          SYSTEM "flags.sgml">
 <!ENTITY license        SYSTEM "license.sgml">
 <!ENTITY intro          SYSTEM "intro.sgml" >
-<!ENTITY relnotes       SYSTEM "5-02-notes.sgml" >
+<!ENTITY relnotes       SYSTEM "5-04-notes.sgml" >
 <!ENTITY installing     SYSTEM "installing.sgml" >
 <!ENTITY using          SYSTEM "using.sgml" >
 <!ENTITY runtime        SYSTEM "runtime_control.sgml" >

diff --git a/ghc/docs/users_guide/using.sgml b/ghc/docs/users_guide/using.sgml
index 2eaa640..41c467d 100644 (file)
--- a/ghc/docs/users_guide/using.sgml
+++ b/ghc/docs/users_guide/using.sgml
@@ -363,7 +363,7 @@ module X where
          <para>Print the path to GHC's library directory.  This is
          the top of the directory tree containing GHC's libraries,
          interfaces, and include files (usually something like
-         <literal>/usr/local/lib/ghc-5.02</literal> on Unix).  This
+         <literal>/usr/local/lib/ghc-5.04</literal> on Unix).  This
          is the value of
          <literal>$libdir</literal><indexterm><primary><literal>libdir</literal></primary>
          </indexterm>in the package configuration file (see <xref
@@ -1408,36 +1408,31 @@ data S = S !Int !Int
       </variablelist>
 
     </sect2>
-
+    
   </sect1>
-
-&phases;  
-
-<Sect1 id="sec-using-concurrent">
+  
+  &phases;  
+  
+  <sect1 id="sec-using-concurrent">
 <title>Using Concurrent Haskell</title>
 
-<para>
-<indexterm><primary>Concurrent Haskell&mdash;use</primary></indexterm>
-</para>
+            <indexterm><primary>Concurrent Haskell&mdash;use</primary></indexterm>
 
 <para>
-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>-package concurrent</option> option.
-</para>
+GHC 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, just import
+<literal>Control.Concurrent</literal> (details are in the accompanying
+library documentation).</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">.
+RTS options are provided for modifying the behaviour of the threaded
+runtime system.  See <XRef LinkEnd="parallel-rts-opts">.
 </para>
 
 <para>
-Concurrent Haskell is described in more detail in <XRef
-LinkEnd="sec-Concurrent">.
+Concurrent Haskell is described in more detail in the documentation
+for the <literal>Control.Concurrent</literal> module.
 </para>
 
 </Sect1>

diff --git a/ghc/docs/users_guide/utils.sgml b/ghc/docs/users_guide/utils.sgml
index d58752e..5260a1f 100644 (file)
--- a/ghc/docs/users_guide/utils.sgml
+++ b/ghc/docs/users_guide/utils.sgml
@@ -449,7 +449,9 @@ tags:
             The intention is that <literal>#peek</literal> and
             <literal>#poke</literal> can be used for implementing the
             operations of class <literal>Storable</literal> for a
-            given C struct (see <xref linkend="sec-Storable">).</para>
+            given C struct (see the
+            <literal>Foreign.Storable</literal> module in the library
+            documentation).</para>
          </listitem>
        </varlistentry>
 

diff --git a/ghc/docs/users_guide/vs_haskell.sgml b/ghc/docs/users_guide/vs_haskell.sgml
index f9e8481..9eb771e 100644 (file)
--- a/ghc/docs/users_guide/vs_haskell.sgml
+++ b/ghc/docs/users_guide/vs_haskell.sgml
@@ -239,9 +239,9 @@ main = print (array (1,1) [(1,2), (1,3)])</programlisting>
          integral types (<literal>Int8</literal>,
          <literal>Int16</literal>, <literal>Int32</literal>,
          <literal>Int64</literal> and the unsigned
-         <literal>Word</literal> variants), see <xref
-         linkend="sec-Int"> and <xref linkend="sec-Word">.</para>
-
+         <literal>Word</literal> variants), see the modules
+         <literal>Data.Int</literal> and <literal>Data.Word</literal>
+         in the library documentation.</para>
        </listitem>
       </varlistentry>