From 29920fbc163944859166a6fde6136e6db50982ef Mon Sep 17 00:00:00 2001
From: simonmar <unknown>
Date: Tue, 20 Feb 2001 18:05:23 +0000
Subject: [PATCH] [project @ 2001-02-20 18:05:23 by simonmar] More doc
 hacking.

Call for Release Notes (CFRN): the 5-00-notes.sgml file is currently a
skeleton only; PLEASE add or expand entries for things you've done.
---
 ghc/docs/users_guide/4-00-notes.sgml |  168 -----------
 ghc/docs/users_guide/4-01-notes.sgml |   31 --
 ghc/docs/users_guide/4-02-notes.sgml |   59 ----
 ghc/docs/users_guide/4-03-notes.sgml |   26 --
 ghc/docs/users_guide/4-04-notes.sgml |  244 ----------------
 ghc/docs/users_guide/4-06-notes.sgml |  250 ----------------
 ghc/docs/users_guide/4-08-notes.sgml |  200 -------------
 ghc/docs/users_guide/5-00-notes.sgml |   54 ++++
 ghc/docs/users_guide/flags.sgml      |    6 +-
 ghc/docs/users_guide/ghci.sgml       |    2 +-
 ghc/docs/users_guide/installing.sgml |  129 +++++----
 ghc/docs/users_guide/intro.sgml      |  518 +++++++++++++---------------------
 ghc/docs/users_guide/ug-book.sgml    |    2 +-
 ghc/docs/users_guide/ug-ent.sgml     |    2 +-
 ghc/docs/users_guide/using.sgml      |    2 +-
 15 files changed, 331 insertions(+), 1362 deletions(-)
 delete mode 100644 ghc/docs/users_guide/4-00-notes.sgml
 delete mode 100644 ghc/docs/users_guide/4-01-notes.sgml
 delete mode 100644 ghc/docs/users_guide/4-02-notes.sgml
 delete mode 100644 ghc/docs/users_guide/4-03-notes.sgml
 delete mode 100644 ghc/docs/users_guide/4-04-notes.sgml
 delete mode 100644 ghc/docs/users_guide/4-06-notes.sgml
 delete mode 100644 ghc/docs/users_guide/4-08-notes.sgml
 create mode 100644 ghc/docs/users_guide/5-00-notes.sgml

diff --git a/ghc/docs/users_guide/4-00-notes.sgml b/ghc/docs/users_guide/4-00-notes.sgml
deleted file mode 100644
index 4fddc0d..0000000
--- a/ghc/docs/users_guide/4-00-notes.sgml
+++ /dev/null
@@ -1,168 +0,0 @@
-<sect1>Release notes for version~4.00---10/98
-<label id="release-4-00">
-<p>
-
-<sect2>Language matters
-<p>
-
-<itemize>
-
-<item> Universal and existential quantification: see Section <ref
-name="Explicit universal quantification"
-id="universal-quantification"> and Section <ref name="Existentially
-quantified data constructors" id="existential-quantification">
-respectively.
-
-Universal quantification was in in GHC 2.10 and later, but the
-syntax has changed: it's now <tt>forall a. ...</tt> instead of <tt>All a =&gt; ...</tt>.
-
-<item> Multi-paramter type classes.  We have relaxed some of the rules
-  since GHC 3.00.  In particular
-
-<descrip>
-  <tag><tt>-fallow-overlapping-instances</tt></tag>
-         allows overlapping instances
-  <tag><tt>-fallow-undecidable-instances</tt></tag>
-         allows you to write instance contexts that constrain non-type-variables
-</descrip>
-
-Full details in Section <ref name="Multi-parameter type classes"
-id="multi-param-type-classes">.
-</itemize>
-
-<sect2>New Libraries
-<p>
-
-Documentation in <url name="GHC/Hugs Extension Libraries"
-url="libs.html">.
-
-<descrip>
-
-<tag><tt>Dynamic</tt></tag>
-
-Dynamic types.  
-
-<tag><tt>Exceptions</tt></tag>
-
-The library <tt>Exception</tt> in <tt>-syslib exts</tt> provide an interface for
-exception handling.  Calls to <tt>error</tt>, pattern matching failures and a
-bunch of other exception can be caught.
-
-</descrip>
-
-<sect2>Compiler internals
-<p>
-
-The intermediate language used by GHC has had a radical overhaul.
-The new Core language (coreSyn/CoreSyn.lhs) is much smaller and
-more uniform.  The main transformation engine (the "simplifier")
-has been totally rewritten.  The compiler is several thousand lines
-shorter as a result.  It's also very much easier to understand 
-and modify.  (It's true.  Honest!)
-
-
-<sect2>Run time system
-<p>
-
-There is a completely new runtime system, aimed at integration with
-Hugs.  Tons of cruft removed.  Some changes to code generation; things
-typically run a bit faster as a result.
-
-An overview of the new RTS is available: <url name="The New GHC/Hugs
-Runtime System" url="http://www.dcs.gla.ac.uk/~simonm/rts.ps">.
-
-<sect2>Storage Manager/Garbage Collector
-<p>
-
-The new storage manager features a dynamically resizing heap, so you
-won't need those pesky <tt>-H</tt> options anymore.  In fact, the <tt>-H</tt> option
-is now ignored for compatibility with older versions.
-
-Stacks are now also expandable, and the <tt>-K</tt> option now specifies a
-<em/maximum/ heap size.  The default is (a perhaps conservative) <tt>1M</tt>.
-
-The garbage collector now collects CAFs, so there's no more space
-leaks associated with these.  If you think you have a CAF-related
-space leak, we'd like to hear about it.
-
-The storage manager current only has a two-space garbage collector,
-which will be slower than 3.02's generational collector when the
-amount of live data is large.  A new generational collector is high on
-our priority list.
-
-For the other new tweakables, see Section <ref name="RTS options to
-control the garbage-collector" id="rts-options-gc">.
-
-<sect2>Profiling
-<p>
-
-There is a new profiler based on <em/Cost Centre Stacks/.  This is an
-extension of the previous cost centre scheme, whereby the profilier
-stores information about the call-graph of the program and attributes
-costs to nodes of this graph.
-
-For a quick demo, try compiling a program with <tt>-prof -auto-all</tt>, then
-run it with <tt>+RTS -p</tt> and see what comes out (in the <tt>&lt;prog&gt;.prof</tt>
-file).
-
-The feature is still experimental, and the call graph may not be
-exactly what you were expecting.  Also, we only have time/allocation
-profiling at the moment; heap profiling will follow shortly.
-
-<sect2>Miscellaneous
-<p>
-
-<itemize>
-
-<item> Concurrent Haskell is now the default.  No need to
-compile/download special libraries.  The context switch interval isn't
-tweakable any more; threads just yield after allocating a fixed amount
-of heap (currently 4k).  If you want a quicker context switch, that
-won't be possible: this decision was made for efficiency reasons (it
-reduces the penalty for runnning threaded code to almost zero).  We
-might allow the context switch interval to be increased in the future;
-but also context switches are pretty fast (faster than before).
-
-<item> <tt>forkIO</tt> now returns a <tt>ThreadId</tt>, and there's a new operation
-<tt>killThread</tt> which will terminate an existing thread.  See Section
-<ref name="The Concurrent interface" id="concurrent-interface"> for
-more details.
-
-<item> You need <tt>-syslib concurrent</tt> to get the <tt>Concurrent</tt> library.
-
-<item> The rewritten IO library from 3.03 has been ported to 4.00.
-
-<item> New constructs: <tt>foriegn import</tt> and <tt>foreign export</tt> for
-H/Direct.
-
-<item> Supported architectures: all the development has been done on
-x86(mainly FreeBSD/Linux) so this is the most stable environment.
-Sparc (Solaris) and x86/Win32 (cygwin32) have also been mildly tested, and
-an Alpha port is in the works.  Everything else will need a little
-porting effort; we don't have machines here, so any help would be
-greatly appreciated.
-
-<item> Code is faster and smaller, but programs might run slower due
-to the garbage collector (see "Storage Manager" above).  Increasing
-the minimum allocation area with the <tt>-A</tt> RTS option can claw back
-some of this speed.
-
-<item> We now use GMP 2.02, and attempt to use an already-installed
-copy if available.  If you have GMP on your system but the configure
-script doesn't detect it, we'd like to know.
-
-<item> <tt>seq</tt> works better than in 3.xx - you can now <tt>seq</tt> functions
-without crashing the program.
-
-<item> The <tt>Eval</tt> class has been removed (i.e. every type is assumed
-to be in class <tt>Eval</tt>).  This change has been made in anticipation of
-Haskell 98.
-
-<item> The native code generator has had very little testing (it's not used
-on x86 yet), so Sparcs may have some trouble with it.  Try -fvia-C if
-strange errors occur.
-
-<item> The compiler is slightly faster, but sometimes needs more heap.
-If you have an example where this is the case, please let us know.
-
-</itemize>
diff --git a/ghc/docs/users_guide/4-01-notes.sgml b/ghc/docs/users_guide/4-01-notes.sgml
deleted file mode 100644
index d0aaa7c..0000000
--- a/ghc/docs/users_guide/4-01-notes.sgml
+++ /dev/null
@@ -1,31 +0,0 @@
-<sect1>Release notes for version~4.01---11/98
-<label id="release-4-01">
-<p>
-
-<itemize>
-
-<item> <tt/relocate_TSO/ bug fixed.
-
-<item> Weak pointers implemented, and new <tt/Weak/ library provided
-(see <htmlurl name="GHC/Hugs Extension Libraries" url="libs.html">).
-The <tt/ForeignObj/ interface no longer supports finalisation - use
-the <tt/Weak/ interface for that.
-
-<item> Foreign funcion interface is now complete and working.
-
-<item> New interface file format for compatibility with Hugs.  No
-user-visible changes except that you'll have to update any .hi-boot
-files you have lying around - check out some GHC-generated .hi files
-for examples.
-
-<item> Space leak in the compiler is partially fixed -
-<tt/-dcore-lint/ is still recommended for decent space behaviour.
-
-<item> New API to the RTS (not interesting unless you're an RTS client
-writer).
-
-<item> <tt/thawIOArray/ added to <tt/IOExts/.
-
-<item> Many many small bugs fixed.
-
-</itemize>
diff --git a/ghc/docs/users_guide/4-02-notes.sgml b/ghc/docs/users_guide/4-02-notes.sgml
deleted file mode 100644
index 0a4eebf..0000000
--- a/ghc/docs/users_guide/4-02-notes.sgml
+++ /dev/null
@@ -1,59 +0,0 @@
-<sect1>Release notes for version~4.02---12/98
-<label id="release-4-02">
-<p>
-
-<itemize>
-
-<item> Full Haskell 98 language support.
-
-<item> Scoped type variables implemented (see Section <ref
-name="Scoped Type Variables" id="scoped-type-variables">).
-
-<item> Several bugs in _ccall_GC and foreign export fixed.
-
-<item> Warnings for unused variables should work now (they didn't before).
-
-<item> Simplifier improvements:
-   <itemize>
-        <item> Much better treatment of strict arguments.
-        <item> Function arguments of unlifted type are treated as strict.
-        <item> Better treatment of bottoming Ids.
-        <item> No need for worker/wrapper split for fns that are merely strict.
-        <item> Fewer iterations needed, I hope.
-   </itemize>
-
-<item> Strictness of primitive operations is now explicit and used by
-the simplifier.
-
-<item> Less gratuitous renaming in interface files and abs C.
-
-<item> <tt/OccName/ is a separate module, and is an abstract data type.
- 
-<item> A new generational garbage collector: the number of generations
-is variable, using the -G RTS option (see <ref id="rts-options-gc"
-name="RTS options to control the garbage-collector">).  This collector
-is faster and more space-efficient than the two-space collector in 4.01.
-
-<item> Error messages and warnings are now printed out in the order they
-occur in the source code.
-
-<item> <tt/isEmptyMVar/ operation added to the <tt/Concurrent/ library.
-
-<item> Two new functions exported from <tt/ST/ (and <tt/LazyST/):
-<tt/unsafeIOToST/ and <tt/stToIO/.
-
-<item> The <tt/+RTS -H&lt;size&gt;/ option is reinstated.  Now it
-means "use about this much memory" (see Section <ref
-id="rts-options-gc" name="RTS options to control the garbage
-collector">).  This option was added mainly so that 4.02 GC times look
-good compared to 3.02 :-).
-
-<item> <tt/finalise/ and <tt/mkWeakNoFinaliser/ operations added to
-<tt/Weak/ library.
-
-<item> Ticky-ticky profiling works again (cost-centre profiling is
-still broken).
-
-<item> Better <tt/egcs-1.1.1/ support.
-
-</itemize>
diff --git a/ghc/docs/users_guide/4-03-notes.sgml b/ghc/docs/users_guide/4-03-notes.sgml
deleted file mode 100644
index a99df0c..0000000
--- a/ghc/docs/users_guide/4-03-notes.sgml
+++ /dev/null
@@ -1,26 +0,0 @@
-<sect1>Release notes for version~4.03---3/99
-<label id="release-4-03">
-<p>
-
-<itemize>
-<item> <tt/Weak/ library changes:
-        <itemize>
-        <item> Finalise is now spelt finalize in all function names.
-        <item> <tt/finalize/ now runs the finalizer immediately, and
-               waits for it to complete before returning.
-        <item> <tt/mkWeak/ now takes a <tt/Maybe (IO ())/ for the finalizer,
-               and <tt/mkWeakNoFinalizer/ is removed.
-        </itemize>
-
-<item> Changed representation of <tt/Integer/ type to speed up
-computations on small integers.  The performance of <tt/Integer/ is now
-only slightly slower than <tt/Int/ for values between <tt/minBound :: Int/
-and <tt/maxBound :: Int/.
-
-<item> On Win32 platforms, added support for using (and producing) dynamic
-link libraries (DLLs) containing ghc-compiled code.
-
-<item> Added <tt>-funbox-strict-fields</tt> for unboxing/unpacking strict
-constructor fields.
-
-</itemize>
diff --git a/ghc/docs/users_guide/4-04-notes.sgml b/ghc/docs/users_guide/4-04-notes.sgml
deleted file mode 100644
index a17baa1..0000000
--- a/ghc/docs/users_guide/4-04-notes.sgml
+++ /dev/null
@@ -1,244 +0,0 @@
-<Sect1 id="release-4-04">
-<Title>Release notes for version&nbsp;4.04&mdash;7/99
-</Title>
-
-<Para>
-
-<ItemizedList>
-<ListItem>
-
-<Para>
-<Literal>Weak</Literal> library changes:
-
-<ItemizedList>
-<ListItem>
-<Para>
-&ldquo;Finalise&rdquo; is now spelt &ldquo;finalize&rdquo; in all function names.
-</Para>
-</ListItem>
-
-<ListItem>
-<Para>
-<Function>finalize</Function> now runs the finalizer immediately, and
-waits for it to complete before returning.
-</Para>
-</ListItem>
-
-<ListItem>
-<Para>
-<Function>mkWeak</Function> now takes a <Literal>Maybe (IO ())</Literal> for the finalizer,
-and <Function>mkWeakNoFinalizer</Function> is removed.
-</Para>
-</ListItem>
-
-<ListItem>
-<Para>
-A weak pointer whose key is itself a weak pointer will now do the right
-thing.
-</Para>
-</ListItem>
-
-</ItemizedList>
-</Para>
-</ListItem>
-
-<ListItem>
-<Para>
-Changed representation of <Literal>Integer</Literal> type to speed up
-computations on small integers.  The performance of <Literal>Integer</Literal> is now
-only slightly slower than <Literal>Int</Literal> for values between <Constant>minBound::Int</Constant>
-and <Constant>maxBound::Int</Constant>.
-</Para>
-</ListItem>
-
-<ListItem>
-<Para>
-On Win32 platforms, added support for using (and producing) dynamic
-link libraries (DLLs) containing ghc-compiled code.
-</Para>
-</ListItem>
-
-<ListItem>
-<Para>
-Added <Option>-funbox-strict-fields</Option> for unboxing/unpacking strict
-constructor fields.
-</Para>
-</ListItem>
-
-<ListItem>
-<Para>
-GHC now has a license!  See <XRef LinkEnd="License">.
-</Para>
-</ListItem>
-
-<ListItem>
-<Para>
-Added CPR analysis, which reduces allocation by unboxing function results
-(thanks to Kevin Glynn <Email>keving@cs.mu.oz.au</Email>).
-</Para>
-</ListItem>
-
-<ListItem>
-<Para>
-UsageSP analysis added, but not yet functional.
-</Para>
-</ListItem>
-
-<ListItem>
-<Para>
-Added a simple common sub-expression analysis pass.
-</Para>
-</ListItem>
-
-<ListItem>
-<Para>
-Implemented update-in-place for certain very restricted cases.
-</Para>
-</ListItem>
-
-<ListItem>
-<Para>
-Replaced GHC's old and worn yacc/lex parser with a new one based on Happy. 
-Fixed several Haskell 98 non-conformance issues in the process.
-</Para>
-</ListItem>
-
-<ListItem>
-<Para>
-Added <Function>Concurrent.yield :: IO ()</Function>.
-</Para>
-</ListItem>
-
-<ListItem>
-<Para>
-Added <Literal>RULES</Literal> pragma&mdash;transformation rules for Haskell source.
-This is used for list fusion: now intermediate lists between map,
-foldr, list comprehensions are removed automatically.
-</Para>
-</ListItem>
-
-<ListItem>
-<Para>
-Unregisterised/unmangled builds now work.
-</Para>
-</ListItem>
-
-<ListItem>
-<Para>
-Much performance tuning: GHC 4.04 produces faster code than all previous
-compilers.
-</Para>
-</ListItem>
-
-<ListItem>
-<Para>
-GHC now defines <Literal>&lowbar;&lowbar;HASKELL98&lowbar;&lowbar;</Literal> when compiling files with <Option>-cpp</Option>.
-</Para>
-</ListItem>
-
-<ListItem>
-<Para>
-<Literal>hppa1.1-hp-hpux</Literal> port reinstated.
-</Para>
-</ListItem>
-
-<ListItem>
-<Para>
-New operations for unsafely thawing byte arrays:
-<Function>unsafeThaw&lcub;Byte,ST,IO&rcub;Array</Function>.
-</Para>
-</ListItem>
-
-<ListItem>
-<Para>
-<Command>mkdependHS</Command> now lives in GHC's lib directory, not the
-binary directory.  It isn't intended to be run standalone, only via
-<Command>ghc -M</Command>.
-</Para>
-</ListItem>
-
-<ListItem>
-<Para>
-Asynchronous exceptions are now supported (see the libary documentation for Concurrent Haskell).  New operations:
-<!-- Want to add external ref here -->
-
-<ItemizedList>
-
-<ListItem>
-<Para>
-<Function>Exception.killThread</Function> now raises an exception 
-(<Function>AsyncException.KilledThread</Function>) in the killed thread.
-</Para>
-</ListItem>
-
-<ListItem>
-<Para>
-<Function>Exception.raiseInThread</Function> allows a thread to raise an
-exception in another thread.
-</Para>
-</ListItem>
-
-<ListItem>
-<Para>
-<Function>Concurrent.myThreadId</Function> returns the <Literal>ThreadId</Literal> of the calling thread.
-</Para>
-</ListItem>
-
-<ListItem>
-<Para>
-Stack overflow results in <Constant>AsyncException.StackOverflow</Constant>
-being raised in the offending thread.
-</Para>
-</ListItem>
-
-</ItemizedList>
-
-</Para>
-</ListItem>
-
-<ListItem>
-<Para>
-Assertion failures now raise an <Constant>AssertionFailed</Constant> exception.
-</Para>
-</ListItem>
-
-<ListItem>
-<Para>
-Added simple high-level interface to the Regex library, see the libraries manual.
-</Para>
-</ListItem>
-
-<ListItem>
-<Para>
-<Function>forkIO</Function> now handles any uncaught exceptions cleanly.
-</Para>
-</ListItem>
-
-<ListItem>
-<Para>
-<Function>integer2Int&num;</Function> isn't sign preserving any longer, but modulo <Constant>(maxBound::Int + 1) * 2</Constant>.
-</Para>
-</ListItem>
-
-<ListItem>
-<Para>
-<Option>-ddump-rdr</Option> is now called <Option>-ddump-parsed</Option>.
-</Para>
-</ListItem>
-
-<ListItem>
-<Para>
-Signal handling with the <Literal>Posix</Literal> library now works.
-</Para>
-</ListItem>
-
-<ListItem>
-<Para>
-Many, many bugs fixed.
-</Para>
-</ListItem>
-
-</ItemizedList>
-</Para>
-
-</Sect1>
diff --git a/ghc/docs/users_guide/4-06-notes.sgml b/ghc/docs/users_guide/4-06-notes.sgml
deleted file mode 100644
index e328353..0000000
--- a/ghc/docs/users_guide/4-06-notes.sgml
+++ /dev/null
@@ -1,250 +0,0 @@
-<Sect1 id="release-4-06">
-<Title>Release notes for version&nbsp;4.06&mdash;1/00
-</Title>
-
-<Para>
-
-<ItemizedList>
-<ListItem>
-
-<Para>
-User visible changes
-
-<ItemizedList>
-
-<ListItem>
-<Para>
-Major library reorganisation.  The libraries are now split into 8
-categories:
-
-<VariableList>
-
-<VarListEntry>
-<Term><Literal>concurrent</Literal></Term>
-<ListItem>
-<Para>
-Same as the old <literal>concurrent</literal> library
-</Para>
-</ListItem>
-</VarListEntry>
-
-<VarListEntry>
-<Term><Literal>data</Literal></Term>
-<ListItem>
-<Para>
-Datatypes.  Contains old <literal>FiniteMap</literal>
-and <literal>Set</literal> modules, and Chris Okasaki's Edison
-library.
-</Para>
-</ListItem>
-</VarListEntry>
-
-<VarListEntry>
-<Term><Literal>lang</Literal></Term>
-<ListItem>
-<Para>
-contains most of the contents of
-the old <literal>exts</literal> library
-</Para>
-</ListItem>
-</VarListEntry>
-
-<VarListEntry>
-<Term><Literal>net</Literal></Term>
-<ListItem>
-<Para>
-networking-related libraries (Socket, SocketPrim, and
-new URI library).
-</Para>
-</ListItem>
-</VarListEntry>
-
-<VarListEntry>
-<Term><Literal>num</Literal></Term>
-<ListItem>
-<Para>
-numerical-related libraries (currently empty).
-</Para>
-</ListItem>
-</VarListEntry>
-
-<VarListEntry>
-<Term><Literal>posix</Literal></Term>
-<ListItem>
-<Para>
-the old POSIX library
-</Para>
-</ListItem>
-</VarListEntry>
-
-<VarListEntry>
-<Term><Literal>text</Literal></Term>
-<ListItem>
-<Para>
-text-processing related libraries (including Andy Gill's
-HTML library)
-</Para>
-</ListItem>
-</VarListEntry>
-
-<VarListEntry>
-<Term><Literal>util</Literal></Term>
-<ListItem>
-<Para>
-various miscellaneous libraries, including John Hughes'
-and Koen Claessen's QuickCheck library.
-</Para>
-</ListItem>
-</VarListEntry>
-
-</VariableList>
-
-See the accompanying libraries documentation for more details.
-</Para>
-</ListItem>
-
-<ListItem>
-<Para>
-Cleanup of concurrent I/O system.  We now use non-blocking I/O on
-all Handles, so that multiple threads can do I/O simultaneously.
-We <Emphasis>don't</Emphasis> however do non-blocking I/O on <Constant>stdout</Constant>/<Constant>stderr</Constant>,
-due to reports that some shells don't correctly restore
-blocking mode on these file descriptors after running a program.
-</Para>
-</ListItem>
-
-<ListItem id="exc-changes-406">
-<Para>
-Exception changes
-
-<ItemizedList>
-<ListItem>
-<Para>
-<Function>raiseInThread</Function> can now raise exceptions in threads blocked on I/O or time delays.
-</Para>
-</ListItem>
-
-<ListItem>
-<Para>
-New functions in <literal>Exception</literal>
-
-<ProgramListing>
-blockAsyncExceptions   :: IO a -> IO a
-unblockAsyncExceptions :: IO a -> IO a
-</ProgramListing>
-
-used to control the delivery of asynchronous exceptions to
-a thread (including those raised via <Function>raiseInThread</Function>).
-</Para>
-</ListItem>
-
-<ListItem>
-<Para>
-Asynchronous exceptions are now blocked by default inside
-an exception handler.  Use <Function>unblockAsyncExceptions</Function> to
-restore the previous behaviour.
-</Para>
-</ListItem>
-
-</ItemizedList>
-
-</Para>
-</ListItem>
-
-<ListItem>
-<Para>
-Add NetBSD/x86 support.
-</Para>
-</ListItem>
-
-<ListItem>
-<Para>
-Added support for <Literal>foreign export dynamic</Literal>.
-</Para>
-</ListItem>
-
-</ItemizedList>
-
-</Para>
-</ListItem>
-
-<ListItem>
-<Para>
-Minor changes
-
-<ItemizedList>
-
-<ListItem>
-<Para>
-Build system cleanup&mdash;<Command>BIN_DIST=1</Command> is now needed in <Filename>build.mk</Filename> (before building!) to build binary dists.
-</Para>
-</ListItem>
-
-<ListItem>
-<Para>
-New RTS option <Option>-xc</Option>, which prints the current cost-centre
-stack to stderr whenever an exception is raised (only for
-profiling builds).
-</Para>  
-</ListItem>
-
-</ItemizedList>
-
-</Para>
-</ListItem>
-
-<ListItem>
-<Para>
-Not-quite-ready-yet, but in there nontheless
-
-<VariableList>
-
-<VarListEntry>
-<Term>
-SMP support
-</Term>
-<ListItem>
-<Para>
-Building way '<Literal>s</Literal>' on a system with pthreads (only tested on
-Linux so far) will include support for running multiple
-Haskell threads on several pthreads simultaneously.  If
-your system supports it, this will enable Haskell programs
-to take advantage of multiprocessor SMP machines.
-</Para>
-</ListItem>
-</VarListEntry>
-
-<VarListEntry>
-<Term>
-GranSim and GUM
-</Term>
-<ListItem>
-<Para>
-Initial ports of GranSim and GUM to GHC 4 are in there.  Not quite
-ready yet.
-</Para>
-</ListItem>
-</VarListEntry>
-
-<VarListEntry>
-<Term>
-Profiling
-</Term>
-<ListItem>
-<Para>
-Heap profiling sort-of works.  Only cost-centre heap
-profiles are supported so far.
-</Para>
-</ListItem>
-</VarListEntry>
-
-</VariableList>
-
-</Para>
-</ListItem>
-
-</ItemizedList>
-
-</Para>
-
-</Sect1>
diff --git a/ghc/docs/users_guide/4-08-notes.sgml b/ghc/docs/users_guide/4-08-notes.sgml
deleted file mode 100644
index 135a93a..0000000
--- a/ghc/docs/users_guide/4-08-notes.sgml
+++ /dev/null
@@ -1,200 +0,0 @@
-<sect1 id="release-4-08">
-  <title>Release notes for version 4.08 (July 2000)</title>
-
-  <sect2>
-    <title>User-visible compiler changes</title>
-
-    <itemizedlist>
-      <listitem>
-	<para>New profiling subsystem, based on cost-centre stacks.
-	See <xref linkend="profiling">.</para>
-      </listitem>
-
-      <listitem>
-	<para>The x86 native code generator has been reworked
-	considerably, and now works reliably.  Using the NCG rather
-	than compiling via C reduces compilation times by roughly a
-	half while having minimal effect on the run-time of the
-	compiled program (about 2-4% slower, worse for floating-point
-	intensive programs).</para>
-
-	<para>The NCG is used by default for non-optimising compiles.
-	You can use it with <option>-O</option> by adding the
-	<option>-fasm-x86</option> flag to GHC's command
-	line, <emphasis>after</emphasis> <option>-O</option>.</para>
-      </listitem>
-
-      <listitem>
-	<para>Implicit parameters.  This Haskell extension gives a
-	statically-typed version of dynamic scoping that avoids the
-	worst problems of dynamic scoping in lisp.  See the
-	<ulink url="http://www.cse.ogi.ed/~jlewis/implicit.ps.gz">POPL paper</ulink>
-	for more details.  It is enabled by <option>-fglasgow-exts</option>.
-	</para>
-      </listitem>
-
-      <listitem>
-	<para>New <literal>DEPRECATED</literal> pragma for marking
-	outdated interfaces as deprecated.</para>
-      </listitem>
-
-      <listitem>
-	<para>New flag: <option>-ddump-minimal-imports</option>, which
-	dumps a file <literal>M.imports</literal> that contains the
-	(allegedly) minimal bunch of imports needed by the current
-	module.</para>
-      </listitem>
-
-      <listitem>
-	<para>New &ldquo;package&rdquo; system for libraries.  See
-	<xref linkend="packages"> for the details.</para>
-      </listitem>
-
-      <listitem>
-	<para>The long-standing bug that caused some programs which
-	used <link linkend="trace"><literal>trace</literal></link> to
-	exit with a deadlock error has been fixed.</para>
-      </listitem>
-
-      <listitem>
-	<para>Trying to put into a full <link
-	linkend="sec-MVars"><literal>MVar</literal></link> will now
-	raise a <link
-	linkend="PutFullMVar"><literal>PutFullMVar</literal></link>
-	exception.</para>
-      </listitem>
-
-      <listitem>
-	<para>If a thread is about to be garbage collected, because it
-	is waiting on an <literal>MVar</literal> that no other thread
-	has access to, then it will now be sent the <link
-	linkend="BlockedOnDeadMVar"><literal>BlockedOnDeadMVar</literal></link>
-	exception.</para>
-      </listitem>
-
-      <listitem>
-	<para>A thread that is found to be blocked against itself
-	(i.e. is black holed) is now sent a
-	<literal>NonTermination</literal> exception.</para>
-      </listitem>
-
-      <listitem>
-	<para>Operations which may <emphasis>block</emphasis>, such as
-	<literal>takeMVar</literal>, <literal>raiseInThread</literal>,
-	and several I/O operations, may now receive asynchronous
-	exceptions even in the scope of a
-	<literal>blockAsyncExceptions</literal>.  These are called
-	<firstterm>interruptible</firstterm> operations.  See <xref
-	linkend="interruptible-operations"> for more details.</para>
-      </listitem>
-
-      <listitem>
-	<para>Result type signatures now work.</para>
-      </listitem>
-
-      <listitem>
-	<para>A truckload of bugfixes.</para>
-      </listitem>
-      
-    </itemizedlist>
-  </sect2>
-
-  <sect2>
-    <title>User-visible library changes</title>
-
-    <itemizedlist>
-      <listitem>
-	<para>The FFI has been revised and expanded; see <xref
-	linkend="sec-Foreign">, <xref linkend="sec-CTypes">, and <xref
-	linkend="sec-CTypesISO"> .</para>
-      </listitem>
-
-      <listitem>
-	<para>HaXml, a library for parsing and generating XML, has
-	been added to the <literal>text</literal> package (<xref
-	linkend="sec-haxml">).</para>
-      </listitem>
-
-      <listitem>
-	<para>The <literal>QuickCheck</literal> library for performing
-	functional testing has been added to the
-	<literal>util</literal> package (<xref
-	linkend="sec-quickcheck">).</para>
-      </listitem>
-
-      <listitem>
-	<para>Two new experimental interfaces to arrays:
-	<literal>IArray</literal> for immutable arrays (<xref
-	linkend="sec-iarray">), and <literal>MArray</literal> for
-	mutable arrays (<xref linkend="sec-marray">). Comments on
-	these interfaces are welcome; eventually we'd like them to
-	replace <literal>ByteArray</literal>,
-	<literal>MutableArray</literal>, <literal>IOArray</literal>,
-	and <literal>STArray</literal>.</para>
-      </listitem>
-
-      <listitem>
-	<para>New function: <link
-	linkend="tryTakeMVar"><literal>tryTakeMVar</literal></link>.</para>
-      </listitem>
-
-      <listitem>
-	<para><literal>hPutBuf</literal>,
-	<literal>hPutBufBA</literal>, <literal>hGetBuf</literal>, and
-	<literal>hGetBufBA</literal>, have been renamed to
-	<literal>hPutBufFull</literal>,
-	<literal>hPutBufBAFull</literal>,
-	<literal>hGetBufFull</literal>, and
-	<literal>hGetBufBAFull</literal>.  Functions with the old
-	names still exist, but have slightly different semantics.  See
-	<xref linkend="sec-bulk-transfers"> for more details.</para>
-      </listitem>
-    </itemizedlist>
-  </sect2>
-
-  <sect2>
-    <title>Internal changes</title>
-
-    <itemizedlist>
-      <listitem>
-	<para><literal>Con</literal> is gone; the
-	<literal>CoreExpr</literal> type is simpler.</para>
-      </listitem>
-
-      <listitem>
-	<para><literal>NoRepLits</literal> have gone.</para>
-      </listitem>
-
-      <listitem>
-	<para>Better usage info in interface files, which means less
-	recompilation.</para>
-      </listitem>
-
-      <listitem>
-	<para>CCall primop is tidied up.</para>
-      </listitem>
-
-      <listitem>
-	<para>Constant folding is now done by Rules.</para>
-      </listitem>
-
-      <listitem>
-	<para>Lots of hackery in the simplifier.</para>
-      </listitem>
-
-      <listitem>
-	<para>Improvements in CPR and strictness analysis.</para>
-      </listitem>
-  
-    </itemizedlist>
-
-  </sect2>
-
-</sect1>
-
-<!-- Emacs stuff:
-     ;;; Local Variables: ***
-     ;;; mode: sgml ***
-     ;;; sgml-parent-document: ("users_guide.sgml" "book" "chapter" "sect1") ***
-     ;;; End: ***
- -->
diff --git a/ghc/docs/users_guide/5-00-notes.sgml b/ghc/docs/users_guide/5-00-notes.sgml
new file mode 100644
index 0000000..2e20572
--- /dev/null
+++ b/ghc/docs/users_guide/5-00-notes.sgml
@@ -0,0 +1,54 @@
+<sect1 id="release-5-00">
+  <title>Release notes for version 5.00 (February 2001)</title>
+
+  <sect2>
+    <title>User-visible compiler changes</title>
+    <itemizedlist>
+      <listitem>
+	<para>GHCi added</para>
+      </listitem>
+      <listitem>
+	<para><option>--make</option> flag added</para>
+      </listitem>
+      <listitem>
+	<para>dynamic vs. static options</para>
+      </listitem>
+      <listitem>
+	<para>NCG support for Sparc</para>
+      </listitem>
+      <listitem>
+	<para><command>hsc2hs</command> added</para>
+      </listitem>
+    </itemizedlist>
+  </sect2>
+
+  <sect2>
+    <title>User-visible library changes</title>
+    <itemizedlist>
+      <listitem>
+	<para>FFI libraries enhanced, lots of deprecations.</para>
+      </listitem>
+    </itemizedlist>
+  </sect2>
+
+  <sect2>
+    <title>Internal changes</title>
+    <itemizedlist>
+      <listitem>
+	<para>The old perl driver has been removed and replaced by a
+	driver in the compiler proper.</para>
+      </listitem>
+      <listitem>
+	<para>Several libraries rewritten to use the FFI.</para>
+      </listitem>
+    </itemizedlist>
+  </sect2>
+
+</sect1>
+
+<!-- Emacs stuff:
+     ;;; Local Variables: ***
+     ;;; mode: sgml ***
+     ;;; sgml-parent-document: ("users_guide.sgml" "book" "chapter" "sect1") ***
+     ;;; End: ***
+ -->
diff --git a/ghc/docs/users_guide/flags.sgml b/ghc/docs/users_guide/flags.sgml
index 3efd5ca..c662ebe 100644
--- a/ghc/docs/users_guide/flags.sgml
+++ b/ghc/docs/users_guide/flags.sgml
@@ -456,19 +456,19 @@
 	  <row>
 	    <entry><option>-W</option></entry>
 	    <entry>enable normal warnings</entry>
-	    <entry>static</entry>
+	    <entry>dynamic</entry>
 	    <entry><option>-w</option></entry>
 	  </row>
 	  <row>
 	    <entry><option>-w</option></entry>
 	    <entry>disable all warnings</entry>
-	    <entry>static</entry>
+	    <entry>dynamic</entry>
 	    <entry>-</entry>
 	  </row>
 	  <row>
 	    <entry><option>-Wall</option></entry>
 	    <entry>enable all warnings</entry>
-	    <entry>static</entry>
+	    <entry>dynamic</entry>
 	    <entry><option>-w</option></entry>
 	  </row>
 
diff --git a/ghc/docs/users_guide/ghci.sgml b/ghc/docs/users_guide/ghci.sgml
index 4af9d61..0782559 100644
--- a/ghc/docs/users_guide/ghci.sgml
+++ b/ghc/docs/users_guide/ghci.sgml
@@ -1,4 +1,4 @@
-<chapter>
+<chapter id="ghci">
   <title>Using GHCi</title>
   
   <para>ToDo</para>
diff --git a/ghc/docs/users_guide/installing.sgml b/ghc/docs/users_guide/installing.sgml
index 7040cad..1c13c69 100644
--- a/ghc/docs/users_guide/installing.sgml
+++ b/ghc/docs/users_guide/installing.sgml
@@ -1,25 +1,72 @@
 <Chapter id="sec-installing-bin-distrib">
-<Title>Installing from binary distributions</Title>
+  <Title>Installing GHC</Title>
 <IndexTerm><Primary>binary installations</Primary></IndexTerm>
 <IndexTerm><Primary>installation, of binaries</Primary></IndexTerm>
 
 <Para>
 Installing from binary distributions is easiest, and recommended!
 (Why binaries? Because GHC is a Haskell compiler written in Haskell,
-so you've got to bootstrap it somehow.  We provide
-machine-generated C-files-from-Haskell for this purpose, but it's
-really quite a pain to use them.  If you must build GHC from its
-sources, using a binary-distributed GHC to do so is a sensible way to
-proceed. For the other <Literal>fptools</Literal> programs, many are written in Haskell, so binary distributions allow you to install them without having a Haskell compiler.)
+so you've got to bootstrap it somehow.  We provide machine-generated
+C-files-from-Haskell for this purpose, but it's really quite a pain to
+use them.  If you must build GHC from its sources, using a
+binary-distributed GHC to do so is a sensible way to proceed. For the
+other <Literal>fptools</Literal> programs, many are written in
+Haskell, so binary distributions allow you to install them without
+having a Haskell compiler.)
 </Para>
 
 <Para>This guide is in two parts: installing on Unix-a-likes, and installing on Windows.</Para>
 
 
-<Sect1><Title>Installing on Unix-a-likes</Title>
+  <Sect1><Title>Installing on Unix-a-likes</Title>
+
+    <sect2>
+      <title>When a platform-specific package is available</title>
+      
+      <para>For certain platforms, we provide GHC binaries packaged
+      using the native package format for the platform.  This is
+      likely to be by far the best way to install GHC for your
+      platform if one of these packages is available, since
+      dependencies will automatically be handled and the package
+      system normally provides a way to uninstall the package at a
+      later date.</para>
+
+      <para>We generally provide the following packages:</para>
+
+      <variablelist>
+	<varlistentry>
+	  <term>RedHat Linux/x86</term>
+	  <listitem>
+	    <para>RPM source & binary packages for RedHat Linux (x86
+	    only) are available for most major releases.</para>
+	  </listitem>
+	</varlistentry>
+
+	<varlistentry>
+	  <term>Debian Linux/x86</term>
+	  <listitem>
+	    <para>Debian packages for Linux (x86 only), also for most
+	    major releases.</para>
+	  </listitem>
+	</varlistentry>
+
+	<varlistentry>
+	  <term>FreeBSD/x86</term>
+	  <listitem>
+	    <para>On FreeBSD/x86, GHC can be installed using either
+	    the ports tree (<literal>cd /usr/ports/lang/ghc && make
+	    install</literal>) or from a pre-compiled package
+	    available from your local FreeBSD mirror.</para>
+	  </listitem>
+	</varlistentry>
+      </variablelist>
+      
+      <para>Other platform-specific packages may be available, check
+      the GHC download page for details.</para>
+    </sect2>
 
 <Sect2>
-<Title>Bundle structure</Title>
+<Title>GHC binary distributions</Title>
 
 <Para>
 <IndexTerm><Primary>bundles of binary stuff</Primary></IndexTerm>
@@ -27,7 +74,7 @@ proceed. For the other <Literal>fptools</Literal> programs, many are written in
 
 <Para>
 Binary distributions come in &ldquo;bundles,&rdquo; one bundle per file called
-<Literal>&lt;bundle&gt;-&lt;platform&gt;.tar.gz</Literal>.  (See the building guide for the definition of a platform.)  Suppose that you untar a binary-distribution bundle, thus:
+<literal><replaceable>bundle</replaceable>-<replaceable>platform</replaceable>.tar.gz</Literal>.  (See the building guide for the definition of a platform.)  Suppose that you untar a binary-distribution bundle, thus:
 </Para>
 
 <Para>
@@ -95,7 +142,7 @@ Guide and this file isn't present.
 </Para>
 </ListItem></VarListEntry>
 <VarListEntry>
-<Term><Literal>bin/&lt;platform&gt;</Literal></Term>
+	    <Term><Literal>bin/<replaceable>platform</replaceable></Literal></Term>
 <ListItem>
 <Para>
 contains platform-specific executable
@@ -104,7 +151,7 @@ must end up in your path.
 </Para>
 </ListItem></VarListEntry>
 <VarListEntry>
-<Term><Literal>lib/&lt;platform&gt;/</Literal></Term>
+<Term><Literal>lib/<replaceable>platform</replaceable>/</Literal></Term>
 <ListItem>
 <Para>
 contains platform-specific support
@@ -179,41 +226,6 @@ contains Unix manual pages.
 </VariableList>
 </Para>
 
-<Para>
-This structure is designed so that you can unpack multiple bundles
-(including ones from different releases or platforms) into a single
-<Literal>fptools</Literal> directory
-<FOOTNOTE>
-
-<Para>
-this doesn't work at the
-moment
-</Para>
-
-</FOOTNOTE>
-:
-</Para>
-
-<Para>
-
-<Screen>
-% cd /your/scratch/space
-% gunzip &#60; ghc-x.xx-sun-sparc-solaris2.tar.gz | tar xvf -
-% gunzip &#60; happy-x.xx-sun-sparc-sunos4.tar.gz | tar xvf -</Screen>
-
-</Para>
-
-<Para>
-When you do multiple unpacks like this, the top level <Literal>Makefile</Literal>,
-<Literal>README</Literal>, and <Literal>INSTALL</Literal> get overwritten each time.
-That's fine&mdash;they should be the same.  Likewise, the
-<Literal>ANNOUNCE-&lt;bundle&gt;</Literal> and <Literal>NEWS-&lt;bundle&gt;</Literal>
-files will be duplicated across multiple platforms, so they will be
-harmlessly overwritten when you do multiple unpacks.  Finally, the
-<Literal>share/</Literal> stuff will get harmlessly overwritten when you do
-multiple unpacks for one bundle on different platforms.
-</Para>
-
 <Sect3 id="sec-install">
 <Title>Installing</Title>
 
@@ -379,11 +391,12 @@ regardless, <Literal>ghc-x.xx</Literal> should always invoke GHC version <Litera
 <Title>What bundles there are</Title>
 
 <Para>
-<IndexTerm><Primary>bundles, binary</Primary></IndexTerm>
-There are plenty of &ldquo;non-basic&rdquo; GHC bundles.  The files for them are
-called <Literal>ghc-x.xx-&lt;bundle&gt;-&lt;platform&gt;.tar.gz</Literal>, where
-the <Literal>&lt;platform&gt;</Literal> is as above, and <Literal>&lt;bundle&gt;</Literal> is one
-of these:
+<IndexTerm><Primary>bundles, binary</Primary></IndexTerm> There are
+plenty of &ldquo;non-basic&rdquo; GHC bundles.  The files for them are
+called
+<Literal>ghc-x.xx-<replaceable>bundle</replaceable>-<replaceable>platform</replaceable>.tar.gz</Literal>,
+where the <replaceable>platform</replaceable> is as above, and
+<replaceable>bundle</replaceable> is one of these:
 </Para>
 
 <Para>
@@ -438,6 +451,12 @@ binary bundles&mdash;basic, and profiling.  We don't usually make the
 rest, although you can build them yourself from a source distribution.
 </Para>
 
+<para>The various GHC bundles are designed to be unpacked into the
+same directory; then installing as per the directions above will
+install the whole lot in one go.  Note: you <emphasis>must</emphasis>
+at least have the basic GHC binary distribution bundle, these extra
+bundles won't install on their own.</para>
+
 </Sect3>
 
 <Sect3 id="sec-GHC-test">
@@ -487,12 +506,8 @@ Some simple-but-profitable tests are to compile and run the notorious
 distributed in <Literal>ghc/misc/examples/nfib/</Literal> in a source distribution.
 </Para>
 
-<Para>
-For more information on how to &ldquo;drive&rdquo; GHC, either do <Literal>ghc -help</Literal> or
-consult the User's Guide (distributed in several pre-compiled formats
-with a binary distribution, or in source form in
-<Literal>ghc/docs/users&lowbar;guide</Literal> in a source distribution).
-</Para>
+<para>For more information on how to &ldquo;drive&rdquo; GHC, read
+on...</para>
 
 </Sect3>
 
diff --git a/ghc/docs/users_guide/intro.sgml b/ghc/docs/users_guide/intro.sgml
index 883377c..175a5e9 100644
--- a/ghc/docs/users_guide/intro.sgml
+++ b/ghc/docs/users_guide/intro.sgml
@@ -1,219 +1,48 @@
-<Chapter id="introduction-GHC">
-<Title>Introduction to GHC
-</Title>
-
-<Para>
-This is a guide to using the Glasgow Haskell compilation (GHC) system. It is
-a batch compiler for the Haskell&nbsp;98 language, with support for various
-Glasgow-only extensions. In this document, we assume that GHC has been
-installed at your site as <Literal>ghc</Literal>.  A separate document,
-&ldquo;Building and Installing the Glasgow Functional Programming Tools Suite&rdquo;,
-describes how to install <Literal>ghc</Literal>.
-</Para>
-
-<Para>
-Many people will use GHC very simply: compile some
-modules&mdash;<Literal>ghc -c -O Foo.hs Bar.hs</Literal>; and link them&mdash;
-<Literal>ghc -o wiggle -O Foo.o Bar.o</Literal>.
-</Para>
-
-<Para>
-But if you need to do something more complicated, GHC can do that,
-too:
-
-<Screen>
-ghc -c -O -fno-foldr-build -dcore-lint -fvia-C -ddump-simpl Foo.lhs
-</Screen>
-
-Stay tuned&mdash;all will be revealed!
-</Para>
-
-<Para>
-The rest of this section provide some tutorial information
-on batch-style compilation; if you're familiar with these concepts
-already, then feel free to skip to the next section.
-</Para>
-
-<Sect1 id="batch-system-parts">
-<Title>The (batch) compilation system components</Title>
-
-<Para>
-The Glorious Haskell Compilation System, as with most UNIX (batch)
-compilation systems, has several interacting parts:
-
-<OrderedList>
-<ListItem>
-<Para>
-A <Emphasis>driver</Emphasis><IndexTerm><Primary>driver
-program</Primary></IndexTerm>
-<Literal>ghc</Literal><IndexTerm><Primary>ghc</Primary></IndexTerm>&mdash;which
-you usually think of as &ldquo;the compiler&rdquo;&mdash;is a program
-that merely invokes/glues-together the other pieces of the system
-(listed below), passing the right options to each, slurping in the
-right libraries, etc.
-</Para>
-</ListItem>
-
-<ListItem>
-<Para>
-A <Emphasis>literate pre-processor</Emphasis>
-<IndexTerm><Primary>literate pre-processor</Primary></IndexTerm>
-<IndexTerm><Primary>pre-processor, literate</Primary></IndexTerm>
-<Literal>unlit</Literal><IndexTerm><Primary>unlit</Primary></IndexTerm> that extracts Haskell
-code from a literate script; used if you believe in that sort of
-thing.
-</Para>
-</ListItem>
-
-<ListItem>
-<Para>
-The <Emphasis>Haskellised C pre-processor</Emphasis>
-<IndexTerm><Primary>Haskellised C pre-processor</Primary></IndexTerm>
-<IndexTerm><Primary>C pre-processor, Haskellised</Primary></IndexTerm>
-<IndexTerm><Primary>pre-processor, Haskellised C</Primary></IndexTerm>
-<Literal>hscpp</Literal>,<IndexTerm><Primary>hscpp</Primary></IndexTerm> only needed by people requiring conditional
-compilation, probably for large systems.  The &ldquo;Haskellised&rdquo; part
-just means that <Literal>&num;line</Literal> directives in the output have been
-converted into proper Haskell <Literal>&lcub;-&num; LINE ... -&rcub;</Literal> pragmas. You must give an explicit <Literal>-cpp</Literal> option 
-<IndexTerm><Primary>-cpp option</Primary></IndexTerm> for the C pre-processor to be invoked.
-</Para>
-</ListItem>
-
-<ListItem>
-<Para>
-The <Emphasis>Haskell compiler</Emphasis>
-<IndexTerm><Primary>Haskell compiler</Primary></IndexTerm>
-<IndexTerm><Primary>compiler, Haskell</Primary></IndexTerm>
-<Literal>hsc</Literal>,<IndexTerm><Primary>hsc</Primary></IndexTerm>
-which&mdash;in normal use&mdash;takes its input from the C pre-processor
-and produces assembly-language output (sometimes: ANSI C output).
-</Para>
-</ListItem>
-
-<ListItem>
-<Para>
-The <Emphasis>ANSI&nbsp;C Haskell high-level assembler :-)</Emphasis>
-<IndexTerm><Primary>ANSI C compiler</Primary></IndexTerm>
-<IndexTerm><Primary>high-level assembler</Primary></IndexTerm>
-<IndexTerm><Primary>assembler, high-level</Primary></IndexTerm>
-compiles <Literal>hsc</Literal>'s C output into assembly language for a particular
-target architecture.  In fact, the only C compiler we currently
-support is <Literal>gcc</Literal>, because we make use of certain extensions to the
-C language only supported by gcc.  Version 2.x is a must; we recommend
-version 2.7.2.1 for stability (we've heard both good and bad reports
-of later versions).
-</Para>
-</ListItem>
-
-<ListItem>
-<Para>
-The <Emphasis>assembler</Emphasis><IndexTerm><Primary>assembler</Primary></IndexTerm>&mdash;a standard UNIX one, probably
-<Literal>as</Literal><IndexTerm><Primary>as</Primary></IndexTerm>.
-</Para>
-</ListItem>
-
-<ListItem>
-<Para>
-The <Emphasis>linker</Emphasis><IndexTerm><Primary>linker</Primary></IndexTerm>&mdash;a standard UNIX one, probably
-<Literal>ld</Literal>.<IndexTerm><Primary>ld</Primary></IndexTerm>
-</Para>
-</ListItem>
-
-<ListItem>
-<Para>
-A <Emphasis>runtime system</Emphasis>,<IndexTerm><Primary>runtime system</Primary></IndexTerm> including (most notably)
-a storage manager; the linker links in the code for this.
-</Para>
-</ListItem>
-
-<ListItem>
-<Para>
-The <Emphasis>Haskell standard prelude</Emphasis><IndexTerm><Primary>standard prelude</Primary></IndexTerm>, a
-large library of standard functions, is linked in as well.
-</Para>
-</ListItem>
-
-<ListItem>
-<Para>
-Parts of other <Emphasis>installed libraries</Emphasis> that you have at your site may be linked in also.
-</Para>
-</ListItem>
-
-</OrderedList>
-</Para>
-
-</Sect1>
-
-<Sect1 id="compile-what-really-happens">
-<Title>What really happens when I &ldquo;compile&rdquo; a Haskell program?
-</Title>
-
-<Para>
-You invoke the Glasgow Haskell compilation system through the
-driver program <Literal>ghc</Literal>.<IndexTerm><Primary>ghc</Primary></IndexTerm> For example, if you had typed a
-literate &ldquo;Hello, world!&rdquo; program into <Literal>hello.lhs</Literal>, and you then
-invoked:
-
-<Screen>
-ghc hello.lhs
-</Screen>
-
-</Para>
-
-<Para>
-the following would happen:
-
-<OrderedList>
-<ListItem>
-
-<Para>
-The file <Literal>hello.lhs</Literal> is run through the literate-program
-code extractor <Literal>unlit</Literal><IndexTerm><Primary>unlit</Primary></IndexTerm>, feeding its output to
-
-</Para>
-</ListItem>
-<ListItem>
-
-<Para>
-The Haskell compiler proper <Literal>hsc</Literal><IndexTerm><Primary>hsc</Primary></IndexTerm>, which produces
-input for
-
-</Para>
-</ListItem>
-<ListItem>
-
-<Para>
-The assembler (or that ubiquitous &ldquo;high-level assembler,&rdquo; a C
-compiler), which produces an object file and passes it to
-
-</Para>
-</ListItem>
-<ListItem>
-
-<Para>
-The linker, which links your code with the appropriate libraries
-(including the standard prelude), producing an executable program in
-the default output file named <Literal>a.out</Literal>.
-</Para>
-</ListItem>
-
-</OrderedList>
-
-</Para>
-
-<Para>
-You have considerable control over the compilation process.  You feed
-command-line arguments (call them &ldquo;options,&rdquo; for short) to the
-driver, <Literal>ghc</Literal>; the &ldquo;types&rdquo; of the input files (as encoded in
-their names' suffixes) also matter.
-</Para>
-
-<Para>
-Here's hoping this is enough background so that you can read the rest
-of this guide!
-</Para>
-
-</Sect1>
+<chapter id="introduction-GHC">
+  <title>Introduction to GHC</title>
+
+  <para>This is a guide to using the Glasgow Haskell Compiler (GHC):
+  an interactive and batch compilation system for the <ulink
+  url="http://www.haskell.org/">Haskell&nbsp;98</ulink>
+  language.</para>
+
+  <para>GHC has two main components: an interactive Haskell
+  interpreter (also known as GHCi), described in <xref
+  linkend="ghci">, and a batch compiler, described throughout <xref
+  linkend="using-ghc">.  In fact, GHC consists of a single program
+  which is just run with different options to provide either the
+  interactive or the batch system.</para>
+
+  <para>The batch compiler can be used alongside GHCi: compiled
+  modules can be loaded into an interactive session and used in the
+  same way as interpreted code, and in fact when using GHCi most of
+  the library code will be pre-compiled.  This means you get the best
+  of both worlds: fast pre-compiled library code, and fast compile
+  turnaround for the parts of your program being actively
+  developed.</para>
+
+  <para>GHC supports numerous language extensions, including
+  concurrency, a foreign function interface, exceptions, type system
+  extensions such as multi-parameter type classes, local universal and
+  existential quantification, functional dependencies, scoped type
+  variables and explicit unboxed types.  These are all described in
+  <xref linkend="ghc-language-features">.</para>
+
+  <para>GHC has a comprehensive optimiser, so when you want to Really
+  Go For It (and you've got time to spare) GHC can produce pretty fast
+  code.  Alternatively, the default option is to compile as fast as
+  possible while not making too much effort to optimise the generated
+  code (although GHC probably isn't what you'd describe as a fast
+  compiler :-).</para>
+  
+  <para>GHC's profiling system supports &ldquo;cost centre
+  stacks&rdquo;: a way of seeing the profile of a Haskell program in a
+  call-graph like structure.  See <xref linkend="profiling"> for more
+  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>
 
   <Sect1 id="mailing-lists-GHC">
     <Title>Meta-information: Web sites, mailing lists, etc.</Title>
@@ -221,119 +50,167 @@ of this guide!
     <IndexTerm><Primary>mailing lists, Glasgow Haskell</Primary></IndexTerm>
     <IndexTerm><Primary>Glasgow Haskell mailing lists</Primary></IndexTerm>
 
-<Para>On the World-Wide Web, there are several URLs of likely
-interest:</Para>
-
-<Para>
-
-<ItemizedList>
-<ListItem>
-
-<Para>
-  <ULink
-URL="http://www.haskell.org/"
->Haskell home page</ULink
->
-</Para>
-</ListItem>
-<ListItem>
-
-<Para>
-  <ULink
-URL="http://www.haskell.org/ghc/"
->GHC home page</ULink
->
-</Para>
-</ListItem>
-<ListItem>
-
-<Para>
-  <ULink
-URL="http://www.cs.nott.ac.uk/Department/Staff/mpj/faq.html"
->comp.lang.functional FAQ</ULink
->
-</Para>
-</ListItem>
-
-</ItemizedList>
-
-</Para>
-
-<Para>
-We run two mailing lists about Glasgow Haskell.  We encourage you to
-join, as you feel is appropriate.
-</Para>
-
-<VariableList>
-<VarListEntry>
-<Term>glasgow-haskell-users:</Term>
-<ListItem>
-<Para>
-This list is for GHC users to chat among themselves.  Subscription can
-be done on-line at <ulink
-url="http://www.haskell.org/mailman/listinfo/glasgow-haskell-users"><literal>http://www.haskell.org/mailman/listinfo/glasgow-haskell-users</literal></ulink>.</para>
-
-<Para>
-To communicate with your fellow users, send mail to <email>glasgow-haskell-users@haskell.org</email>.
-</Para>
-
-<Para>
-To contact the list administrator, send mail to
-<email>glasgow-haskell-users-admin@haskell.org</email>.  An archive
-of the list is available at <ulink url="http://www.haskell.org/pipermail/glasgow-haskell-users/"><literal>http://www.haskell.org/pipermail/glasgow-haskell-users/</literal></ulink>.
-
-</Para>
-</ListItem>
-</VarListEntry>
-<VarListEntry>
-<Term>glasgow-haskell-bugs:</Term>
-<ListItem>
-<Para>
-Send bug reports for GHC to this address!  The sad and lonely people
-who subscribe to this list will muse upon what's wrong and what you
-might do about it.
-</Para>
-
-<para>Subscription can be done on-line at <ulink
-url="http://www.haskell.org/mailman/listinfo/glasgow-haskell-bugs"><literal>http://www.haskell.org/mailman/listinfo/glasgow-haskell-bugs</literal></ulink>.</para>
-
-<Para>
-Again, you may contact the list administrator at
-<email>glasgow-haskell-bugs-admin@haskell.org</email>.  And, yes, an
-archive of the list is available on the Web at the <ulink url="http://www.haskell.org/pipermail/glasgow-haskell-bugs/"><literal>http://www.haskell.org/pipermail/glasgow-haskell-bugs/</literal></ulink>.</Para>
-</ListItem>
-</VarListEntry>
+    <para>On the World-Wide Web, there are several URLs of likely
+    interest:</para>
 
+    <itemizedlist>
+      <listitem>
+	<para><ulink URL="http://www.haskell.org/" >Haskell home
+	page</ulink></para>
+      </listitem>
+
+      <listitem>
+	<para><ulink URL="http://www.haskell.org/ghc/">GHC home
+	page</ulink></para>
+      </listitem>
+
+      <listitem>
+	<para><ulink
+	URL="http://www.cs.nott.ac.uk/Department/Staff/mpj/faq.html">comp.lang.functional
+	FAQ</ulink></para>
+      </listitem>
+
+    </itemizedlist>
+
+    <para>We run the following mailing lists about Glasgow Haskell.
+    We encourage you to join, as you feel is appropriate.</para>
+
+    <variablelist>
+      <varlistentry>
+	<term>glasgow-haskell-users:</term>
+	<listitem>
+	  <para>This list is for GHC users to chat among
+	  themselves.</para>
+
+	  <variablelist>
 	    <varlistentry>
-	      <term>cvs-ghc:</term>
+	      <term>list email address:</term>
 	      <listitem>
-		<para>The hardcore GHC developers hang out here.  This
-		list also gets commit message from the CVS repository.
-		There are several other similar lists for other parts
-		of the CVS repository
-		(eg. <literal>cvs-hslibs</literal>,
-		<literal>cvs-happy</literal>,
-		<literal>cvs-hdirect</literal> etc.)</para>
+		<para><email>glasgow-haskell-users@haskell.org</email></para>
+	      </listitem>
+	    </varlistentry>
 
-		<para>To subscribe: <ulink
-                url="http://www.haskell.org/mailman/listinfo/cvs-ghc"><literal>http://www.haskell.org/mailman/listinfo/cvs-ghc</literal></ulink></para>
+	    <varlistentry>
+	      <term>subscribe at:</term> 
+	      <listitem>
+		<para><ulink
+	      url="http://www.haskell.org/mailman/listinfo/glasgow-haskell-users"><literal>http://www.haskell.org/mailman/listinfo/glasgow-haskell-users</literal></ulink>.</para>
+	      </listitem>
+	    </varlistentry>
 
+	    <varlistentry>
+	      <term>admin email address:</term>
+	      <listitem>
+		<para><email>glasgow-haskell-users-admin@haskell.org</email></para>
+	      </listitem>
+	    </varlistentry>
+
+	    <varlistentry>
+	      <term>list archives:</term>
+	      <listitem>
+		<para><ulink
+          url="http://www.haskell.org/pipermail/glasgow-haskell-users/"><literal>http://www.haskell.org/pipermail/glasgow-haskell-users/</literal></ulink></para>
 	      </listitem>
 	    </varlistentry>
 	  </variablelist>
+	</listitem>
+      </varlistentry>
 
-<Para>
-There are several other haskell and GHC-related mailing lists served
-by <literal>www.haskell.org</literal>.  Go to <ulink
-url="http://www.haskell.org/mailman/listinfo/"><literal>http://www.haskell.org/mailman/listinfo/</literal></ulink>
-for the full list.</Para>
+      <varlistentry>
+	<term>glasgow-haskell-bugs:</term>
+	<listitem>
+	  <para>Send bug reports for GHC to this address!  The sad and
+          lonely people who subscribe to this list will muse upon
+          what's wrong and what you might do about it.</para>
 
-<Para>
-Some Haskell-related discussion also takes place in the Usenet
-newsgroup <Literal>comp.lang.functional</Literal>.
-</Para>
+	  <variablelist>
+	    <varlistentry>
+	      <term>list email address:</term>
+	      <listitem>
+		<para><email>glasgow-haskell-bugs@haskell.org</email></para>
+	      </listitem>
+	    </varlistentry>
 
-  </Sect1>
+	    <varlistentry>
+	      <term>subscribe at:</term> 
+	      <listitem>
+		<para><ulink
+	      url="http://www.haskell.org/mailman/listinfo/glasgow-haskell-bugs"><literal>http://www.haskell.org/mailman/listinfo/glasgow-haskell-bugs</literal></ulink>.</para>
+	      </listitem>
+	    </varlistentry>
+
+	    <varlistentry>
+	      <term>admin email address:</term>
+	      <listitem>
+		<para><email>glasgow-haskell-bugs-admin@haskell.org</email></para>
+	      </listitem>
+	    </varlistentry>
+
+	    <varlistentry>
+	      <term>list archives:</term>
+	      <listitem>
+		<para><ulink
+          url="http://www.haskell.org/pipermail/glasgow-haskell-bugs/"><literal>http://www.haskell.org/pipermail/glasgow-haskell-bugs/</literal></ulink></para>
+	      </listitem>
+	    </varlistentry>
+	  </variablelist>
+	</listitem>
+      </varlistentry>
+
+      <varlistentry>
+	<term>cvs-ghc:</term>
+	<listitem>
+	  <para>The hardcore GHC developers hang out here.  This list
+	  also gets commit message from the CVS repository.  There are
+	  several other similar lists for other parts of the CVS
+	  repository (eg. <literal>cvs-hslibs</literal>,
+	  <literal>cvs-happy</literal>, <literal>cvs-hdirect</literal>
+	  etc.)</para>
+	  
+	  <variablelist>
+	    <varlistentry>
+	      <term>list email address:</term>
+	      <listitem>
+		<para><email>cvs-ghc@haskell.org</email></para>
+	      </listitem>
+	    </varlistentry>
+
+	    <varlistentry>
+	      <term>subscribe at:</term> 
+	      <listitem>
+		<para><ulink
+	      url="http://www.haskell.org/mailman/listinfo/cvs-ghc"><literal>http://www.haskell.org/mailman/listinfo/cvs-ghc</literal></ulink>.</para>
+	      </listitem>
+	    </varlistentry>
+
+	    <varlistentry>
+	      <term>admin email address:</term>
+	      <listitem>
+		<para><email>cvs-ghc-admin@haskell.org</email></para>
+	      </listitem>
+	    </varlistentry>
+
+	    <varlistentry>
+	      <term>list archives:</term>
+	      <listitem>
+		<para><ulink
+          url="http://www.haskell.org/pipermail/cvs-ghc/"><literal>http://www.haskell.org/pipermail/cvs-ghc/</literal></ulink></para>
+	      </listitem>
+	    </varlistentry>
+	  </variablelist>
+	</listitem>
+      </varlistentry>
+    </variablelist>
+
+    <para>There are several other haskell and GHC-related mailing
+    lists served by <literal>www.haskell.org</literal>.  Go to <ulink
+    url="http://www.haskell.org/mailman/listinfo/"><literal>http://www.haskell.org/mailman/listinfo/</literal></ulink>
+    for the full list.</para>
+
+    <para>Some Haskell-related discussion also takes place in the
+    Usenet newsgroup <literal>comp.lang.functional</literal>.</para>
+
+  </sect1>
 
   <sect1 id="version-numbering">
     <title>GHC version numbering policy</title>
@@ -353,7 +230,7 @@ newsgroup <Literal>comp.lang.functional</Literal>.
 	  is zero).  Patchlevels are bug-fix releases only, and never
 	  change the programmer interface to any system-supplied code.
 	  However, if you install a new patchlevel over an old one you
-	  may need to recompile any code that was compiled against the
+	  will need to recompile any code that was compiled against the
 	  old libraries.</para>
 
 	  <para>The value of <literal>__GLASGOW_HASKELL__</literal>
@@ -400,7 +277,8 @@ newsgroup <Literal>comp.lang.functional</Literal>.
     
     <para>The version number of your copy of GHC can be found by
     invoking <literal>ghc</literal> with the
-    <literal>--version</literal> flag.</para>
+    <literal>--version</literal> flag (see <xref
+    linkend="options-help">).</para>
   </sect1>
 
 
diff --git a/ghc/docs/users_guide/ug-book.sgml b/ghc/docs/users_guide/ug-book.sgml
index a410ed9..f557d34 100644
--- 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 4.08</Title>
+<Title>The Glasgow Haskell Compiler User's Guide, Version 5.00</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 6b6007b..0c56c2f 100644
--- a/ghc/docs/users_guide/ug-ent.sgml
+++ b/ghc/docs/users_guide/ug-ent.sgml
@@ -2,7 +2,7 @@
 <!ENTITY flags          SYSTEM "flags.sgml">
 <!ENTITY license        SYSTEM "license.sgml">
 <!ENTITY intro          SYSTEM "intro.sgml" >
-<!ENTITY relnotes       SYSTEM "4-08-notes.sgml" >
+<!ENTITY relnotes       SYSTEM "5-00-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 125177c..69cd3d0 100644
--- a/ghc/docs/users_guide/using.sgml
+++ b/ghc/docs/users_guide/using.sgml
@@ -1,4 +1,4 @@
-<chapter>
+<chapter id="using-ghc">
   <title>Using GHC</title>
 
   <indexterm><primary>GHC, using</primary></indexterm>
-- 
1.7.10.4