[project @ 2004-06-02 08:53:54 by panne]
[ghc-hetmet.git] / docs / building / building.sgml
index 565b0be..ecac376 100644 (file)
@@ -1,13 +1,13 @@
 <!DOCTYPE Article PUBLIC "-//OASIS//DTD DocBook V3.1//EN">
 
-<Article id="building-guide">
+<article id="building-guide">
 
-<ArtHeader>
+<artheader>
 
-<Title>Building the Glasgow Functional Programming Tools Suite</Title>
-<Author><OtherName>The GHC Team</OtherName></Author>
-<Address><Email>glasgow-haskell-&lcub;users,bugs&rcub;@haskell.org</Email></Address>
-<PubDate>November 2001</PubDate>
+<title>Building the Glasgow Functional Programming Tools Suite</title>
+<author><othername>The GHC Team</othername></author>
+<address><email>glasgow-haskell-&lcub;users,bugs&rcub;@haskell.org</email></address>
+<pubdate>November 2001</pubdate>
 
     <abstract>
       <para>The Glasgow fptools suite is a collection of Functional
       installation system.</para>
 
       <para>This guide is intended for people who want to build or
-      modify programs from the Glasgow <Literal>fptools</Literal>
+      modify programs from the Glasgow <literal>fptools</literal>
       suite (as distinct from those who merely want to
-      <Emphasis>run</Emphasis> them). Installation instructions are
+      <emphasis>run</emphasis> them). Installation instructions are
       now provided in the user guide.</para>
 
       <para>The bulk of this guide applies to building on Unix
-      systems; see <XRef LinkEnd="winbuild"> for Windows notes.</para>
+      systems; see <xref linkend="winbuild"/> for Windows notes.</para>
     </abstract>
 
-  </artheader>
+</artheader>
 
 
   <sect1 id="sec-getting">
           the parser specifications.  If you don't want to alter the
           parser then this saves you having to find and install
           <command>happy</command>. You will still need a working
-          version of GHC (preferably version 4.08+) on your machine in
+          version of GHC (version 5.x or later) on your machine in
           order to compile (most of) the sources, however.</para>
        </listitem>
       </varlistentry>
 
       <varlistentry>
-       <term>The CVS repository.</term>
-       <indexterm><primary>CVS repository</primary>
-       </indexterm>
+       <term>The CVS repository.<indexterm><primary>CVS repository</primary></indexterm></term>
        <listitem>
          <para>We make releases infrequently.  If you want more
           up-to-the minute (but less tested) source code then you need
@@ -84,7 +82,7 @@
           scratch.</para>
 
          <para>More information about our CVS repository can be found
-          in <xref linkend="sec-cvs">.</para>
+          in <xref linkend="sec-cvs"/>.</para>
        </listitem>
       </varlistentry>
     </variablelist>
     remember is that most mistakes can be undone, but if there's
     anything you're not sure about feel free to bug the local CVS
     meister (namely Jeff Lewis
-    <email>jlewis@galconn.com</email>). </para>
+    <email>jlewis@galois.com</email>). </para>
 
     <sect2 id="cvs-access">
       <title>Getting access to the CVS Repository</title>
 
       <para>You can access the repository in one of two ways:
-      read-only (<xref linkend="cvs-read-only">), or read-write (<xref
-      linkend="cvs-read-write">).</para>
+      read-only (<xref linkend="cvs-read-only"/>), or read-write (<xref
+      linkend="cvs-read-write"/>).</para>
 
       <sect3 id="cvs-read-only">
        <title>Remote Read-only CVS Access</title>
          <listitem>
            <para>Set your <literal>$CVSROOT</literal> environment variable to
             <literal>:pserver:anoncvs@glass.cse.ogi.edu:/cvs</literal></para>
+           <para>If you set <literal>$CVSROOT</literal> in a shell script, be sure not to
+             have any trailing spaces on that line, otherwise CVS will respond with 
+             a perplexing message like
+             <programlisting>
+               /cvs : no such repository
+         </programlisting></para>
          </listitem>
          <listitem>
             <para>Run the command</para>
          </listitem>
 
          <listitem>
-           <para>Now go to <xref linkend="cvs-first">.</para>
+           <para>Now go to <xref linkend="cvs-first"/>.</para>
          </listitem>
        </orderedlist>
       </sect3>
 
 
        <para>
-       [Windows users.] The programs <command>ssh-keygen1</command>, <command>ssh1</command>, and <command>cvs</command>,
-       seem to lock up <command>bash</command> entirely if they try to get user input (e.g. if
-       they ask for a password).  To solve this, start up <filename>cmd.exe</filename> 
-       and run it as follows:
-       <Screen>
-       c:\tmp> set CYGWIN32=tty
-       c:\tmp> c:/user/local/bin/ssh-keygen1
-       </Screen> </para>
+       <emphasis>Windows users: see the notes in <xref linkend="configure-ssh"/> about <command>ssh</command> wrinkles!</emphasis>
+         </para>
+
 
-           <para>[Windows users.] To protect your
-            <literal>.ssh</literal> from access by anyone else,
-            right-click your <literal>.ssh</literal> directory, and
-            select <literal>Properties</literal>.  If you are not on
-            the access control list, add yourself, and give yourself
-            full permissions (the second panel).  Remove everyone else
-            from the access control list.  Don't leave them there but
-            deny them access, because 'they' may be a list that
-            includes you!</para>
-           <para>[March 2003] In fact <command>ssh</command> 3.6.1 now seems to <emphasis>require</emphasis>
-             you to have Unix permissions 600 (read/write for owner only) 
-             on the <literal>.ssh/identity</literal> file, else it 
-             bombs out.  For your local C drive, it seems that <literal>chmod 600 identity</literal> works,
-             but on Windows NT/XP, it doesn't work on a network drive (exact dteails obscure).  
-             The solution seems to be to set the CYGWIN environment
-             variable to "<literal>ntsec neta</literal>".  The CYGWIN environment variable is discussed
-             in <ulink url="http://cygwin.com/cygwin-ug-net/using-cygwinenv.html">the Cygwin User's Guide</ulink>,
-             and there are more details in <ulink url="http://cygwin.com/faq/faq_4.html#SEC44">the Cygwin FAQ</ulink>.
-             </para>
          </listitem>
 
          <listitem>
            <para>Send a message to to the CVS repository
             administrator (currently Jeff Lewis
-            <email>jeff@galconn.com</email>), containing:</para>
+            <email>jeff@galois.com</email>), containing:</para>
            <itemizedlist>
              <listitem>
                <para>Your desired user-name.</para>
 
          <listitem>
            <para>Set the following environment variables:</para>
-          <ItemizedList>
+          <itemizedlist>
           <listitem>
           <para>
           <constant>$HOME</constant>: points to your home directory.  This is where CVS
        </para>
        </listitem>
 
-       </ItemizedList>
+       </itemizedlist>
 
 
          </listitem>
          Put the following in <filename>$HOME/.cvsrc</filename>:
          </para>
          
-         <ProgramListing>
+         <programlisting>
          checkout -P
          release -d
          update -P
          diff -u
-         </ProgramListing>
+         </programlisting>
          
          <para>
          These are the default options for the specified CVS commands,
           some other junk. </para>
 
 <para>[Windows users.]  The following messages appear to be harmless:
-<Screen>
+<screen>
 setsockopt IPTOS_LOWDELAY: Invalid argument
 setsockopt IPTOS_THROUGHPUT: Invalid argument
-</Screen>
+</screen>
 </para>
 
 
@@ -455,7 +435,11 @@ setsockopt IPTOS_THROUGHPUT: Invalid argument
           you need at least the <literal>ghc</literal>,
           <literal>hslibs</literal> and <literal>libraries</literal>
           modules (for a full list of the projects available, see
-          <xref linkend="projects">).</para>
+          <xref linkend="projects"/>).</para>
+
+         <para>Remember that if you do not have
+          <literal>happy</literal> and/or <literal>Alex</literal>
+          installed, you need to check them out as well.</para>
        </listitem>
       </itemizedlist>
     </sect2>
@@ -491,7 +475,14 @@ $ cvs diff
           you the results.</para>
        </listitem>
 
-      <listitem>
+       <listitem>
+         <para>If you changed something in the 
+          <literal>fptools/libraries</literal> subdirectories, also run
+          <literal>make html</literal> to check if the documentation can
+          be generated successfully, too.</para>
+       </listitem>
+
+       <listitem>
          <para>Before checking in a change, you need to update your
           source tree:</para>
 
@@ -574,17 +565,25 @@ $ cvs commit -F <replaceable>commit-message</replaceable> <replaceable>directory
       major cause of headaches. </para>
 
       <para>So, to avoid a lot of hassle, follow this recipe for
-      updating your tree: </para>
+      updating your tree:</para>
 
 <screen>
 $ cd fptools
-$ cvs update -Pd 2&gt;&amp;1 | tee log</screen>
+$ cvs update -P 2&gt;&amp;1 | tee log</screen>
 
       <para>Look at the log file, and fix any conflicts (denoted by a
-      <quote>C</quote> in the first column). If you're using multiple
-      build trees, then for every build tree you have pointing at this
-      source tree, you need to update the links in case any new files
-      have appeared: </para>
+      <quote>C</quote> in the first column).  New directories may have
+      appeared in the repository; CVS doesn't check these out by
+      default, so to get new directories you have to explicitly do
+<screen>
+$ cvs update -d</screen>
+      in each project subdirectory.  Don't do this at the top level,
+      because then <emphasis>all</emphasis> the projects will be
+      checked out.</para>
+
+      <para>If you're using multiple build trees, then for every build
+      tree you have pointing at this source tree, you need to update
+      the links in case any new files have appeared: </para>
 
 <screen>
 $ cd <replaceable>build-tree</replaceable>
@@ -725,9 +724,23 @@ $ cvs checkout nofib/spectral
 
     <variablelist>
       <varlistentry>
-       <term><literal>ghc</literal></term>
-       <indexterm><primary><literal>ghc</literal></primary>
-       <secondary>project</secondary></indexterm>
+       <term>
+          <literal>alex</literal>
+          <indexterm><primary><literal>alex</literal></primary><secondary>project</secondary></indexterm>
+        </term>
+       <listitem>
+         <para>The <ulink
+         url="http://www.haskell.org/alex/">Alex</ulink> lexical
+         analyser generator for Haskell.</para>
+       </listitem>
+      </varlistentry>
+
+      <varlistentry>
+       <term>
+          <literal>ghc</literal>
+          <indexterm><primary><literal>ghc</literal></primary>
+          <secondary>project</secondary></indexterm>
+        </term>
        <listitem>
          <para>The <ulink url="http://www.haskell.org/ghc/">Glasgow
          Haskell Compiler</ulink> (minus libraries).  Absolutely
@@ -736,8 +749,10 @@ $ cvs checkout nofib/spectral
       </varlistentry>
 
       <varlistentry>
-       <term><literal>glafp-utils</literal></term>
-       <indexterm><primary><literal>glafp-utils</literal></primary><secondary>project</secondary></indexterm>
+       <term>
+          <literal>glafp-utils</literal>
+          <indexterm><primary><literal>glafp-utils</literal></primary><secondary>project</secondary></indexterm>
+        </term>
        <listitem>
          <para>Utility programs, some of which are used by the
          build/installation system.  Required for pretty much
@@ -746,19 +761,23 @@ $ cvs checkout nofib/spectral
       </varlistentry>
 
       <varlistentry>
-       <term><literal>green-card</literal></term>
-       <indexterm><primary><literal>green-card</literal></primary><secondary>project</secondary></indexterm>
+       <term>
+          <literal>greencard</literal>
+         <indexterm><primary><literal>greencard</literal></primary><secondary>project</secondary></indexterm>
+        </term>
        <listitem>
          <para>The <ulink
-         url="http://www.haskell.org/greencard/">Green Card</ulink>
+         url="http://www.haskell.org/greencard/">GreenCard</ulink>
          system for generating Haskell foreign function
          interfaces.</para>
        </listitem>
       </varlistentry>
 
       <varlistentry>
-       <term><literal>haggis</literal></term>
-       <indexterm><primary><literal>haggis</literal></primary><secondary>project</secondary></indexterm>
+       <term>
+          <literal>haggis</literal>
+         <indexterm><primary><literal>haggis</literal></primary><secondary>project</secondary></indexterm>
+        </term>
        <listitem>
          <para>The <ulink
          url="http://www.dcs.gla.ac.uk/fp/software/haggis/">Haggis</ulink>
@@ -767,8 +786,10 @@ $ cvs checkout nofib/spectral
       </varlistentry>
 
       <varlistentry>
-       <term><literal>haddock</literal></term>
-       <indexterm><primary><literal>haddock</literal></primary><secondary>project</secondary></indexterm>
+       <term>
+          <literal>haddock</literal>
+         <indexterm><primary><literal>haddock</literal></primary><secondary>project</secondary></indexterm>
+        </term>
        <listitem>
          <para>The <ulink
          url="http://www.haskell.org/haddock/">Haddock</ulink>
@@ -777,8 +798,10 @@ $ cvs checkout nofib/spectral
       </varlistentry>
 
       <varlistentry>
-       <term><literal>happy</literal></term>
-       <indexterm><primary><literal>happy</literal></primary><secondary>project</secondary></indexterm>
+       <term>
+          <literal>happy</literal>
+          <indexterm><primary><literal>happy</literal></primary><secondary>project</secondary></indexterm>
+        </term>
        <listitem>
          <para>The <ulink
          url="http://www.haskell.org/happy/">Happy</ulink> Parser
@@ -787,8 +810,10 @@ $ cvs checkout nofib/spectral
       </varlistentry>
 
       <varlistentry>
-       <term><literal>hdirect</literal></term>
-       <indexterm><primary><literal>hdirect</literal></primary><secondary>project</secondary></indexterm>
+       <term>
+          <literal>hdirect</literal>
+          <indexterm><primary><literal>hdirect</literal></primary><secondary>project</secondary></indexterm>
+        </term>
        <listitem>
          <para>The <ulink
          url="http://www.haskell.org/hdirect/">H/Direct</ulink>
@@ -797,8 +822,10 @@ $ cvs checkout nofib/spectral
       </varlistentry>
 
       <varlistentry>
-       <term><literal>hood</literal></term>
-       <indexterm><primary><literal>hood</literal></primary><secondary>project</secondary></indexterm>
+       <term>
+          <literal>hood</literal>
+          <indexterm><primary><literal>hood</literal></primary><secondary>project</secondary></indexterm>
+        </term>
        <listitem>
          <para>The <ulink url="http://www.haskell.org/hood/">Haskell
          Object Observation Debugger</ulink>.</para>
@@ -806,8 +833,10 @@ $ cvs checkout nofib/spectral
       </varlistentry>
 
       <varlistentry>
-       <term><literal>hslibs</literal></term>
-       <indexterm><primary><literal>hslibs</literal></primary><secondary>project</secondary></indexterm>
+       <term>
+          <literal>hslibs</literal>
+          <indexterm><primary><literal>hslibs</literal></primary><secondary>project</secondary></indexterm>
+        </term>
        <listitem>
          <para>Supplemental libraries for GHC
          (<emphasis>required</emphasis> for building GHC).</para>
@@ -815,8 +844,10 @@ $ cvs checkout nofib/spectral
       </varlistentry>
 
       <varlistentry>
-       <term><literal>libraries</literal></term>
-       <indexterm><primary><literal></literal></primary><secondary>project</secondary></indexterm>
+       <term>
+          <literal>libraries</literal>
+          <indexterm><primary><literal></literal></primary><secondary>project</secondary></indexterm>
+        </term>
        <listitem>
          <para>Hierarchical Haskell library suite
          (<emphasis>required</emphasis> for building GHC).</para>
@@ -824,16 +855,20 @@ $ cvs checkout nofib/spectral
       </varlistentry>
 
       <varlistentry>
-       <term><literal>mhms</literal></term>
-       <indexterm><primary><literal></literal></primary><secondary>project</secondary></indexterm>
+       <term>
+          <literal>mhms</literal>
+          <indexterm><primary><literal></literal></primary><secondary>project</secondary></indexterm>
+        </term>
        <listitem>
          <para>The Modular Haskell Metric System.</para>
        </listitem>
       </varlistentry>
 
       <varlistentry>
-       <term><literal>nofib</literal></term>
-       <indexterm><primary><literal>nofib</literal></primary><secondary>project</secondary></indexterm>
+       <term>
+          <literal>nofib</literal>
+          <indexterm><primary><literal>nofib</literal></primary><secondary>project</secondary></indexterm>
+        </term>
        <listitem>
          <para>The NoFib suite: A collection of Haskell programs used
          primarily for benchmarking.</para>
@@ -841,8 +876,10 @@ $ cvs checkout nofib/spectral
       </varlistentry>
 
       <varlistentry>
-       <term><literal>testsuite</literal></term>
-       <indexterm><primary><literal>testsuite</literal></primary><secondary>project</secondary></indexterm>
+       <term>
+          <literal>testsuite</literal>
+          <indexterm><primary><literal>testsuite</literal></primary><secondary>project</secondary></indexterm>
+        </term>
        <listitem>
          <para>A testing framework, including GHC's regression test
          suite.</para>
@@ -864,9 +901,8 @@ $ cvs checkout nofib/spectral
 
     <orderedlist>
 
-      <listitem>
-       <indexterm><primary>Disk space needed</primary></indexterm>
-       <para>Disk space needed: from about 100Mb for a basic GHC
+      <listitem><para><indexterm><primary>Disk space needed</primary></indexterm>Disk
+        space needed: from about 100Mb for a basic GHC
        build, up to probably 500Mb for a GHC build with everything
        included (libraries built several different ways,
        etc.).</para>
@@ -874,23 +910,23 @@ $ cvs checkout nofib/spectral
 
       <listitem>
        <para>Use an appropriate machine / operating system.  <xref
-       linkend="sec-port-info"> lists the supported platforms; if
+       linkend="sec-port-info"/> lists the supported platforms; if
        yours isn't amongst these then you can try porting GHC (see
-       <xref linkend="sec-porting-ghc">).</para>
+       <xref linkend="sec-porting-ghc"/>).</para>
       </listitem>
 
       <listitem>
        <para>Be sure that the &ldquo;pre-supposed&rdquo; utilities are
-        installed.  <Xref LinkEnd="sec-pre-supposed">
+        installed.  <xref linkend="sec-pre-supposed"/>
         elaborates.</para>
       </listitem>
 
       <listitem>
        <para>If you have any problem when building or installing the
-        Glasgow tools, please check the &ldquo;known pitfalls&rdquo; (<Xref
-        LinkEnd="sec-build-pitfalls">).  Also check the FAQ for the
+        Glasgow tools, please check the &ldquo;known pitfalls&rdquo; (<xref
+        linkend="sec-build-pitfalls"/>).  Also check the FAQ for the
         version you're building, which is part of the User's Guide and
-        available on the <ulink URL="http://www.haskell.org/ghc/" >GHC web
+        available on the <ulink url="http://www.haskell.org/ghc/" >GHC web
         site</ulink>.</para>
 
        <indexterm><primary>bugs</primary><secondary>known</secondary></indexterm>
@@ -966,13 +1002,13 @@ $ cvs checkout nofib/spectral
 
       <variablelist>
        <varlistentry>
-         <term>alpha-dec-{osf,linux,freebsd,openbsd,netbsd}:</term>
+         <term>alpha-dec-{osf,linux,freebsd,openbsd,netbsd}:
          <indexterm><primary>alpha-dec-osf</primary></indexterm>
          <indexterm><primary>alpha-dec-linux</primary></indexterm>
          <indexterm><primary>alpha-dec-freebsd</primary></indexterm>
          <indexterm><primary>alpha-dec-openbsd</primary></indexterm>
          <indexterm><primary>alpha-dec-netbsd</primary></indexterm>
-         
+          </term>
          <listitem>
            <para>The OSF port is currently working (as of GHC version
            5.02.1) and well supported.  The native code generator is
@@ -982,8 +1018,9 @@ $ cvs checkout nofib/spectral
        </varlistentry>
 
        <varlistentry>
-         <term>sparc-sun-sunos4</term>
-         <indexterm><primary>sparc-sun-sunos4</primary></indexterm>
+         <term>sparc-sun-sunos4
+           <indexterm><primary>sparc-sun-sunos4</primary></indexterm>
+          </term>
          <listitem>
            <para>Probably works with minor tweaks, hasn't been tested
            for a while.</para>
@@ -991,17 +1028,29 @@ $ cvs checkout nofib/spectral
        </varlistentry>
 
        <varlistentry>
-         <term>sparc-sun-solaris2</term>
-         <indexterm><primary>sparc-sun-solaris2</primary></indexterm>
+         <term>sparc-sun-solaris2
+            <indexterm><primary>sparc-sun-solaris2</primary></indexterm>
+          </term>
          <listitem>
-           <para>Fully supported (at least for Solaris 2.7),
+           <para>Fully supported (at least for Solaris 2.7 and 2.6),
            including native-code generator.</para>
          </listitem>
        </varlistentry>
 
        <varlistentry>
-         <term>hppa1.1-hp-hpux (HP-PA boxes running HPUX 9.x)</term>
-         <indexterm><primary>hppa1.1-hp-hpux</primary></indexterm>
+         <term>sparc-unknown-openbsd
+            <indexterm><primary>sparc-unknown-openbsd</primary></indexterm>
+          </term>
+         <listitem>
+           <para>Supported, including native-code generator. The
+           same should also be true of NetBSD</para>
+         </listitem>
+       </varlistentry>
+
+       <varlistentry>
+         <term>hppa1.1-hp-hpux (HP-PA boxes running HPUX 9.x)
+            <indexterm><primary>hppa1.1-hp-hpux</primary></indexterm>
+          </term>
          <listitem>
            <para>A registerised port is available for version 4.08,
            but GHC hasn't been built on that platform since (as far
@@ -1010,11 +1059,12 @@ $ cvs checkout nofib/spectral
        </varlistentry>
 
        <varlistentry>
-         <term>i386-unknown-linux (PCs running Linux, ELF binary format)</term>
-         <indexterm><primary>i386-*-linux</primary></indexterm>
+         <term>i386-unknown-linux (PCs running Linux, ELF binary format)
+            <indexterm><primary>i386-*-linux</primary></indexterm>
+          </term>
          <listitem>
            <para>GHC works registerised and has a native code
-            generator.  You <Emphasis>must</Emphasis> have GCC 2.7.x
+            generator.  You <emphasis>must</emphasis> have GCC 2.7.x
             or later.  NOTE about <literal>glibc</literal> versions:
             GHC binaries built on a system running <literal>glibc
             2.0</literal> won't work on a system running
@@ -1026,9 +1076,9 @@ $ cvs checkout nofib/spectral
        </varlistentry>
 
        <varlistentry>
-         <term>i386-unknown-freebsd (PCs running FreeBSD 2.2 or
-         higher)</term>
-         <indexterm><primary>i386-unknown-freebsd</primary></indexterm>
+         <term>i386-unknown-freebsd (PCs running FreeBSD 2.2 or higher)
+            <indexterm><primary>i386-unknown-freebsd</primary></indexterm>
+          </term>
          <listitem>
            <para>GHC works registerised.  Pre-built packages are
             available in the native package format, so if you just
@@ -1039,8 +1089,9 @@ $ cvs checkout nofib/spectral
        </varlistentry>
 
        <varlistentry>
-         <term>i386-unknown-openbsd (PCs running OpenBSD)</term>
-         <indexterm><primary>i386-unknown-openbsd</primary></indexterm> 
+         <term>i386-unknown-openbsd (PCs running OpenBSD)
+            <indexterm><primary>i386-unknown-openbsd</primary></indexterm> 
+          </term>
          <listitem>
            <para>Supported, with native code generator.  Packages are
            available through the ports system in the native package
@@ -1049,9 +1100,9 @@ $ cvs checkout nofib/spectral
        </varlistentry>
 
        <varlistentry>
-         <term>i386-unknown-netbsd (PCs running NetBSD and
-           OpenBSD)</term>
-           <indexterm><primary>i386-unknown-netbsd</primary></indexterm>
+         <term>i386-unknown-netbsd (PCs running NetBSD)
+            <indexterm><primary>i386-unknown-netbsd</primary></indexterm>
+          </term>
          <listitem>
            <para>Will require some minor porting effort, but should
            work registerised.</para>
@@ -1059,8 +1110,9 @@ $ cvs checkout nofib/spectral
        </varlistentry>
 
        <varlistentry>
-         <term>i386-unknown-mingw32 (PCs running Windows)</term>
-         <indexterm><primary>i386-unknown-mingw32</primary></indexterm>
+         <term>i386-unknown-mingw32 (PCs running Windows)
+            <indexterm><primary>i386-unknown-mingw32</primary></indexterm>
+          </term>
          <listitem>
            <para>Fully supported under Win9x, WinNT, Win2k, and
             WinXP.  Includes a native code generator.  Building from
@@ -1071,8 +1123,19 @@ $ cvs checkout nofib/spectral
        </varlistentry>
 
        <varlistentry>
-         <term>ia64-unknown-linux</term>
-         <indexterm><primary>ia64-unknown-linux</primary></indexterm>
+         <term>ia64-unknown-linux
+            <indexterm><primary>ia64-unknown-linux</primary></indexterm>
+          </term>
+         <listitem>
+           <para>Supported, except there is no native code
+           generator.</para>
+         </listitem>
+       </varlistentry>
+
+       <varlistentry>
+         <term>x86_64-unknown-linux
+            <indexterm><primary>x86_64-unknown-linux</primary></indexterm>
+          </term>
          <listitem>
            <para>GHC currently works unregisterised.  A registerised
            port is in progress.</para>
@@ -1080,8 +1143,20 @@ $ cvs checkout nofib/spectral
        </varlistentry>
 
        <varlistentry>
-         <term>mips-sgi-irix5</term>
-         <indexterm><primary>mips-sgi-irix[5-6]</primary></indexterm>
+         <term>amd64-unknown-openbsd
+            <indexterm><primary>amd64-unknown-linux</primary></indexterm>
+          </term>
+         <listitem>
+            <para>(This is the same as x86_64-unknown-openbsd). GHC
+                currently works unregisterised.  A registerised port is in
+                progress.</para>
+         </listitem>
+       </varlistentry>
+
+       <varlistentry>
+         <term>mips-sgi-irix5
+            <indexterm><primary>mips-sgi-irix[5-6]</primary></indexterm>
+          </term>
          <listitem>
            <para>Port has worked in the past, but hasn't been tested
             for some time (and will certainly have rotted in various
@@ -1092,8 +1167,18 @@ $ cvs checkout nofib/spectral
        </varlistentry>
 
        <varlistentry>
-         <term>powerpc-ibm-aix</term>
-         <indexterm><primary>powerpc-ibm-aix</primary></indexterm>
+         <term>mips64-sgi-irix6
+            <indexterm><primary>mips-sgi-irix6</primary></indexterm>
+          </term>
+         <listitem>
+           <para>GHC currently works unregisterised.</para>
+         </listitem>
+       </varlistentry>
+
+       <varlistentry>
+         <term>powerpc-ibm-aix
+            <indexterm><primary>powerpc-ibm-aix</primary></indexterm>
+          </term>
          <listitem>
            <para>Port currently doesn't work, needs some minimal
             porting effort.  As usual, we don't have access to
@@ -1103,17 +1188,19 @@ $ cvs checkout nofib/spectral
        </varlistentry>
 
        <varlistentry>
-         <term>powerpc-apple-darwin</term>
-         <indexterm><primary>powerpc-apple-darwin</primary></indexterm> 
+         <term>powerpc-apple-darwin
+            <indexterm><primary>powerpc-apple-darwin</primary></indexterm> 
+          </term>
          <listitem>
-           <para>Supported registerised.  No native code
-           generator.</para>
+           <para>Supported registerised.  Native code generator is
+           almost working.</para>
          </listitem>
        </varlistentry>
 
        <varlistentry>
-         <term>powerpc-apple-linux</term>
-         <indexterm><primary>powerpc-apple-linux</primary></indexterm> 
+         <term>powerpc-apple-linux
+            <indexterm><primary>powerpc-apple-linux</primary></indexterm> 
+          </term>
          <listitem>
            <para>Not supported (yet).</para>
          </listitem>
@@ -1152,14 +1239,15 @@ $ cvs checkout nofib/spectral
     <variablelist>
 
       <varlistentry>
-       <term>GHC</term>
-       <indexterm><primary>pre-supposed: GHC</primary></indexterm>
-       <indexterm><primary>GHC, pre-supposed</primary></indexterm>
+       <term>GHC
+          <indexterm><primary>pre-supposed: GHC</primary></indexterm>
+          <indexterm><primary>GHC, pre-supposed</primary></indexterm>
+        </term>
        <listitem>
          <para>GHC is required to build many of the tools, including
          GHC itself.  If you need to port GHC to your platform
          because there isn't a binary distribution of GHC available,
-         then see <xref linkend="sec-porting-ghc">.</para>
+         then see <xref linkend="sec-porting-ghc"/>.</para>
 
          <para>Which version of GHC you need will depend on the
          packages you intend to build.  GHC itself will normally
@@ -1169,9 +1257,10 @@ $ cvs checkout nofib/spectral
       </varlistentry>
 
       <varlistentry>
-       <term>Perl</term>
-       <indexterm><primary>pre-supposed: Perl</primary></indexterm>
-       <indexterm><primary>Perl, pre-supposed</primary></indexterm>
+       <term>Perl
+          <indexterm><primary>pre-supposed: Perl</primary></indexterm>
+          <indexterm><primary>Perl, pre-supposed</primary></indexterm>
+        </term>
        <listitem>
          <para><emphasis>You have to have Perl to proceed!</emphasis>
           Perl version 5 at least is required.  GHC has been known to
@@ -1193,10 +1282,10 @@ $ cvs checkout nofib/spectral
       </varlistentry>
 
       <varlistentry>
-       <term>GNU C (<command>gcc</command>)</term>
-       <indexterm><primary>pre-supposed: GCC (GNU C
-       compiler)</primary></indexterm> <indexterm><primary>GCC (GNU C
-       compiler), pre-supposed</primary></indexterm>
+       <term>GNU C (<command>gcc</command>)
+          <indexterm><primary>pre-supposed: GCC (GNU C compiler)</primary></indexterm>
+          <indexterm><primary>GCC (GNU C compiler), pre-supposed</primary></indexterm>
+        </term>
        <listitem>
          <para>We recommend using GCC version 2.95.2 on all
           platforms.  Failing that, version 2.7.2 is stable on most
@@ -1205,9 +1294,12 @@ $ cvs checkout nofib/spectral
           <command>egcs</command>) have varying degrees of stability
           depending on the platform.</para>
 
+         <para>GCC 3.2 is currently known to have problems building
+         GHC on Sparc, but is stable on x86.</para>
+         
          <para>If your GCC dies with &ldquo;internal error&rdquo; on
           some GHC source file, please let us know, so we can report
-          it and get things improved.  (Exception: on iX86
+          it and get things improved.  (Exception: on x86
           boxes&mdash;you may need to fiddle with GHC's
           <option>-monly-N-regs</option> option; see the User's
           Guide)</para>
@@ -1215,9 +1307,9 @@ $ cvs checkout nofib/spectral
       </varlistentry>
 
       <varlistentry>
-       <term>GNU Make</term>
-       <indexterm><primary>make</primary><secondary>GNU</secondary>
-       </indexterm>
+       <term>GNU Make
+          <indexterm><primary>make</primary><secondary>GNU</secondary></indexterm>
+        </term>
        <listitem>
          <para>The fptools build system makes heavy use of features
          specific to GNU <command>make</command>, so you must have
@@ -1227,8 +1319,9 @@ $ cvs checkout nofib/spectral
       </varlistentry>
 
       <varlistentry>
-       <term>Happy</term>
-       <indexterm><primary>Happy</primary></indexterm>
+       <term>Happy
+          <indexterm><primary>Happy</primary></indexterm>
+        </term>
        <listitem>
          <para>Happy is a parser generator tool for Haskell, and is
           used to generate GHC's parsers.  Happy is written in
@@ -1236,7 +1329,7 @@ $ cvs checkout nofib/spectral
           (<literal>fptools/happy</literal>).  It can be built from
           source, but bear in mind that you'll need GHC installed in
           order to build it.  To avoid the chicken/egg problem,
-          install a binary distribtion of either Happy or GHC to get
+          install a binary distribution of either Happy or GHC to get
           started.  Happy distributions are available from <ulink
           url="http://www.haskell.org/happy/">Happy's Web
           Page</ulink>.</para>
@@ -1244,26 +1337,47 @@ $ cvs checkout nofib/spectral
       </varlistentry>
 
       <varlistentry>
-       <term>Autoconf</term>
-       <indexterm><primary>pre-supposed: Autoconf</primary></indexterm>
-       <indexterm><primary>Autoconf, pre-supposed</primary></indexterm>
+       <term>Alex
+          <indexterm><primary>Alex</primary></indexterm>
+        </term>
        <listitem>
-         <para>GNU Autoconf is needed if you intend to build from the
+         <para>Alex is a lexical-analyser generator for Haskell,
+         which GHC uses to generate its lexer.  Like Happy, Alex is
+         written in Haskell and is a project in the CVS repository.
+         Alex distributions are available from <ulink
+         url="http://www.haskell.org/alex/">Alex's Web
+         Page</ulink>.</para>
+       </listitem>
+      </varlistentry>
+
+      <varlistentry>
+       <term>autoconf
+          <indexterm><primary>pre-supposed: autoconf</primary></indexterm>
+          <indexterm><primary>autoconf, pre-supposed</primary></indexterm>
+        </term>
+       <listitem>
+         <para>GNU autoconf is needed if you intend to build from the
           CVS sources, it is <emphasis>not</emphasis> needed if you
           just intend to build a standard source distribution.</para>
 
-         <para>Autoconf builds the <command>configure</command>
-          script from <filename>configure.in</filename> and
-          <filename>aclocal.m4</filename>.  If you modify either of
-          these files, you'll need <command>autoconf</command> to
-          rebuild <filename>configure</filename>.</para>
+         <para>Version 2.52 or later of the autoconf package is required.
+         NB. version 2.13 will no longer work, as of GHC version
+         6.1.</para>
+
+         <para><command>autoreconf</command> (from the autoconf package)
+          recursively builds <command>configure</command> scripts from
+          the corresponding <filename>configure.ac</filename> and
+          <filename>aclocal.m4</filename> files.  If you modify one of
+          the latter files, you'll need <command>autoreconf</command> to
+          rebuild the corresponding <filename>configure</filename>.</para>
        </listitem>
       </varlistentry>
 
       <varlistentry>
-       <term><command>sed</command></term>
-       <indexterm><primary>pre-supposed: sed</primary></indexterm>
-       <indexterm><primary>sed, pre-supposed</primary></indexterm>
+       <term><command>sed</command>
+          <indexterm><primary>pre-supposed: sed</primary></indexterm>
+          <indexterm><primary>sed, pre-supposed</primary></indexterm>
+        </term>
        <listitem>
          <para>You need a working <command>sed</command> if you are
           going to build from sources.  The build-configuration stuff
@@ -1287,13 +1401,14 @@ $ cvs checkout nofib/spectral
 
       <variablelist>
        <varlistentry>
-         <term>PVM version 3:</term>
+         <term>PVM version 3:
          <indexterm><primary>pre-supposed: PVM3 (Parallel Virtual Machine)</primary></indexterm>
-         <indexterm><primary>PVM3 (Parallel Virtual Machine), pre-supposed</primary></indexterm>
+            <indexterm><primary>PVM3 (Parallel Virtual Machine), pre-supposed</primary></indexterm>
+          </term>
          <listitem>
            <para>PVM is the Parallel Virtual Machine on which
             Parallel Haskell programs run.  (You only need this if you
-            plan to run Parallel Haskell.  Concurent Haskell, which
+            plan to run Parallel Haskell.  Concurrent Haskell, which
             runs concurrent threads on a uniprocessor doesn't need
             it.)  Underneath PVM, you can have (for example) a network
             of workstations (slow) or a multiprocessor box
@@ -1311,8 +1426,9 @@ $ cvs checkout nofib/spectral
        </varlistentry>
 
        <varlistentry>
-         <term><command>bash</command>:</term>
-         <indexterm><primary>bash, presupposed (Parallel Haskell only)</primary></indexterm>
+         <term><command>bash</command>:
+            <indexterm><primary>bash, presupposed (Parallel Haskell only)</primary></indexterm>
+          </term>
          <listitem>
            <para>Sadly, the <command>gr2ps</command> script, used to
             convert &ldquo;parallelism profiles&rdquo; to PostScript,
@@ -1328,9 +1444,10 @@ $ cvs checkout nofib/spectral
 
       <variablelist>
        <varlistentry>
-         <term>Flex</term>
-         <indexterm><primary>pre-supposed: flex</primary></indexterm> 
-         <indexterm><primary>flex, pre-supposed</primary></indexterm>
+         <term>Flex
+            <indexterm><primary>pre-supposed: flex</primary></indexterm> 
+            <indexterm><primary>flex, pre-supposed</primary></indexterm>
+          </term>
          <listitem>
            <para>This is a quite-a-bit-better-than-Lex lexer.  Used
             to build a couple of utilities in
@@ -1343,7 +1460,7 @@ $ cvs checkout nofib/spectral
 
       <para>More tools are required if you want to format the documentation
       that comes with GHC and other fptools projects.  See <xref
-      linkend="building-docs">.</para>
+      linkend="building-docs"/>.</para>
     </sect2>
   </sect1>
 
@@ -1376,7 +1493,8 @@ $ cvs checkout nofib/spectral
       want a completely standard build, then the following should
       work:</para>
 
-<screen>$ ./configure
+<screen>$ autoreconf
+$ ./configure
 $ make
 $ make install
 </screen>
@@ -1410,7 +1528,7 @@ $ make install
        </listitem>
 
        <listitem>
-         <para><filename>configure.in</filename>,
+         <para><filename>configure.ac</filename>,
           <filename>config.sub</filename>,
           <filename>config.guess</filename>: these files support the
           configuration process.</para>
@@ -1433,7 +1551,7 @@ $ make install
       only one project (<literal>happy</literal>, say), you must have
       a source tree whose root directory contains
       <filename>Makefile</filename>, <filename>mk/</filename>,
-      <filename>configure.in</filename>, and the project(s) you want
+      <filename>configure.ac</filename>, and the project(s) you want
       (<filename>happy/</filename> in this case).  You cannot get by
       with just the <filename>happy/</filename> directory.</para>
     </sect2>
@@ -1464,8 +1582,8 @@ $ make install
       are two (If you don't have either, the source distribution
       includes sources for the X11
       <command>lndir</command>&mdash;check out
-      <filename>fptools/glafp-utils/lndir</filename>). See <Xref
-      LinkEnd="sec-storysofar"> for a typical invocation.</para>
+      <filename>fptools/glafp-utils/lndir</filename>). See <xref
+      linkend="sec-storysofar"/> for a typical invocation.</para>
 
       <para>The build tree does not need to be anywhere near the
       source tree in the file system.  Indeed, one advantage of
@@ -1473,8 +1591,8 @@ $ make install
       can be placed in a non-backed-up partition, saving your systems
       support people from backing up untold megabytes of
       easily-regenerated, and rapidly-changing, gubbins.  The golden
-      rule is that (with a single exception&mdash;<XRef
-      LinkEnd="sec-build-config">) <emphasis>absolutely everything in
+      rule is that (with a single exception&mdash;<xref
+      linkend="sec-build-config"/>) <emphasis>absolutely everything in
       the build tree is either a symbolic link to the source tree, or
       else is mechanically generated</emphasis>.  It should be
       perfectly OK for your build tree to vanish overnight; an hour or
@@ -1509,7 +1627,7 @@ $ make install
       <constant>&dollar;(FPTOOLS&lowbar;TOP)</constant> unless
       otherwise stated.  For example, the file
       <filename>ghc/mk/target.mk</filename> is actually
-      <filename><constant>&dollar;(FPTOOLS&lowbar;TOP)</constant>/ghc/mk/target.mk</filename>.</para>
+      <filename>&dollar;(FPTOOLS&lowbar;TOP)/ghc/mk/target.mk</filename>.</para>
     </sect2>
 
     <sect2 id="sec-build-config">
@@ -1547,26 +1665,32 @@ $ make install
 
            <para>Change directory to
             <constant>&dollar;(FPTOOLS&lowbar;TOP)</constant> and
-            issue the command
-            <command>autoconf</command><indexterm><primary>autoconf</primary></indexterm>
-            (with no arguments). This GNU program converts
-            <filename><constant>&dollar;(FPTOOLS&lowbar;TOP)</constant>/configure.in</filename>
+            issue the command</para>
+<programlisting>
+autoreconf
+</programlisting>
+            <indexterm><primary>autoreconf</primary></indexterm>
+            <para>(with no arguments). This GNU program (recursively) converts
+            <filename>&dollar;(FPTOOLS&lowbar;TOP)/configure.ac</filename> and
+            <filename>&dollar;(FPTOOLS&lowbar;TOP)/aclocal.m4</filename>
             to a shell script called
-            <filename><constant>&dollar;(FPTOOLS&lowbar;TOP)</constant>/configure</filename>.
+            <filename>&dollar;(FPTOOLS&lowbar;TOP)/configure</filename>.
+             If <command>autoreconf</command> bleats that it can't write the file <filename>configure</filename>,
+             then delete the latter and try again.  Note that you must use <command>autoreconf</command>,
+             and not the old <command>autoconf</command>!  If you erroneously use the latter, you'll get 
+             a message like "No rule to make target 'mk/config.h.in'".
             </para>
 
-           <para>Some projects, including GHC, have their own
-            configure script.  If there's an
-            <constant>&dollar;(FPTOOLS&lowbar;TOP)/&lt;project&gt;/configure.in</constant>,
-            then you need to run <command>autoconf</command> in that
-            directory too.</para>
-
-           <para>Both these steps are completely
-            platform-independent; they just mean that the
-            human-written file (<filename>configure.in</filename>) can
-            be short, although the resulting shell script,
-            <command>configure</command>, and
-            <filename>mk/config.h.in</filename>, are long.</para>
+           <para>Some projects, including GHC, have their own configure script.
+            <command>autoreconf</command> takes care of that, too, so all you have
+             to do is calling <command>autoreconf</command> in the top-level directory
+            <filename>&dollar;(FPTOOLS&lowbar;TOP)</filename>.</para>
+
+           <para>These steps are completely platform-independent; they just mean
+            that the human-written files (<filename>configure.ac</filename> and
+            <filename>aclocal.m4</filename>) can be short, although the resulting
+            files (the <command>configure</command> shell scripts and the C header
+            template <filename>mk/config.h.in</filename>) are long.</para>
          </listitem>
        </varlistentry>
 
@@ -1576,15 +1700,15 @@ $ make install
            <para>Runs the newly-created <command>configure</command>
            script, thus:</para>
 
-<ProgramListing>
+<programlisting>
 ./configure <optional><parameter>args</parameter></optional>
-</ProgramListing>
+</programlisting>
 
            <para><command>configure</command>'s mission is to scurry
             round your computer working out what architecture it has,
             what operating system, whether it has the
-            <Function>vfork</Function> system call, where
-            <command>yacc</command> is kept, whether
+            <function>vfork</function> system call, where
+            <command>tar</command> is kept, whether
             <command>gcc</command> is available, where various obscure
             <literal>&num;include</literal> files are, whether it's a
             leap year, and what the systems manager had for lunch.  It
@@ -1628,9 +1752,9 @@ $ make install
 
            <variablelist>
              <varlistentry>
-               <term><literal>--with-ghc=<parameter>path</parameter></literal></term>
-               <indexterm><primary><literal>--with-ghc</literal></primary>
-               </indexterm>
+               <term><literal>--with-ghc=<parameter>path</parameter></literal>
+                  <indexterm><primary><literal>--with-ghc</literal></primary></indexterm>
+                </term>
                <listitem>
                  <para>Specifies the path to an installed GHC which
                  you would like to use.  This compiler will be used
@@ -1645,9 +1769,9 @@ $ make install
              </varlistentry>
              
              <varlistentry>
-               <term><literal>--with-hc=<parameter>path</parameter></literal></term>
-               <indexterm><primary><literal>--with-hc</literal></primary>
-               </indexterm>
+               <term><literal>--with-hc=<parameter>path</parameter></literal>
+                  <indexterm><primary><literal>--with-hc</literal></primary></indexterm>
+                </term>
                <listitem>
                  <para>Specifies the path to any installed Haskell
                  compiler.  This compiler will be used for compiling
@@ -1657,9 +1781,9 @@ $ make install
              </varlistentry>
              
              <varlistentry>
-               <term><literal>--with-gcc=<parameter>path</parameter></literal></term>
-               <indexterm><primary><literal>--with-gcc</literal></primary>
-               </indexterm>
+               <term><literal>--with-gcc=<parameter>path</parameter></literal>
+                  <indexterm><primary><literal>--with-gcc</literal></primary></indexterm>
+                </term>
                <listitem>
                  <para>Specifies the path to the installed GCC. This
                  compiler will be used to compile all C files,
@@ -1670,13 +1794,6 @@ $ make install
                </listitem>
              </varlistentry>
            </variablelist>
-           
-           <para><command>configure</command> caches the results of
-            its run in <filename>config.cache</filename>.  Quite often
-            you don't want that; you're running
-            <command>configure</command> a second time because
-            something has changed.  In that case, simply delete
-            <filename>config.cache</filename>.</para>
          </listitem>
        </varlistentry>
        
@@ -1721,12 +1838,15 @@ $ make install
       includes <filename>build.mk</filename> after
       <filename>config.mk</filename>.)</para>
 
+     <para>For your convenience, there's a file called <filename>build.mk.sample</filename>
+     that can serve as a starting point for your <filename>build.mk</filename>.</para>
+
       <para>For example, <filename>config.mk.in</filename> contains
       the definition:</para>
 
-<ProgramListing>
+<programlisting>
 GhcHcOpts=-O -Rghc-timing
-</ProgramListing>
+</programlisting>
 
       <para>The accompanying comment explains that this is the list of
       flags passed to GHC when building GHC itself.  For doing
@@ -1736,9 +1856,9 @@ GhcHcOpts=-O -Rghc-timing
       
       <para>or, if you prefer,</para>
 
-<ProgramListing>
+<programlisting>
 GhcHcOpts += -DDEBUG
-</ProgramListing>
+</programlisting>
 
       <para>GNU <command>make</command> allows existing definitions to
       have new text appended using the &ldquo;<literal>+=</literal>&rdquo;
@@ -1749,9 +1869,9 @@ GhcHcOpts += -DDEBUG
       lot quicker), you can just override
       <literal>GhcLibHcOpts</literal> altogether:</para>
 
-<ProgramListing>
+<programlisting>
 GhcHcOpts=-DDEBUG -Rghc-timing
-</ProgramListing>
+</programlisting>
 
       <para>When reading <filename>config.mk.in</filename>, remember
       that anything between &ldquo;@...@&rdquo; signs is going to be substituted
@@ -1760,19 +1880,19 @@ GhcHcOpts=-DDEBUG -Rghc-timing
       you want, but you need to be a bit surer what you are doing.
       For example, there's a line that says:</para>
 
-<ProgramListing>
-YACC = @YaccCmd@
-</ProgramListing>
+<programlisting>
+TAR = @TarCmd@
+</programlisting>
 
-      <para>This defines the Make variables <constant>YACC</constant>
-      to the pathname for a <command>yacc</command> that
+      <para>This defines the Make variables <constant>TAR</constant>
+      to the pathname for a <command>tar</command> that
       <command>configure</command> finds somewhere.  If you have your
-      own pet <command>yacc</command> you want to use instead, that's
+      own pet <command>tar</command> you want to use instead, that's
       fine. Just add this line to <filename>mk/build.mk</filename>:</para>
 
-<ProgramListing>
-YACC = myyacc
-</ProgramListing>
+<programlisting>
+TAR = mytar
+</programlisting>
 
       <para>You do not <emphasis>have</emphasis> to have a
       <filename>mk/build.mk</filename> file at all; if you don't,
@@ -1803,8 +1923,8 @@ YACC = myyacc
           or source distribution).  Say you call the root directory
           <filename>myfptools</filename> (it does not have to be
           called <filename>fptools</filename>).  Make sure that you
-          have the essential files (see <XRef
-          LinkEnd="sec-source-tree">).</para>
+          have the essential files (see <xref
+          linkend="sec-source-tree"/>).</para>
        </listitem>
 
        <listitem>
@@ -1838,21 +1958,13 @@ $ cd /scratch/joe-bloggs/myfptools-sun4
          <para>Prepare for system configuration:</para>
 
 <programlisting>
-$ autoconf
+$ autoreconf
 </programlisting>
 
          <para>(You can skip this step if you are starting from a
           source distribution, and you already have
           <filename>configure</filename> and
           <filename>mk/config.h.in</filename>.)</para>
-
-         <para>Some projects, including GHC itself, have their own
-         configure scripts, so it is necessary to run autoconf again
-         in the appropriate subdirectories. eg:</para>
-
-<programlisting>
-$ (cd ghc; autoconf)
-</programlisting>
        </listitem>
 
        <listitem>
@@ -2144,8 +2256,8 @@ $ emacs mk/build.mk
          <listitem>
            <para>is only available in the root directory
             <constant>&dollar;(FPTOOLS&lowbar;TOP)</constant>; it has
-            been discussed in <XRef
-            LinkEnd="sec-build-config">.</para>
+            been discussed in <xref
+            linkend="sec-build-config"/>.</para>
          </listitem>
        </varlistentry>
 
@@ -2161,9 +2273,9 @@ $ emacs mk/build.mk
             generated <filename>.depend</filename> file will contain
             the dependency:</para>
 
-<ProgramListing>
+<programlisting>
 Foo.o : Baz.hi
-</ProgramListing>
+</programlisting>
 
            <para>which says that the object file
             <filename>Foo.o</filename> depends on the interface file
@@ -2207,13 +2319,14 @@ Foo.o : Baz.hi
 
       <para> Do <emphasis>NOT</emphasis> use
       <filename>ghc/compiler/ghc</filename>, or
-      <filename>ghc/compiler/ghc-5.xx</filename>, as these are the
+      <filename>ghc/compiler/ghc-6.xx</filename>, as these are the
       scripts intended for installation, and contain hard-wired paths
       to the installed libraries, rather than the libraries in the
       build tree.</para>
 
       <para>Happy can similarly be run from the build tree, using
-      <filename>happy/src/happy-inplace</filename>.</para>
+      <filename>happy/src/happy-inplace</filename>, and similarly for
+      Alex and Haddock.</para>
     </sect2>
 
     <sect2>
@@ -2229,9 +2342,9 @@ Foo.o : Baz.hi
       <command>make</command> is going to rebuild everything anyway,
       the following hack may be useful:</para>
 
-<ProgramListing>
+<programlisting>
 gmake FAST=YES 
-</ProgramListing>
+</programlisting>
 
       <para>This tells the make system to ignore dependencies and just
       build what you tell it to.  In other words, it's equivalent to
@@ -2300,7 +2413,7 @@ gmake FAST=YES
 
 <indexterm><primary>Makefile, minimal</primary></indexterm>
 
-<ProgramListing>
+<programlisting>
 #     Makefile for fptools project "small"
 
 TOP = ..
@@ -2310,7 +2423,7 @@ SRCS = $(wildcard *.lhs) $(wildcard *.c)
 HS_PROG = small
 
 include $(TOP)/target.mk
-</ProgramListing>
+</programlisting>
 
       <para>this <filename>Makefile</filename> has three
       sections:</para>
@@ -2329,11 +2442,11 @@ directive.
 
           a file of &ldquo;boilerplate&rdquo; code from the level
           above (which in this case will be
-          <filename><constant>FPTOOLS&lowbar;TOP</constant>/mk/boilerplate.mk</filename><indexterm><primary>boilerplate.mk</primary></indexterm>).
+          <filename>FPTOOLS&lowbar;TOP/mk/boilerplate.mk</filename><indexterm><primary>boilerplate.mk</primary></indexterm>).
           As its name suggests, <filename>boilerplate.mk</filename>
           consists of a large quantity of standard
           <filename>Makefile</filename> code.  We discuss this
-          boilerplate in more detail in <XRef LinkEnd="sec-boiler">.
+          boilerplate in more detail in <xref linkend="sec-boiler"/>.
           <indexterm><primary>include, directive in
           Makefiles</primary></indexterm> <indexterm><primary>Makefile
           inclusion</primary></indexterm></para>
@@ -2345,9 +2458,9 @@ directive.
           directory in which the <filename>boilerplate.mk</filename>
           file is.  It is <emphasis>not</emphasis> OK to simply say</para>
 
-<ProgramListing>
+<programlisting>
 include ../mk/boilerplate.mk  # NO NO NO
-</ProgramListing>
+</programlisting>
 
 
           <para>Why?  Because the <filename>boilerplate.mk</filename>
@@ -2360,7 +2473,7 @@ include ../mk/boilerplate.mk  # NO NO NO
           <literal>include</literal>d sits.)  In general,
           <emphasis>every file <filename>foo.mk</filename> assumes
           that
-          <filename><constant>&dollar;(TOP)</constant>/mk/foo.mk</filename>
+          <filename>&dollar;(TOP)/mk/foo.mk</filename>
           refers to itself.</emphasis> It is up to the
           <filename>Makefile</filename> doing the
           <literal>include</literal> to ensure this is the case.</para>
@@ -2385,8 +2498,8 @@ include ../mk/boilerplate.mk  # NO NO NO
           <constant>HS&lowbar;PROG</constant><indexterm><primary>HS&lowbar;PROG</primary></indexterm>
           (the executable binary to be built).  We will discuss in
           more detail what the &ldquo;standard variables&rdquo; are,
-          and how they affect what happens, in <XRef
-          LinkEnd="sec-targets">.</para>
+          and how they affect what happens, in <xref
+          linkend="sec-targets"/>.</para>
 
          <para>The definition for <constant>SRCS</constant> uses the
           useful GNU <command>make</command> construct
@@ -2405,12 +2518,12 @@ include ../mk/boilerplate.mk  # NO NO NO
           code, called
           <filename>target.mk</filename><indexterm><primary>target.mk</primary></indexterm>.
           It contains the rules that tell <command>gmake</command> how
-          to make the standard targets (<Xref
-          LinkEnd="sec-standard-targets">).  Why, you ask, can't this
+          to make the standard targets (<xref
+          linkend="sec-standard-targets"/>).  Why, you ask, can't this
           standard code be part of
           <filename>boilerplate.mk</filename>?  Good question.  We
-          discuss the reason later, in <Xref
-          LinkEnd="sec-boiler-arch">.</para>
+          discuss the reason later, in <xref
+          linkend="sec-boiler-arch"/>.</para>
 
           <para>You do not <emphasis>have</emphasis> to
           <literal>include</literal> the
@@ -2419,8 +2532,8 @@ include ../mk/boilerplate.mk  # NO NO NO
           though, you will find quite a big payoff from using the
           canned rules in <filename>target.mk</filename>; the price
           tag is that you have to understand what canned rules get
-          enabled, and what they do (<Xref
-          LinkEnd="sec-targets">).</para>
+          enabled, and what they do (<xref
+          linkend="sec-targets"/>).</para>
        </listitem>
       </orderedlist>
 
@@ -2476,7 +2589,7 @@ include ../mk/boilerplate.mk  # NO NO NO
       rare.)  To give you the idea, here's part of the directory
       structure for the (rather large) GHC project:</para>
 
-<Screen>
+<screen>
 $(FPTOOLS_TOP)/ghc/
   Makefile
   mk/
@@ -2493,14 +2606,14 @@ $(FPTOOLS_TOP)/ghc/
     parser/...source files for parser...
     renamer/...source files for renamer...
     ...etc...
-</Screen>
+</screen>
 
       <para>The sub-directories <filename>docs</filename>,
       <filename>driver</filename>, <filename>compiler</filename>, and
       so on, each contains a sub-component of GHC, and each has its
       own <filename>Makefile</filename>.  There must also be a
       <filename>Makefile</filename> in
-      <filename><constant>&dollar;(FPTOOLS&lowbar;TOP)</constant>/ghc</filename>.
+      <filename>&dollar;(FPTOOLS&lowbar;TOP)/ghc</filename>.
       It does most of its work by recursively invoking
       <command>gmake</command> on the <filename>Makefile</filename>s
       in the sub-directories.  We say that
@@ -2602,9 +2715,9 @@ $(FPTOOLS_TOP)/ghc/
           <emphasis>augment</emphasis> them. For example, a
           <filename>Makefile</filename> might say:</para>
 
-<ProgramListing>
+<programlisting>
 SRC_HC_OPTS += -O
-</ProgramListing>
+</programlisting>
 
          <para>thereby adding &ldquo;<option>-O</option>&rdquo; to
          the end of
@@ -2614,7 +2727,7 @@ SRC_HC_OPTS += -O
        <listitem>
          <para><filename>target.mk</filename> contains
           <command>make</command> rules for the standard targets
-          described in <Xref LinkEnd="sec-standard-targets">.  These
+          described in <xref linkend="sec-standard-targets"/>.  These
           rules are selectively included, depending on the setting of
           certain <command>make</command> variables.  These variables
           are usually set in the middle section of the
@@ -2631,13 +2744,13 @@ SRC_HC_OPTS += -O
 
              <para><command>gmake</command> commits target and
               dependency lists earlier than it should.  For example,
-              <FIlename>target.mk</FIlename> has a rule that looks
+              <filename>target.mk</filename> has a rule that looks
               like this:</para>
 
-<ProgramListing>
+<programlisting>
 $(HS_PROG) : $(OBJS)
       $(HC) $(LD_OPTS) $&#60; -o $@
-</ProgramListing>
+</programlisting>
 
              <para>If this rule was in
               <filename>boilerplate.mk</filename> then
@@ -2678,23 +2791,25 @@ $(HS_PROG) : $(OBJS)
       <indexterm><primary>boilerplate.mk</primary></indexterm>
 
       <para>If you look at
-      <filename><constant>&dollar;(FPTOOLS&lowbar;TOP)</constant>/mk/boilerplate.mk</filename>
+      <filename>&dollar;(FPTOOLS&lowbar;TOP)/mk/boilerplate.mk</filename>
       you will find that it consists of the following sections, each
       held in a separate file:</para>
 
       <variablelist>
        <varlistentry>
-         <term><filename>config.mk</filename></term>
-         <indexterm><primary>config.mk</primary></indexterm>
+         <term><filename>config.mk</filename>
+            <indexterm><primary>config.mk</primary></indexterm>
+          </term>
          <listitem>
            <para>is the build configuration file we discussed at
-            length in <Xref LinkEnd="sec-build-config">.</para>
+            length in <xref linkend="sec-build-config"/>.</para>
          </listitem>
        </varlistentry>
 
        <varlistentry>
-         <term><filename>paths.mk</filename></term>
-         <indexterm><primary>paths.mk</primary></indexterm>
+         <term><filename>paths.mk</filename>
+            <indexterm><primary>paths.mk</primary></indexterm>
+          </term>
          <listitem>
            <para>defines <command>make</command> variables for
             pathnames and file lists.  This file contains code for
@@ -2710,9 +2825,9 @@ $(HS_PROG) : $(OBJS)
 
            <variablelist>
              <varlistentry>
-               <term><literal>ALL_DIRS</literal></term>
-               <indexterm><primary><literal>ALL_DIRS</literal></primary>
-               </indexterm>
+               <term><literal>ALL_DIRS</literal>
+                  <indexterm><primary><literal>ALL_DIRS</literal></primary></indexterm>
+                </term>
                <listitem>
                  <para>Set to a list of directories to search in
                  addition to the current directory for source
@@ -2721,9 +2836,9 @@ $(HS_PROG) : $(OBJS)
              </varlistentry>
 
              <varlistentry>
-               <term><literal>EXCLUDE_SRCS</literal></term>
-               <indexterm><primary><literal>EXCLUDE_SRCS</literal></primary>
-               </indexterm>
+               <term><literal>EXCLUDE_SRCS</literal>
+                  <indexterm><primary><literal>EXCLUDE_SRCS</literal></primary></indexterm>
+                </term>
                <listitem>
                  <para>Set to a list of source files (relative to the
                  current directory) to omit from the automatic
@@ -2739,9 +2854,9 @@ $(HS_PROG) : $(OBJS)
              </varlistentry>
 
              <varlistentry>
-               <term><literal>EXTRA_SRCS</literal></term>
-               <indexterm><primary><literal>EXCLUDE_SRCS</literal></primary>
-               </indexterm>
+               <term><literal>EXTRA_SRCS</literal>
+                  <indexterm><primary><literal>EXCLUDE_SRCS</literal></primary></indexterm>
+                </term>
                  <listitem>
                  <para>Set to a list of extra source files (perhaps
                  in directories not listed in
@@ -2756,8 +2871,9 @@ $(HS_PROG) : $(OBJS)
 
            <variablelist>
              <varlistentry>
-               <term><literal>SRCS</literal></term>
-               <indexterm><primary><literal>SRCS</literal></primary></indexterm>
+               <term><literal>SRCS</literal>
+                  <indexterm><primary><literal>SRCS</literal></primary></indexterm>
+                </term>
                <listitem>
                  <para>All source files found, sorted and without
                  duplicates, including those which might not exist
@@ -2769,8 +2885,9 @@ $(HS_PROG) : $(OBJS)
              </varlistentry>
 
              <varlistentry>
-               <term><literal>HS_SRCS</literal></term>
-               <indexterm><primary><literal>HS_SRCS</literal></primary></indexterm>
+               <term><literal>HS_SRCS</literal>
+                  <indexterm><primary><literal>HS_SRCS</literal></primary></indexterm>
+                </term>
                <listitem>
                  <para>all Haskell source files in the current
                   directory, including those derived from other source
@@ -2780,8 +2897,9 @@ $(HS_PROG) : $(OBJS)
              </varlistentry>
 
              <varlistentry>
-               <term><literal>HS_OBJS</literal></term>
-               <indexterm><primary><literal>HS_OBJS</literal></primary></indexterm>
+               <term><literal>HS_OBJS</literal>
+                  <indexterm><primary><literal>HS_OBJS</literal></primary></indexterm>
+                </term>
                <listitem>
                  <para>Object files derived from
                  <literal>HS_SRCS</literal>.</para>
@@ -2789,8 +2907,9 @@ $(HS_PROG) : $(OBJS)
              </varlistentry>
 
              <varlistentry>
-               <term><literal>HS_IFACES</literal></term>
-               <indexterm><primary><literal>HS_IFACES</literal></primary></indexterm>
+               <term><literal>HS_IFACES</literal>
+                  <indexterm><primary><literal>HS_IFACES</literal></primary></indexterm>
+                </term>
                <listitem>
                  <para>Interface files (<literal>.hi</literal> files)
                  derived from <literal>HS_SRCS</literal>.</para>
@@ -2798,16 +2917,18 @@ $(HS_PROG) : $(OBJS)
              </varlistentry>
 
              <varlistentry>
-               <term><literal>C_SRCS</literal></term>
+               <term><literal>C_SRCS</literal>
                <indexterm><primary><literal>C_SRCS</literal></primary></indexterm>
+                </term>
                <listitem>
                  <para>All C source files found.</para>
                </listitem>
              </varlistentry>
 
              <varlistentry>
-               <term><literal>C_OBJS</literal></term>
+               <term><literal>C_OBJS</literal>
                <indexterm><primary><literal>C_OBJS</literal></primary></indexterm>
+                </term>
                <listitem>
                  <para>Object files derived from
                  <literal>C_SRCS</literal>.</para>
@@ -2815,8 +2936,9 @@ $(HS_PROG) : $(OBJS)
              </varlistentry>
 
              <varlistentry>
-               <term><literal>SCRIPT_SRCS</literal></term>
+               <term><literal>SCRIPT_SRCS</literal>
                <indexterm><primary><literal>SCRIPT_SRCS</literal></primary></indexterm>
+                </term>
                <listitem>
                  <para>All script source files found
                  (<literal>.lprl</literal> files).</para>
@@ -2824,8 +2946,9 @@ $(HS_PROG) : $(OBJS)
              </varlistentry>
 
              <varlistentry>
-               <term><literal>SCRIPT_OBJS</literal></term>
+               <term><literal>SCRIPT_OBJS</literal>
                <indexterm><primary><literal>SCRIPT_OBJS</literal></primary></indexterm>
+                </term>
                <listitem>
                  <para><quote>object</quote> files derived from
                  <literal>SCRIPT_SRCS</literal>
@@ -2834,8 +2957,9 @@ $(HS_PROG) : $(OBJS)
              </varlistentry>
 
              <varlistentry>
-               <term><literal>HSC_SRCS</literal></term>
+               <term><literal>HSC_SRCS</literal>
                <indexterm><primary><literal>HSC_SRCS</literal></primary></indexterm>
+                </term>
                <listitem>
                  <para>All <literal>hsc2hs</literal> source files
                  (<literal>.hsc</literal> files).</para>
@@ -2843,8 +2967,9 @@ $(HS_PROG) : $(OBJS)
              </varlistentry>
 
              <varlistentry>
-               <term><literal>HAPPY_SRCS</literal></term>
+               <term><literal>HAPPY_SRCS</literal>
                <indexterm><primary><literal>HAPPY_SRCS</literal></primary></indexterm>
+                </term>
                <listitem>
                  <para>All <literal>happy</literal> source files
                  (<literal>.y</literal> or <literal>.hy</literal> files).</para>
@@ -2852,8 +2977,9 @@ $(HS_PROG) : $(OBJS)
              </varlistentry>
 
              <varlistentry>
-               <term><literal>OBJS</literal></term>
+               <term><literal>OBJS</literal>
                <indexterm><primary>OBJS</primary></indexterm>
+                </term>
                <listitem>
                  <para>the concatenation of
                  <literal>&dollar;(HS_OBJS)</literal>,
@@ -2879,23 +3005,25 @@ $(HS_PROG) : $(OBJS)
        </varlistentry>
 
        <varlistentry>
-         <term><filename>opts.mk</filename></term>
-         <indexterm><primary>opts.mk</primary></indexterm>
+         <term><filename>opts.mk</filename>
+            <indexterm><primary>opts.mk</primary></indexterm>
+          </term>
          <listitem>
            <para>defines <command>make</command> variables for option
             strings to pass to each program. For example, it defines
             <constant>HC&lowbar;OPTS</constant><indexterm><primary>HC&lowbar;OPTS</primary></indexterm>,
             the option strings to pass to the Haskell compiler.  See
-            <Xref LinkEnd="sec-suffix">.</para>
+            <xref linkend="sec-suffix"/>.</para>
          </listitem>
        </varlistentry>
 
        <varlistentry>
-         <term><filename>suffix.mk</filename></term>
-         <indexterm><primary>suffix.mk</primary></indexterm>
+         <term><filename>suffix.mk</filename>
+            <indexterm><primary>suffix.mk</primary></indexterm>
+          </term>
          <listitem>
-           <para>defines standard pattern rules&mdash;see <Xref
-           LinkEnd="sec-suffix">.</para>
+           <para>defines standard pattern rules&mdash;see <xref
+           linkend="sec-suffix"/>.</para>
          </listitem>
        </varlistentry>
       </variablelist>
@@ -2924,11 +3052,11 @@ $(HS_PROG) : $(OBJS)
 
       <para>Almost all the rules look something like this:</para>
 
-<ProgramListing>
+<programlisting>
 %.o : %.c
       $(RM) $@
       $(CC) $(CC_OPTS) -c $&#60; -o $@
-</ProgramListing>
+</programlisting>
 
       <para>Here's how to understand the rule.  It says that
       <emphasis>something</emphasis><filename>.o</filename> (say
@@ -2956,9 +3084,10 @@ $(HS_PROG) : $(OBJS)
       defined in <filename>mk/opts.mk</filename>.  Almost all of them
       are defined like this:</para>
 
-<ProgramListing>
-CC_OPTS = $(SRC_CC_OPTS) $(WAY$(_way)_CC_OPTS) $($*_CC_OPTS) $(EXTRA_CC_OPTS)
-</ProgramListing>
+<programlisting>
+CC_OPTS = \
+  $(SRC_CC_OPTS) $(WAY$(_way)_CC_OPTS) $($*_CC_OPTS) $(EXTRA_CC_OPTS)
+</programlisting>
 
       <para>The four variables from which
        <constant>CC&lowbar;OPTS</constant> is built have the following
@@ -2982,7 +3111,7 @@ CC_OPTS = $(SRC_CC_OPTS) $(WAY$(_way)_CC_OPTS) $($*_CC_OPTS) $(EXTRA_CC_OPTS)
             <literal>mp</literal>.  The variable
             <constant>WAY&lowbar;CC&lowbar;OPTS</constant> holds
             options to pass to the C compiler when compiling the
-            standard way.  (<Xref LinkEnd="sec-ways"> dicusses
+            standard way.  (<xref linkend="sec-ways"/> dicusses
             multi-way compilation.)</para>
          </listitem>
        </varlistentry>
@@ -3004,9 +3133,9 @@ CC_OPTS = $(SRC_CC_OPTS) $(WAY$(_way)_CC_OPTS) $($*_CC_OPTS) $(EXTRA_CC_OPTS)
            <para>extra options to pass to all C compilations.  This
             is intended for command line use, thus:</para>
 
-<ProgramListing>
+<programlisting>
 gmake libHS.a EXTRA_CC_OPTS="-v"
-</ProgramListing>
+</programlisting>
          </listitem>
        </varlistentry>
       </variablelist>
@@ -3017,8 +3146,8 @@ gmake libHS.a EXTRA_CC_OPTS="-v"
       <indexterm><primary>target.mk</primary></indexterm>
 
       <para><filename>target.mk</filename> contains canned rules for
-      all the standard targets described in <Xref
-      LinkEnd="sec-standard-targets">.  It is complicated by the fact
+      all the standard targets described in <xref
+      linkend="sec-standard-targets"/>.  It is complicated by the fact
       that you don't want all of these rules to be active in every
       <filename>Makefile</filename>.  Rather than have a plethora of
       tiny files which you can include selectively, there is a single
@@ -3112,10 +3241,10 @@ gmake libHS.a EXTRA_CC_OPTS="-v"
       <para>All of these rules are &ldquo;double-colon&rdquo; rules,
       thus</para>
 
-<ProgramListing>
+<programlisting>
 install :: $(HS_PROG)
       ...how to install it...
-</ProgramListing>
+</programlisting>
 
       <para>GNU <command>make</command> treats double-colon rules as
       separate entities.  If there are several double-colon rules for
@@ -3146,7 +3275,7 @@ install :: $(HS_PROG)
 
       <para>When <constant>SUBDIRS</constant> is defined,
       <filename>target.mk</filename> includes a rather neat rule for
-      the standard targets (<Xref LinkEnd="sec-standard-targets"> that
+      the standard targets (<xref linkend="sec-standard-targets"/> that
       simply invokes <command>make</command> recursively in each of
       the sub-directories.</para>
 
@@ -3235,8 +3364,8 @@ install :: $(HS_PROG)
           <filename>Makefile</filename> to the list of way tags you
           want these targets built for.  The mechanism here is very
           much like the recursive invocation of
-          <command>make</command> in sub-directories (<Xref
-          LinkEnd="sec-subdirs">).  It is up to you to set
+          <command>make</command> in sub-directories (<xref
+          linkend="sec-subdirs"/>).  It is up to you to set
           <constant>WAYS</constant> in your
           <filename>Makefile</filename>; this is how you control what
           ways will get built.</para>
@@ -3256,10 +3385,10 @@ install :: $(HS_PROG)
           file will match</emphasis>.  The key pattern rules (in
           <filename>suffix.mk</filename>) look like this:
 
-<ProgramListing>
+<programlisting>
 %.$(way_)o : %.lhs
       $(HC) $(HC_OPTS) $&#60; -o $@
-</ProgramListing>
+</programlisting>
 
           Neat, eh?</para>
        </listitem>
@@ -3307,9 +3436,10 @@ $ make way=p
       
       <variablelist>
        <varlistentry>
-         <term>DocBook</term>
-         <indexterm><primary>pre-supposed: DocBook</primary></indexterm>
-         <indexterm><primary>DocBook, pre-supposed</primary></indexterm>
+         <term>DocBook
+            <indexterm><primary>pre-supposed: DocBook</primary></indexterm>
+            <indexterm><primary>DocBook, pre-supposed</primary></indexterm>
+          </term>
          <listitem>
            <para>Much of our documentation is written in SGML, using
             the DocBook DTD.  Instructions on installing and
@@ -3318,9 +3448,10 @@ $ make way=p
        </varlistentry>
 
        <varlistentry>
-         <term>TeX</term>
-         <indexterm><primary>pre-supposed: TeX</primary></indexterm>
-         <indexterm><primary>TeX, pre-supposed</primary></indexterm>
+         <term>TeX
+            <indexterm><primary>pre-supposed: TeX</primary></indexterm>
+            <indexterm><primary>TeX, pre-supposed</primary></indexterm>
+          </term>
          <listitem>
            <para>A decent TeX distribution is required if you want to
             produce printable documentation.  We recomment teTeX,
@@ -3329,9 +3460,9 @@ $ make way=p
        </varlistentry>
 
        <varlistentry>
-         <term>Haddock</term>
-         <indexterm><primary>Haddock</primary>
-         </indexterm>
+         <term>Haddock
+            <indexterm><primary>Haddock</primary></indexterm>
+          </term>
          <listitem>
            <para>Haddock is a Haskell documentation tool that we use
            for automatically generating documentation from the
@@ -3358,21 +3489,21 @@ $ make way=p
 
        <para>If you don't have DocBook tools installed, and you are
         using a system that can handle RedHat RPM packages, you can
-        probably use the <ULink
-        URL="http://sourceware.cygnus.com/docbook-tools/">Cygnus
-        DocBook tools</ULink>, which is the most shrink-wrapped SGML
+        probably use the <ulink
+        url="http://sourceware.cygnus.com/docbook-tools/">Cygnus
+        DocBook tools</ulink>, which is the most shrink-wrapped SGML
         suite that we could find. You need all the RPMs except for
-        psgml (i.e.  <Filename>docbook</Filename>,
-        <Filename>jade</Filename>, <Filename>jadetex</Filename>,
-        <Filename>sgmlcommon</Filename> and
-        <Filename>stylesheets</Filename>). Note that most of these
+        psgml (i.e.  <filename>docbook</filename>,
+        <filename>jade</filename>, <filename>jadetex</filename>,
+        <filename>sgmlcommon</filename> and
+        <filename>stylesheets</filename>). Note that most of these
         RPMs are architecture neutral, so are likely to be found in a
-        <Filename>noarch</Filename> directory. The SuSE RPMs also
-        work; the RedHat ones <Emphasis>don't</Emphasis> in RedHat 6.2
+        <filename>noarch</filename> directory. The SuSE RPMs also
+        work; the RedHat ones <emphasis>don't</emphasis> in RedHat 6.2
         (7.0 and later should be OK), but they are easy to fix: just
         make a symlink from
-        <Filename>/usr/lib/sgml/stylesheets/nwalsh-modular/lib/dblib.dsl</Filename>
-        to <Filename>/usr/lib/sgml/lib/dblib.dsl</Filename>. </para>
+        <filename>/usr/lib/sgml/stylesheets/nwalsh-modular/lib/dblib.dsl</filename>
+        to <filename>/usr/lib/sgml/lib/dblib.dsl</filename>. </para>
       </sect3>
     
       <sect3>
@@ -3396,17 +3527,17 @@ $ make way=p
       <sect3>
        <title>Installing from binaries on Windows</title>
        
-       <Para>It's a good idea to use Norman Walsh's <ULink
-        URL="http://nwalsh.com/docbook/dsssl/doc/install.html">installation
-        notes</ULink> as a guide. You should get version 3.1 of
-        DocBook, and note that his file <Filename>test.sgm</Filename>
+       <para>It's a good idea to use Norman Walsh's <ulink
+        url="http://nwalsh.com/docbook/dsssl/doc/install.html">installation
+        notes</ulink> as a guide. You should get version 3.1 of
+        DocBook, and note that his file <filename>test.sgm</filename>
         won't work, as it needs version 3.0. You should unpack Jade
-        into <Filename>\Jade</Filename>, along with the entities,
-        DocBook into <Filename>\docbook</Filename>, and the DocBook
-        stylesheets into <Filename>\docbook\stylesheets</Filename> (so
+        into <filename>\Jade</filename>, along with the entities,
+        DocBook into <filename>\docbook</filename>, and the DocBook
+        stylesheets into <filename>\docbook\stylesheets</filename> (so
         they actually end up in
-        <Filename>\docbook\stylesheets\docbook</Filename>).</para>
-      </Sect3>
+        <filename>\docbook\stylesheets\docbook</filename>).</para>
+      </sect3>
 
 
       <sect3>
@@ -3415,58 +3546,58 @@ $ make way=p
        <sect4>
          <title>Jade</title>
 
-         <para>Install <ULink
-          URL="http://openjade.sourceforge.net/">OpenJade</ULink>
+         <para>Install <ulink
+          url="http://openjade.sourceforge.net/">OpenJade</ulink>
           (Windows binaries are available as well as sources). If you
           want DVI, PS, or PDF then install JadeTeX from the
-          <Filename>dsssl</Filename> subdirectory. (If you get the
+          <filename>dsssl</filename> subdirectory. (If you get the
           error:
 
 <screen>
 ! LaTeX Error: Unknown option implicit=false' for package hyperref'.
 </screen>
 
-          your version of <Command>hyperref</Command> is out of date;
+          your version of <command>hyperref</command> is out of date;
           download it from CTAN
-          (<Filename>macros/latex/contrib/supported/hyperref</Filename>),
+          (<filename>macros/latex/contrib/supported/hyperref</filename>),
           and make it, ensuring that you have first removed or renamed
           your old copy. If you start getting file not found errors
-          when making the test for <Command>hyperref</Command>, you
+          when making the test for <command>hyperref</command>, you
           can abort at that point and proceed straight to
-          <Command>make install</Command>, or enter them as
-          <Filename>../</Filename><Emphasis>filename</Emphasis>.)</para>
+          <command>make install</command>, or enter them as
+          <filename>../</filename><emphasis>filename</emphasis>.)</para>
 
-         <para>Make links from <Filename>virtex</Filename> to
-          <Filename>jadetex</Filename> and
-          <Filename>pdfvirtex</Filename> to
-          <Filename>pdfjadetex</Filename> (otherwise DVI, PostScript
+         <para>Make links from <filename>virtex</filename> to
+          <filename>jadetex</filename> and
+          <filename>pdfvirtex</filename> to
+          <filename>pdfjadetex</filename> (otherwise DVI, PostScript
           and PDF output will not work). Copy
-          <Filename>dsssl/*.{dtd,dsl}</Filename> and
-          <Filename>catalog</Filename> to
-          <Filename>/usr/[local/]lib/sgml</Filename>.</para>
+          <filename>dsssl/*.{dtd,dsl}</filename> and
+          <filename>catalog</filename> to
+          <filename>/usr/[local/]lib/sgml</filename>.</para>
        </sect4>
 
        <sect4>
          <title>DocBook and the DocBook stylesheets</title>
 
-         <para>Get a Zip of <ULink
-          URL="http://www.oasis-open.org/docbook/sgml/3.1/index.html">DocBook</ULink>
+         <para>Get a Zip of <ulink
+          url="http://www.oasis-open.org/docbook/sgml/3.1/index.html">DocBook</ulink>
           and install the contents in
-          <Filename>/usr/[local/]/lib/sgml</Filename>.</para>
+          <filename>/usr/[local/]/lib/sgml</filename>.</para>
 
-         <para>Get the <ULink
-          URL="http://nwalsh.com/docbook/dsssl/">DocBook
-          stylesheets</ULink> and install in
-          <Filename>/usr/[local/]lib/sgml/stylesheets</Filename>
+         <para>Get the <ulink
+          url="http://nwalsh.com/docbook/dsssl/">DocBook
+          stylesheets</ulink> and install in
+          <filename>/usr/[local/]lib/sgml/stylesheets</filename>
           (thereby creating a subdirectory docbook). For indexing,
-          copy or link <Filename>collateindex.pl</Filename> from the
-          DocBook stylesheets archive in <Filename>bin</Filename> into
-          a directory on your <Constant>PATH</Constant>.</para>
-
-         <para>Download the <ULink
-          URL="http://www.oasis-open.org/cover/ISOEnts.zip">ISO
-          entities</ULink> into
-          <Filename>/usr/[local/]lib/sgml</Filename>.</para>
+          copy or link <filename>collateindex.pl</filename> from the
+          DocBook stylesheets archive in <filename>bin</filename> into
+          a directory on your <constant>PATH</constant>.</para>
+
+         <para>Download the <ulink
+          url="http://www.oasis-open.org/cover/ISOEnts.zip">ISO
+          entities</ulink> into
+          <filename>/usr/[local/]lib/sgml</filename>.</para>
        </sect4>
       </sect3>
     </sect2>
@@ -3474,7 +3605,7 @@ $ make way=p
     <sect2>
       <title>Configuring the DocBook tools</title>
 
-      <Para>Once the DocBook tools are installed, the configure script
+      <para>Once the DocBook tools are installed, the configure script
       will detect them and set up the build system accordingly. If you
       have a system that isn't supported, let us know, and we'll try
       to help.</para>
@@ -3486,12 +3617,12 @@ $ make way=p
       <para>If you install from source, you'll get a pile of warnings
       of the form
 
-<Screen>DTDDECL catalog entries are not supported</Screen>
+<screen>DTDDECL catalog entries are not supported</screen>
 
       every time you build anything. These can safely be ignored, but
       if you find them tedious you can get rid of them by removing all
-      the <Constant>DTDDECL</Constant> entries from
-      <Filename>docbook.cat</Filename>.</para>
+      the <constant>DTDDECL</constant> entries from
+      <filename>docbook.cat</filename>.</para>
     </sect2>
 
     <sect2>
@@ -3569,14 +3700,14 @@ $ make install-docs
        supported (or perhaps has been supported in the past, but
        currently isn't).  This is the easiest type of porting job,
        but it still requires some careful bootstrapping.  Proceed to
-       <xref linkend="sec-booting-from-hc">.</para>
+       <xref linkend="sec-booting-from-hc"/>.</para>
       </listitem>
       
       <listitem>
        <para>Your system's hardware architecture isn't supported by
        GHC.  This will be a more difficult port (though by comparison
        perhaps not as difficult as porting gcc).  Proceed to <xref
-       linkend="unregisterised-porting">.</para>
+       linkend="unregisterised-porting"/>.</para>
       </listitem>
     </itemizedlist>
     
@@ -3593,17 +3724,16 @@ $ make install-docs
       target machine, and compiling them using gcc to get a working
       GHC.</para>
 
-      <para><emphasis>NOTE: GHC version 5.xx is significantly harder
-      to bootstrap from C than previous versions.  We recommend
-      starting from version 4.08.2 if you need to bootstrap in this
-      way.</emphasis></para>
+      <para><emphasis>NOTE: GHC versions 5.xx were hard to bootstrap
+      from C.  We recommend using GHC 6.0.1 or
+      later.</emphasis></para>
 
-      <para>HC files are architecture-dependent (but not
-      OS-dependent), so you have to get a set that were generated on
-      similar hardware.  There may be some supplied on the GHC
-      download page, otherwise you'll have to compile some up
-      yourself, or start from <emphasis>unregisterised</emphasis> HC
-      files - see <xref linkend="unregisterised-porting">.</para>
+      <para>HC files are platform-dependent, so you have to get a set
+      that were generated on similar hardware.  There may be some
+      supplied on the GHC download page, otherwise you'll have to
+      compile some up yourself, or start from
+      <emphasis>unregisterised</emphasis> HC files - see <xref
+      linkend="unregisterised-porting"/>.</para>
 
       <para>The following steps should result in a working GHC build
       with full libraries:</para>
@@ -3630,9 +3760,9 @@ $ make install-docs
           command will execute the whole build process (it won't
           install yet):</para>
 
-<Screen>
+<screen>
 foo% distrib/hc-build --prefix=<replaceable>dir</replaceable>
-</Screen>
+</screen>
 <indexterm><primary>--hc-build</primary></indexterm>
 
          <para>By default, the installation directory is
@@ -3645,9 +3775,9 @@ foo% distrib/hc-build --prefix=<replaceable>dir</replaceable>
           build process, you can install the resulting system, as
           normal, with</para>
 
-<Screen>
+<screen>
 foo% make install
-</Screen>
+</screen>
        </listitem>
       </itemizedlist>
     </sect2>
@@ -3687,65 +3817,239 @@ foo% make install
       since unregisterised compilation is usually just a step on the
       way to a full registerised port, we don't mind too much.</para>
 
-      <sect3>
-       <title>Building an unregisterised port</title>
+      <para>Notes on GHC portability in general: we've tried to stick
+      to writing portable code in most parts of the system, so it
+      should compile on any POSIXish system with gcc, but in our
+      experience most systems differ from the standards in one way or
+      another.  Deal with any problems as they arise - if you get
+      stuck, ask the experts on
+      <email>glasgow-haskell-users@haskell.org</email>.</para>
        
-       <para>The first step is to get some unregisterised HC files.
-       Either (a)&nbsp;download them from the GHC site (if there are
-       some available for the right version of GHC), or
-       (b)&nbsp;build them yourself on any machine with a working
-       GHC.  If at all possible this should be a machine with the
-       same word size as the target.</para>
-
-       <para>There is a script available which should automate the
-       process of doing the 2-stage bootstrap necessary to get the
-       unregisterised HC files - it's available in <ulink
-       url="http://cvs.haskell.org/cgi-bin/cvsweb.cgi/fptools/distrib/cross-port"><filename>fptools/distrib/cross-port</filename></ulink>
-       in CVS.</para>
-
-       <para>Now take these unregisterised HC files to the target
-       platform and bootstrap a compiler from them as per the
-       instructions in <xref linkend="sec-booting-from-hc">.  In
-       <filename>build.mk</filename>, you need to tell the build
-       system that the compiler you're building is
-       (a)&nbsp;unregisterised itself, and (b)&nbsp;builds
-       unregisterised binaries.  This varies depending on the GHC
-       version you're bootstraping:</para>
+      <para>Lots of useful information about the innards of GHC is
+      available in the <ulink
+      url="http://www.cse.unsw.edu.au/~chak/haskell/ghc/comm/">GHC
+      Commentary</ulink>, which might be helpful if you run into some
+      code which needs tweaking for your system.</para>
 
-<programlisting>
-# build.mk for GHC 4.08.x
-GhcWithRegisterised=NO
-</programlisting>
+      <sect3>
+       <title>Cross-compiling to produce an unregisterised GHC</title>
+
+       <para>In this section, we explain how to bootstrap GHC on a
+       new platform, using unregisterised intermediate C files.  We
+       haven't put a great deal of effort into automating this
+       process, for two reasons: it is done very rarely, and the
+       process usually requires human intervention to cope with minor
+       porting issues anyway.</para>
+
+       <para>The following step-by-step instructions should result in
+       a fully working, albeit unregisterised, GHC.  Firstly, you
+       need a machine that already has a working GHC (we'll call this
+       the <firstterm>host</firstterm> machine), in order to
+       cross-compile the intermediate C files that we will use to
+       bootstrap the compiler on the <firstterm>target</firstterm>
+       machine.</para>
+
+       <itemizedlist>
+         <listitem>
+           <para>On the target machine:</para>
+
+         <itemizedlist>
+           <listitem>
+             <para>Unpack a source tree (preferably a released
+             version).  We will call the path to the root of this
+             tree <replaceable>T</replaceable>.</para>
+           </listitem>
+
+           <listitem>
+<screen>
+$ cd <replaceable>T</replaceable>
+$ ./configure --enable-hc-boot --enable-hc-boot-unregisterised
+</screen>
+
+             <para>You might need to update
+              <filename>configure.in</filename> to recognise the new
+              architecture, and re-generate
+              <filename>configure</filename> with
+              <literal>autoreconf</literal>.</para>
+           </listitem>
+  
+           <listitem>
+<screen>
+$ cd <replaceable>T</replaceable>/ghc/includes
+$ make config.h
+</screen>
+           </listitem>
+         </itemizedlist>
+         </listitem>
+
+         <listitem>
+           <para>On the host machine:</para>
+             
+         <itemizedlist>
+           <listitem>
+             <para>Unpack a source tree (same released version).  Call
+              this directory <replaceable>H</replaceable>.</para>
+           </listitem>
+           <listitem>
+<screen>
+$ cd <replaceable>H</replaceable>
+$ ./configure
+</screen>
+           </listitem>
+
+           <listitem>
+             <para>Create
+             <filename><replaceable>H</replaceable>/mk/build.mk</filename>,
+             with the following contents:</para>
 
 <programlisting>
-# build.mk for GHC 5.xx
-GhcUnregisterised=YES
+GhcUnregisterised = YES
+GhcLibHcOpts = -O -H32m -keep-hc-files
+GhcLibWays =
+SplitObjs = NO
+GhcWithNativeCodeGen = NO
+GhcWithInterpreter = NO
+GhcStage1HcOpts = -O -H32m -fasm
+GhcStage2HcOpts = -O -fvia-C -keep-hc-files
 </programlisting>
+           </listitem>
 
-       <para>Version 5.xx only: use the option
-       <option>--enable-hc-boot-unregisterised</option> instead of
-       <option>--enable-hc-boot</option> when running
-       <filename>./configure</filename>.</para>
-
-       <para>The build may not go through cleanly.  We've tried to
-       stick to writing portable code in most parts of the compiler,
-       so it should compile on any POSIXish system with gcc, but in
-       our experience most systems differ from the standards in one
-       way or another.  Deal with any problems as they arise - if you
-       get stuck, ask the experts on
-       <email>glasgow-haskell-users@haskell.org</email>.</para>
-       
-       <para>Once you have the unregisterised compiler up and
-       running, you can use it to start a registerised port.  The
-       following sections describe the various parts of the system
-       that will need architecture-specific tweaks in order to get a
-       registerised build going.</para>
-
-       <para>Lots of useful information about the innards of GHC is
-       available in the <ulink
-       url="http://www.cse.unsw.edu.au/~chak/haskell/ghc/comm/">GHC
-       Commentary</ulink>, which might be helpful if you run into
-       some code which needs tweaking for your system.</para>
+           <listitem>
+             <para>Edit
+             <filename><replaceable>H</replaceable>/mk/config.mk</filename>:</para>
+             <itemizedlist>
+               <listitem>
+                 <para>change <literal>TARGETPLATFORM</literal>
+                  appropriately, and set the variables involving
+                  <literal>TARGET</literal> to the correct values for
+                  the target platform.  This step is necessary because
+                  currently <literal>configure</literal> doesn't cope
+                  with specifying different values for the
+                  <literal>--host</literal> and
+                  <literal>--target</literal> flags.</para>
+               </listitem>
+               <listitem>
+                 <para>copy <literal>LeadingUnderscore</literal>
+                 setting from target.</para>
+               </listitem>
+             </itemizedlist>
+           </listitem>
+
+           <listitem>
+             <para>Copy
+             <filename><replaceable>T</replaceable>/ghc/includes/config.h</filename>
+             to
+             <filename><replaceable>H</replaceable>/ghc/includes</filename>.
+             Note that we are building on the host machine, using the
+             target machine's <literal>config.h</literal> file.  This
+             is so that the intermediate C files generated here will
+             be suitable for compiling on the target system.</para>
+
+           </listitem>
+
+             <listitem>
+               <para>Touch <literal>config.h</literal>, just to make
+               sure it doesn't get replaced during the build:</para>
+<screen>
+$ touch <replaceable>H</replaceable>/ghc/includes/config.h</screen>
+             </listitem>
+
+           <listitem>
+               <para>Now build the compiler:</para>
+<screen>
+$ cd <replaceable>H</replaceable>/glafp-utils &amp;&amp; make boot &amp;&amp; make
+$ cd <replaceable>H</replaceable>/ghc &amp;&amp; make boot &amp;&amp; make
+</screen>
+             <para>Don't worry if the build falls over in the RTS, we
+              don't need the RTS yet.</para>
+           </listitem>
+
+           <listitem>
+<screen>
+$ cd <replaceable>H</replaceable>/libraries
+$ make boot &amp;&amp; make
+</screen>
+           </listitem>
+
+           <listitem>
+<screen>
+$ cd <replaceable>H</replaceable>/ghc
+$ make boot stage=2 &amp;&amp; make stage=2
+</screen>
+           </listitem>
+           
+           <listitem>
+             <screen>
+$ cd <replaceable>H</replaceable>/ghc/utils
+$ make clean
+$ make -k HC=<replaceable>H</replaceable>/ghc/compiler/stage1/ghc-inplace \
+               EXTRA_HC_OPTS='-O -fvia-C -keep-hc-files'
+</screen>
+           </listitem>
+           
+           <listitem>
+<screen>
+$ cd <replaceable>H</replaceable>
+$ make hc-file-bundle Project=Ghc
+</screen>
+           </listitem>
+
+           <listitem>
+             <para>copy
+             <filename><replaceable>H</replaceable>/*-hc.tar.gz</filename>
+             to <filename><replaceable>T</replaceable>/..</filename>.</para>
+           </listitem>
+         </itemizedlist>
+         </listitem>
+
+         <listitem>
+           <para>On the target machine:</para>
+
+           <para>At this stage we simply need to bootstrap a compiler
+           from the intermediate C files we generated above.  The
+           process of bootstrapping from C files is automated by the
+           script in <literal>distrib/hc-build</literal>, and is
+           described in <xref linkend="sec-booting-from-hc"/>.</para>
+
+<screen>
+$ ./distrib/hc-build --enable-hc-boot-unregisterised
+</screen>
+
+           <para>However, since this is a bootstrap on a new machine,
+           the automated process might not run to completion the
+           first time.  For that reason, you might want to treat the
+           <literal>hc-build</literal> script as a list of
+           instructions to follow, rather than as a fully automated
+           script.  This way you'll be able to restart the process
+           part-way through if you need to fix anything on the
+           way.</para>
+
+           <para>Don't bother with running
+           <literal>make&nbsp;install</literal> in the newly
+           bootstrapped tree; just use the compiler in that tree to
+           build a fresh compiler from scratch, this time without
+           booting from C files.  Before doing this, you might want
+           to check that the bootstrapped compiler is generating
+           working binaries:</para>
+
+<screen>
+$ cat >hello.hs
+main = putStrLn "Hello World!\n"
+^D
+$ <replaceable>T</replaceable>/ghc/compiler/ghc-inplace hello.hs -o hello
+$ ./hello
+Hello World!
+</screen>
+
+           <para>Once you have the unregisterised compiler up and
+           running, you can use it to start a registerised port.  The
+           following sections describe the various parts of the
+           system that will need architecture-specific tweaks in
+           order to get a registerised build going.</para>
+
+         </listitem>
+       </itemizedlist>
       </sect3>
 
       <sect3>
@@ -3756,9 +4060,9 @@ GhcUnregisterised=YES
 
        <variablelist>
          <varlistentry>
-           <term><filename>ghc/includes/MachRegs.h</filename></term>
-           <indexterm><primary><filename>MachRegs.h</filename></primary>
-           </indexterm>
+           <term><filename>ghc/includes/MachRegs.h</filename>
+           <indexterm><primary><filename>MachRegs.h</filename></primary></indexterm>
+            </term>
            <listitem>
              <para>Defines the STG-register to machine-register
              mapping.  You need to know your platform's C calling
@@ -3768,19 +4072,19 @@ GhcUnregisterised=YES
            </listitem>
          </varlistentry>
          <varlistentry>
-           <term><filename>ghc/includes/TailCalls.h</filename></term>
-           <indexterm><primary><filename>TailCalls.h</filename></primary>
-           </indexterm>
+           <term><filename>ghc/includes/TailCalls.h</filename>
+           <indexterm><primary><filename>TailCalls.h</filename></primary></indexterm>
+            </term>
            <listitem>
              <para>Macros that cooperate with the mangler (see <xref
-             linkend="sec-mangler">) to make proper tail-calls
+             linkend="sec-mangler"/>) to make proper tail-calls
              work.</para>
            </listitem>
          </varlistentry>
          <varlistentry>
-           <term><filename>ghc/rts/Adjustor.c</filename></term>
-           <indexterm><primary><filename>Adjustor.c</filename></primary>
-           </indexterm>
+           <term><filename>ghc/rts/Adjustor.c</filename>
+           <indexterm><primary><filename>Adjustor.c</filename></primary></indexterm>
+            </term>
            <listitem>
              <para>Support for
              <literal>foreign&nbsp;import&nbsp;"wrapper"</literal>
@@ -3791,9 +4095,9 @@ GhcUnregisterised=YES
            </listitem>
          </varlistentry>
          <varlistentry>
-           <term><filename>ghc/rts/StgCRun.c</filename></term>
-           <indexterm><primary><filename>StgCRun.c</filename></primary>
-           </indexterm>
+           <term><filename>ghc/rts/StgCRun.c</filename>
+           <indexterm><primary><filename>StgCRun.c</filename></primary></indexterm>
+            </term>
            <listitem>
              <para>The little assembly layer between the C world and
              the Haskell world.  See the comments and code for the
@@ -3801,12 +4105,12 @@ GhcUnregisterised=YES
            </listitem>
          </varlistentry>
          <varlistentry>
-           <term><filename>ghc/rts/MBlock.h</filename></term>
-           <term><filename>ghc/rts/MBlock.c</filename></term>
-           <indexterm><primary><filename>MBlock.h</filename></primary>
-           </indexterm>
-           <indexterm><primary><filename>MBlock.c</filename></primary>
-           </indexterm>
+           <term><filename>ghc/rts/MBlock.h</filename>
+              <indexterm><primary><filename>MBlock.h</filename></primary></indexterm>
+            </term>
+           <term><filename>ghc/rts/MBlock.c</filename>
+              <indexterm><primary><filename>MBlock.c</filename></primary></indexterm>
+            </term>
            <listitem>
              <para>These files are really OS-specific rather than
              architecture-specific.  In <filename>MBlock.h</filename>
@@ -3872,10 +4176,13 @@ GhcUnregisterised=YES
        <para>To support GHCi, you need to port the dynamic linker
        (<filename>fptools/ghc/rts/Linker.c</filename>).  The linker
        currently supports the ELF and PEi386 object file formats - if
-       your platform uses one of these then you probably don't have
-       to do anything except fiddle with the
-       <literal>#ifdef</literal>s at the top of
-       <filename>Linker.c</filename> to tell it about your OS.</para>
+       your platform uses one of these then things will be
+       significantly easier.  The majority of Unix platforms use the
+       ELF format these days.  Even so, there are some
+       machine-specific parts of the ELF linker: for example, the
+       code for resolving particular relocation types is
+       machine-specific, so some porting of this code to your
+       architecture will probaly be necessary.</para>
        
        <para>If your system uses a different object file format, then
        you have to write a linker &mdash; good luck!</para>
@@ -3897,7 +4204,7 @@ WARNINGS about pitfalls and known &ldquo;problems&rdquo;:
 
 <para>
 
-<OrderedList>
+<orderedlist>
 <listitem>
 
 <para>
@@ -3913,9 +4220,9 @@ of choice).
 
 The best way around it is to say
 
-<ProgramListing>
+<programlisting>
 export TMPDIR=&#60;dir&#62;
-</ProgramListing>
+</programlisting>
 
 in your <filename>build.mk</filename> file.
 Then GHC and the other <literal>fptools</literal> programs will use the appropriate directory
@@ -3947,11 +4254,11 @@ incompatible pointer type&rdquo; out of GCC.  Harmless.
 Similarly, <command>ar</command>chiving warning messages like the following are not
 a problem:
 
-<Screen>
+<screen>
 ar: filename GlaIOMonad__1_2s.o truncated to GlaIOMonad_
 ar: filename GlaIOMonad__2_2s.o truncated to GlaIOMonad_
 ...
-</Screen>
+</screen>
 
 
 </para>
@@ -3991,15 +4298,15 @@ above.
 </itemizedlist>
 
 
-and try again: <command>gmake</command>.  (see <Xref LinkEnd="sec-suffix"> for information about
+and try again: <command>gmake</command>.  (see <xref linkend="sec-suffix"/> for information about
 <constant>&lt;module&gt;&lowbar;HC&lowbar;OPTS</constant>.)
 
 Alternatively, just cut to the chase:
 
-<Screen>
+<screen>
 % cd ghc/compiler
 % make EXTRA_HC_OPTS=-optCrts-M128M
-</Screen>
+</screen>
 
 
 </para>
@@ -4023,13 +4330,13 @@ this bug also suggests that you have an old GCC.
 You <emphasis>may</emphasis> need to re-<command>ranlib</command><indexterm><primary>ranlib</primary></indexterm> your libraries (on Sun4s).
 
 
-<Screen>
+<screen>
 % cd $(libdir)/ghc-x.xx/sparc-sun-sunos4
 % foreach i ( `find . -name '*.a' -print` ) # or other-shell equiv...
 ?    ranlib $i
 ?    # or, on some machines: ar s $i
 ? end
-</Screen>
+</screen>
 
 
 We'd be interested to know if this is still necessary.
@@ -4045,18 +4352,18 @@ a bit from one Unix to another.  One particular gotcha is macro calls
 like this:
 
 
-<ProgramListing>
+<programlisting>
 SLIT("Hello, world")
-</ProgramListing>
+</programlisting>
 
 
 Some <command>cpp</command>s treat the comma inside the string as separating two macro
 arguments, so you get
 
 
-<Screen>
+<screen>
 :731: macro `SLIT' used with too many (2) args
-</Screen>
+</screen>
 
 
 Alas, <command>cpp</command> doesn't tell you the offending file!
@@ -4065,31 +4372,26 @@ Workaround: don't put weird things in string args to <command>cpp</command> macr
 </para>
 </listitem>
 
-</OrderedList>
+</orderedlist>
 
 </para>
 
 </sect1>
 
 
-<Sect1 id="winbuild"><Title>Notes for building under Windows</Title>
-
+<sect1 id="platforms"><title>Platforms, scripts, and file names</title>
 <para>
-This section summarises how to get the utilities you need on your
-Win95/98/NT/2000 machine to use CVS and build GHC. Similar notes for
-installing and running GHC may be found in the user guide. In general,
-Win95/Win98 behave the same, and WinNT/Win2k behave the same.
-You should read the GHC installation guide sections on Windows (in the user
-guide) before continuing to read these notes.
+GHC is designed both to be built, and to run, on both Unix and Windows.  This flexibility
+gives rise to a good deal of brain-bending detail, which we have tried to collect in this chapter.
 </para>
 
+<sect2 id="cygwin-and-mingw"><title>Windows platforms: Cygwin, MSYS, and MinGW</title>
 
-<sect2 id="cygwin-and-mingw"><Title>Cygwin and MinGW</Title>
-
-<para> The Windows situation for building GHC is rather confusing.  This section
+<para> The build system is built around Unix-y makefiles.  Because it's not native,
+the Windows situation for building GHC is particularly confusing.  This section
 tries to clarify, and to establish terminology.</para>
 
-<sect3 id="ghc-mingw"><title>GHC-mingw</title>
+<sect3 id="ghc-mingw"><title>MinGW</title>
 
 <para> <ulink url="http://www.mingw.org">MinGW (Minimalist GNU for Windows)</ulink> 
 is a collection of header
@@ -4099,47 +4401,125 @@ current set of tools include GNU Compiler Collection (<command>gcc</command>), G
 Utilities (Binutils), GNU debugger (Gdb), GNU make, and a assorted
 other utilities. 
 </para>
-<para>The GHC that we distribute includes, inside the distribution itself, the MinGW <command>gcc</command>,
-<command>as</command>, <command>ld</command>, and a bunch of input/output libraries.  
-GHC compiles Haskell to C (or to 
-assembly code), and then invokes these MinGW tools to generate an executable binary.
-The resulting binaries can run on any Win32 system.
+
+<para> The down-side of MinGW is that the MinGW libraries do not support anything like the full
+Posix interface.  
 </para>
-<para> We will call a GHC that targets MinGW in this way <emphasis>GHC-mingw</emphasis>.</para>
+</sect3>
+
+<sect3 id="ghc-cygwin"><title>Cygwin and MSYS</title>
+
+<para>You can't use the MinGW to <emphasis>build</emphasis> GHC, because MinGW doesn't have a shell,
+or the standard Unix commands such as <command>mv</command>, <command>rm</command>,
+<command>ls</command>, nor build-system stuff such as <command>make</command> and <command>cvs</command>.
+For that, there are two choices: <ulink url="http://www.cygwin.com">Cygwin</ulink> 
+and <ulink url="http://www.mingw.org/msys.shtml">MSYS</ulink>:
+
+<itemizedlist>
+<listitem><para>
+Cygwin comes with compilation tools (<command>gcc</command>, <command>ld</command> and so on), which
+compile code that has access to all of Posix.  The price is that the executables must be 
+dynamically linked with the Cygwin DLL, so that <emphasis>you cannot run a Cywin-compiled program on a machine
+that doesn't have Cygwin</emphasis>.  Worse, Cygwin is a moving target.  The name of the main DLL, <literal>cygwin1.dll</literal>
+does not change, but the implementation certainly does.  Even the interfaces to functions
+it exports seem to change occasionally. </para>
+</listitem>
+
+<listitem><para>
+MSYS is a fork of the Cygwin tree, so they
+are fundamentally similar.  However, MSYS is by design much smaller and simpler.  Access to the file system goes
+through fewer layers, so MSYS is quite a bit faster too.
+</para>
+
+<para>Furthermore, MSYS provides no compilation tools; it relies instead on the MinGW tools. These
+compile binaries that run with no DLL support, on any Win32 system.
+However, MSYS does come with all the make-system tools, such as <command>make</command>, <command>autoconf</command>, 
+<command>cvs</command>, <command>ssh</command> etc.  To get these, you have to download the 
+MsysDTK (Developer Tool Kit) package, as well as the base MSYS package.
+</para>
+<para>MSYS does have a DLL, but it's only used by MSYS commands (<command>sh</command>, <command>rm</command>, 
+<command>ssh</command> and so on),
+not by programs compiled under MSYS.
+</para></listitem>
 
-<para> The down-side of GHC-mingw is that the MinGW libraries do not support anything like the full
-Posix interface.  So programs compiled with GHC-mingw cannot import the (Haskell) Posix 
+</itemizedlist>
+
+</para>
+</sect3>
+
+<sect3><title>Targeting MinGW</title>
+
+<para>We want GHC to compile programs that work on any Win32 system.  Hence:
+<itemizedlist>
+<listitem><para>
+GHC does invoke a C compiler, assembler, linker and so on, but we ensure that it only
+invokes the MinGW tools, not the Cygwin ones.  That means that the programs GHC compiles
+will work on any system, but it also means that the programs GHC compiles do not have access
+to all of Posix.  In particular, they cannot import the (Haskell) Posix 
 library; they have to do
-their input output using standard Haskell I/O libraries, or native Win32 bindings.
+their input output using standard Haskell I/O libraries, or native Win32 bindings.</para>
+<para> We will call a GHC that targets MinGW in this way <emphasis>GHC-mingw</emphasis>.</para>
+</listitem>
+
+<listitem><para>
+To make the GHC distribution self-contained, the GHC distribution includes the MinGW <command>gcc</command>,
+<command>as</command>, <command>ld</command>, and a bunch of input/output libraries.  
+</para></listitem>
+</itemizedlist>
+So <emphasis>GHC targets MinGW</emphasis>, not Cygwin.
+It is in principle possible to build a version of GHC, <emphasis>GHC-cygwin</emphasis>, 
+that targets Cygwin instead.  The up-side of GHC-cygwin is
+that Haskell programs compiled by GHC-cygwin can import the (Haskell) Posix library.
+<emphasis>We do not support GHC-cygwin, however; it is beyond our resources.</emphasis>
+</para>
+
+<para>While GHC <emphasis>targets</emphasis> MinGW, that says nothing about 
+how GHC is <emphasis>built</emphasis>.  We use both MSYS and Cygwin as build environments for
+GHC; both work fine, though MSYS is rather lighter weight.</para>
+
+<para>In your build tree, you build a compiler called <command>ghc-inplace</command>.  It
+uses the <command>gcc</command> that you specify using the
+<option>--with-gcc</option> flag when you run
+<command>configure</command> (see below).
+The makefiles are careful to use <command>ghc-inplace</command> (not <command>gcc</command>)
+to compile any C files, so that it will in turn invoke the correct <command>gcc</command> rather that
+whatever one happens to be in your path.  However, the makefiles do use whatever <command>ld</command> 
+and <command>ar</command> happen to be in your path. This is a bit naughty, but (a) they are only
+used to glom together .o files into a bigger .o file, or a .a file, 
+so they don't ever get libraries (which would be bogus; they might be the wrong libraries), and (b)
+Cygwin and MinGW use the same .o file format.  So its ok.
 </para>
 </sect3>
 
-<sect3 id="ghc-cygwin"><title>GHC-cygwin</title>
+<sect3><title> File names </title>
 
-<para>There <emphasis>is</emphasis> a way to get the full Posix interface, which is to use Cygwin.  
-<ulink url="http://www.cygwin.com">Cygwin</ulink> is a complete Unix simulation that runs on Win32.
-Cygwin comes with a shell, and all the usual Unix commands: <command>mv</command>, <command>rm</command>,
-<command>ls</command>, plus of course <command>gcc</command>, <command>ld</command> and so on.
-A C program compiled with the Cygwin <command>gcc</command> certainly can use all of Posix.
+<para>Cygwin, MSYS, and the underlying Windows file system all understand file paths of form <literal>c:/tmp/foo</literal>.
+However:
+<itemizedlist>
+<listitem><para>
+MSYS programs understand <filename>/bin</filename>, <filename>/usr/bin</filename>, and map Windows's lettered drives as
+<filename>/c/tmp/foo</filename> etc.  The exact mount table is given in the doc subdirectory of the MSYS distribution.
 </para>
-<para>So why doesn't GHC use the Cygwin <command>gcc</command> and libraries?  Because
-Cygwin comes with a DLL <emphasis>that must be linked with every runnable Cygwin-compiled program</emphasis>.
-A program compiled by the Cygwin tools cannot run at all unless Cygwin is installed. 
-If GHC targeted Cygwin, users would have to install Cygwin just to run the Haskell programs
-that GHC compiled; and the Cygwin DLL would have to be in the DLL load path.
-Worse, Cygwin is a moving target.  The name of the main DLL, <literal>cygwin1.dll</literal>
-does not change, but the implementation certainly does.  Even the interfaces to functions
-it exports seem to change occasionally. So programs compiled by GHC might only run with
-particular versions of Cygwin.  All of this seems very undesirable.
+<para> When it invokes a command, the MSYS shell sees whether the invoked binary lives in the MSYS <filename>/bin</filename>
+directory.  If so, it just invokes it.  If not, it assumes the program is no an MSYS program, and walks over the command-line
+arguments changing MSYS paths into native-compatible paths.  It does this inside sub-arguments and inside quotes. For example,
+if you invoke
+<programlisting>
+   foogle -B/c/tmp/baz
+</programlisting>
+the MSYS shell will actually call <literal>foogle</literal> with argument <literal>-Bc:/tmp/baz</literal>.
+</para></listitem>
+
+<listitem><para>
+Cygwin programs have a more complicated mount table, and map the lettered drives as <filename>/cygdrive/c/tmp/foo</filename>.
 </para>
-<para>
-Nevertheless, it is certainly possible to build a version of GHC that targets Cygwin;
-we will call that <emphasis>GHC-cygwin</emphasis>.  The up-side of GHC-cygwin is
-that Haskell programs compiled by GHC-cygwin can import the (Haskell) Posix library.
+<para>The Cygwin shell does no argument processing when invoking non-Cygwin programs.
+</para></listitem>
+</itemizedlist>
 </para>
 </sect3>
 
-<sect3><title>HOST_OS vs TARGET_OS</title>
+<sect3><title>Host System vs Target System</title>
 
 <para>
 In the source code you'll find various ifdefs looking like:
@@ -4157,64 +4537,173 @@ and
 These macros are set by the configure script (via the file config.h).
 Which is which?  The criterion is this.  In the ifdefs in GHC's source code:
 <itemizedlist>
+  <listitem>
+    <para>The "host" system is the one on which GHC itself will be run.</para>
+  </listitem>
+  <listitem>
+    <para>The "target" system is the one for which the program compiled by GHC will be run.</para>
+  </listitem>
+</itemizedlist>
+For a stage-2 compiler, in which GHCi is available, the "host" and "target" systems must be the same.
+So then it doesn't really matter whether you use the HOST_OS or TARGET_OS cpp macros.
+
+</para>
+</sect3>
+
+</sect2>
+
+<sect2><title>Wrapper scripts</title>
+
+<para>
+Many programs, including GHC itself and hsc2hs, need to find associated binaries and libraries.
+For <emphasis>installed</emphasis> programs, the strategy depends on the platform.  We'll use
+GHC itself as an example:
+<itemizedlist>
   <listitem> <para>
-  The "host" system is the one on which GHC itself will be run.
+  On Unix, the command <command>ghc</command> is a shell script, generated by adding installation
+  paths to the front of the source file <filename>ghc.sh</filename>, 
+  that invokes the real binary, passing "-B<emphasis>path</emphasis>" as an argument to tell <command>ghc</command>
+  where to find its supporting files. 
   </para> </listitem>
+
   <listitem> <para>
-  The "target" system is the one for which the program compiled by GHC will be run.
+  On vanilla Windows, it turns out to be much harder to make reliable script to be run by the
+  native Windows shell <command>cmd</command> (e.g. limits on the length
+   of the command line).  So instead we invoke the GHC binary directly, with no -B flag.
+  GHC uses the Windows <literal>getExecDir</literal> function to find where the executable is,
+  and from that figures out where the supporting files are.
   </para> </listitem>
 </itemizedlist>
-For a stage-2 compiler, in which GHCi is available, the "host" and "target" systems must be the same.
-So then it doesn't really matter whether you use the HOST_OS or TARGET_OS cpp macros.
+(You can find the layout of GHC's supporting files in the
+  section "Layout of installed files" of Section 2 of the GHC user guide.)
+</para>
+<para>
+Things work differently for <emphasis>in-place</emphasis> execution, where you want to
+execute a program that has just been built in a build tree. The difference is that the
+layout of the supporting files is different.
+In this case, whether on Windows or Unix, we always use a shell script. This works OK
+on Windows because the script is executed by MSYS or Cygwin, which don't have the
+shortcomings of the native Windows <command>cmd</command> shell.
+</para>
 
+</sect2>
+
+</sect1>
+
+<sect1 id="winbuild"><title>Instructions for building under Windows</title>
+
+<para>
+This section gives detailed instructions for how to build 
+GHC from source on your Windows machine. Similar instructions for
+installing and running GHC may be found in the user guide. In general,
+Win95/Win98 behave the same, and WinNT/Win2k behave the same.
 </para>
-</sect3>
+<para>
+Make sure you read the preceding section on platforms (<xref linkend="platforms"/>)
+before reading section.
+You don't need Cygwin or MSYS to <emphasis>use</emphasis> GHC, 
+but you do need one or the other to <emphasis>build</emphasis> GHC.</para>
 
-<sect3><title>Summary</title>
 
-<para>Notice that "GHC-mingw" means "GHC that <emphasis>targets</emphasis> MinGW".  It says nothing about 
-how that GHC was <emphasis>built</emphasis>.  It is entirely possible to have a GHC-mingw that was built
-by compiling GHC's Haskell sources with a GHC-cygwin, or vice versa.</para>
+<sect2 id="msys-install"><title>Installing and configuring MSYS</title>
 
-<para>We distribute only a GHC-mingw built by a GHC-mingw; supporting
-GHC-cygwin too is beyond our resources.  The GHC we distribute
-therefore does not require Cygwin to run, nor do the programs it
-compiles require Cygwin.</para>
+<para>
+MSYS is a lightweight alternative to Cygwin.  
+You don't need MSYS to <emphasis>use</emphasis> GHC, 
+but you do need it or Cygwin to <emphasis>build</emphasis> GHC.
+Here's how to install MSYS.
+<itemizedlist>
+<listitem><para>
+Go to <ulink url="http://www.mingw.org/download.shtml">http://www.mingw.org/download.shtml</ulink> and 
+download the following (of course, the version numbers will differ):
+<itemizedlist>
+  <listitem><para>The main MSYS package (binary is sufficient): <literal>MSYS-1.0.9.exe</literal>
+  </para></listitem>
+  <listitem><para>The MSYS developer's toolkit (binary is sufficient): <literal>msysDTK-1.0.1.exe</literal>.
+                   This provides <command>make</command>, <command>autoconf</command>, 
+                   <command>ssh</command>, <command>cvs</command> and probably more besides.
+  </para></listitem>
+</itemizedlist>
+Run both executables (in the order given above) to install them.  I put them in <literal>c:/msys</literal>
+</para></listitem>
 
-<para>The instructions that follow describe how to build GHC-mingw. It is
-possible to build GHC-cygwin, but it's not a supported route, and the build system might
-be flaky.</para>
+<listitem><para>
+Set the following environment variables
+<itemizedlist>
+  <listitem><para><literal>PATH</literal>: add <literal>c:/msys/1.0/bin</literal> to your path.  (Of course, the version number may differ.)
+  </para></listitem>
 
-<para>In your build tree, you build a compiler called <Command>ghc-inplace</Command>.  It
-uses the <Command>gcc</Command> that you specify using the
-<option>--with-gcc</option> flag when you run
-<Command>configure</Command> (see below).
-The makefiles are careful to use <Command>ghc-inplace</Command> (not <Command>gcc</Command>)
-to compile any C files, so that it will in turn invoke the right <Command>gcc</Command> rather that
-whatever one happens to be in your path.  However, the makefiles do use whatever <Command>ld</Command> 
-and <Command>ar</Command> happen to be in your path. This is a bit naughty, but (a) they are only
-used to glom together .o files into a bigger .o file, or a .a file, 
-so they don't ever get libraries (which would be bogus; they might be the wrong libraries), and (b)
-Cygwin and Mingw use the same .o file format.  So its ok.
+  <listitem><para><literal>HOME</literal>: set to your home directory (e.g. <literal>c:/userid</literal>).
+  This is where, among other things, <command>ssh</command> will look for your <literal>.ssh</literal> directory.
+  </para></listitem>  
+
+  <listitem><para><literal>SHELL</literal>: set to <literal>c:/msys/1.0/bin/sh.exe</literal>
+  </para></listitem>
+
+  <listitem><para><literal>CVS_RSH</literal>: set to <literal>c:/msys/1.0/bin/ssh.exe</literal>.  Only necessary if
+             you are using CVS.
+  </para></listitem>
+
+  <listitem><para><literal>MAKE_MODE</literal>: set to <literal>UNIX</literal>.  (I'm not certain this is necessary for MSYS.)
+  </para></listitem>
+
+</itemizedlist>
+</para></listitem>
+
+<listitem><para>
+Check that the <literal>CYGWIN</literal> environment variable is <emphasis>not</emphasis> set.  It's a bad bug
+that MSYS is affected by this, but if you have CYGWIN set to "ntsec ntea", which is right for Cygwin, it
+causes the MSYS <command>ssh</command> to bogusly fail complaining that your <filename>.ssh/identity</filename>
+file has too-liberal permissinos.
+</para></listitem>
+
+</itemizedlist>
 </para>
-</sect3>
-</sect2>
+<para>Here are some points to bear in mind when using MSYS:
+<itemizedlist>
+<listitem> <para> MSYS does some kind of special magic to binaries stored in 
+<filename>/bin</filename> and <filename>/usr/bin</filename>, which are by default both mapped
+to <filename>c:/msys/1.0/bin</filename> (assuming you installed MSYS in <filename>c:/msys</filename>).
+Do not put any other binaries (such as GHC or Alex) in this directory or its sub-directories: 
+they fail in mysterious ways.  However, it's fine to put other binaries in <filename>/usr/local/bin</filename>,
+which maps to <filename>c:/msys/1.0/local/bin</filename>.</para></listitem>
+
+<listitem> <para> MSYS seems to implement symbolic links by copying, so sharing is lost.
+</para></listitem>
 
-<Sect2><Title>Installing and configuring Cygwin</Title>
+<listitem> <para>
+Win32 has a <command>find</command> command which is not the same as MSYS's find.
+You will probably discover that the Win32 <command>find</command> appears in your <constant>PATH</constant>
+before the MSYS one, because it's in the <emphasis>system</emphasis> <constant>PATH</constant> 
+environment variable, whereas you have probably modified the <emphasis>user</emphasis> <constant>PATH</constant> 
+variable.  You can always invoke <command>find</command> with an absolute path, or rename it.
+</para></listitem>
 
-<para>You don't need Cygwin to <emphasis>use</emphasis> GHC, 
-but you do need it to <emphasis>build</emphasis> GHC.</para>
+<listitem> <para>
+MSYS comes with <command>bzip</command>, and MSYS's <command>tar</command>'s <literal>-j</literal> 
+will bunzip an archive (e.g. <literal>tar xvjf foo.tar.bz2</literal>).  Useful when you get a
+bzip'd dump.</para></listitem>
 
-<para> Install Cygwin from <ulink url="http://www.cygwin.com/">http://www.cygwin.com/</ulink>.
-The installation process is straightforward; we install it in <Filename>c:/cygwin</Filename>.
-During the installation dialogue, make sure that you select:
-<command>cvs</command>, <command>openssh</command>,
-<command>autoconf</command>,
-<command>binutils</command> (includes ld and (I think) ar),
-<command>gcc</command>,
-<command>flex</command>,
-<command>make</command>.
+</itemizedlist>
+</para>
+</sect2>
 
+<sect2><title>Installing and configuring Cygwin</title>
+
+<para> Install Cygwin from <ulink url="http://www.cygwin.com/">http://www.cygwin.com/</ulink>.
+The installation process is straightforward; we install it in <filename>c:/cygwin</filename>.
+During the installation dialogue, make sure that you select all of the following:
+             <command>cvs</command>, 
+             <command>openssh</command>,
+             <command>autoconf</command>,
+             <command>binutils</command> (includes ld and (I think) ar),
+             <command>gcc</command>,
+             <command>flex</command>,
+             <command>make</command>.
+If you miss out any of these, strange things will happen to you.   To see thse packages, 
+click on the "View" button in the "Select Packages" 
+stage of Cygwin's installation dialogue, until the view says "Full".  The default view, which is
+"Category" isn't very helpful, and the "View" button is rather unobtrousive.
 </para>
 <para> Now set the following user environment variables:
 <itemizedlist>
@@ -4224,17 +4713,17 @@ During the installation dialogue, make sure that you select:
 
 <listitem>
 <para>
-Set <constant>MAKE_MODE</constant> to <Literal>UNIX</Literal>. If you
+Set <constant>MAKE_MODE</constant> to <literal>UNIX</literal>. If you
 don't do this you get very weird messages when you type
-<Command>make</Command>, such as:
-<Screen>
+<command>make</command>, such as:
+<screen>
 /c: /c: No such file or directory
-</Screen>
+</screen>
 </para>
 </listitem>
 
 <listitem><para> Set <constant>SHELL</constant> to
-<Filename>c:/cygwin/bin/sh</Filename>. When you invoke a shell in Emacs, this
+<filename>c:/cygwin/bin/bash</filename>. When you invoke a shell in Emacs, this
 <constant>SHELL</constant> is what you get.
 </para></listitem>
 
@@ -4267,21 +4756,21 @@ you can't rename a running program!
 
 <listitem>
 <para>
-Some script files used in the make system start with "<Command>#!/bin/perl</Command>",
-(and similarly for <Command>sh</Command>).  Notice the hardwired path!
-So you need to ensure that your <Filename>/bin</Filename> directory has the following
+Some script files used in the make system start with "<command>#!/bin/perl</command>",
+(and similarly for <command>sh</command>).  Notice the hardwired path!
+So you need to ensure that your <filename>/bin</filename> directory has the following
 binaries in it:
 <itemizedlist>
-<listitem> <para><Command>sh</Command></para></listitem>
-<listitem> <para><Command>perl</Command></para></listitem>
-<listitem> <para><Command>cat</Command></para></listitem>
+<listitem> <para><command>sh</command></para></listitem>
+<listitem> <para><command>perl</command></para></listitem>
+<listitem> <para><command>cat</command></para></listitem>
 </itemizedlist>
-All these come in Cygwin's <Filename>bin</Filename> directory, which you probably have
-installed as <Filename>c:/cygwin/bin</Filename>.  By default Cygwin mounts "<Filename>/</Filename>" as
-<Filename>c:/cygwin</Filename>, so if you just take the defaults it'll all work ok.
+All these come in Cygwin's <filename>bin</filename> directory, which you probably have
+installed as <filename>c:/cygwin/bin</filename>.  By default Cygwin mounts "<filename>/</filename>" as
+<filename>c:/cygwin</filename>, so if you just take the defaults it'll all work ok.
 (You can discover where your Cygwin
-root directory <Filename>/</Filename> is by typing <Command>mount</Command>.)
-Provided <Filename>/bin</Filename> points to the Cygwin <Filename>bin</Filename>
+root directory <filename>/</filename> is by typing <command>mount</command>.)
+Provided <filename>/bin</filename> points to the Cygwin <filename>bin</filename>
 directory, there's no need to copy anything.  If not, copy these binaries from the <filename>cygwin/bin</filename>
 directory (after fixing the <filename>sh.exe</filename> stuff mentioned in the previous bullet).
 </para>
@@ -4305,20 +4794,93 @@ they don't recognise symlinks.
 </para></listitem>
 
 <listitem> <para>
-Win32 has a <command>find</command> command which is not the same as Cygwin's find.
-You will probably discover that the Win32 <command>find</command> appears in your <constant>PATH</constant>
-before the Cygwin one, because it's in the <emphasis>system</emphasis> <constant>PATH</constant> 
-environment variable, whereas you have probably modified the <emphasis>user</emphasis> <constant>PATH</constant> 
-variable.  You can always invoke <command>find</command> with an absolute path, or rename it.
+See the notes in <xref linkend="msys-install"/> about <command>find</command> and <command>bzip</command>,
+which apply to Cygwin too.
 </para></listitem>
 </itemizedlist>
 </para>
 
-</Sect2>
+</sect2>
+
 
-<Sect2><Title>Other things you need to install</Title>
+<sect2 id="configure-ssh"><title>Configuring SSH</title>
 
-<para>You have to install the following other things to build GHC:
+<para><command>ssh</command> comes with Cygwin, provided you remember to ask for it when
+you install Cygwin.  (If not, the installer lets you update easily.)  Look for <command>openssh</command> 
+(not ssh) in the Cygwin list of applications!</para>
+
+<para>There are several strange things about <command>ssh</command> on Windows that you need to know.
+<itemizedlist>
+<listitem>
+<para>
+       The programs <command>ssh-keygen1</command>, <command>ssh1</command>, and <command>cvs</command>,
+       seem to lock up <command>bash</command> entirely if they try to get user input (e.g. if
+       they ask for a password).  To solve this, start up <filename>cmd.exe</filename> 
+       and run it as follows:
+       <screen>
+       c:\tmp> set CYGWIN32=tty
+       c:\tmp> c:/user/local/bin/ssh-keygen1
+       </screen> </para>
+</listitem>
+
+<listitem><para> (Cygwin-only problem, I think.)
+<command>ssh</command> needs to access your directory <filename>.ssh</filename>, in your home directory.  
+To determine your home directory <command>ssh</command> first looks in 
+<filename>c:/cygwin/etc/passwd</filename> (or wherever you have Cygwin installed).  If there's an entry
+there with your userid, it'll use that entry to determine your home directory, <emphasis>ignoring
+the setting of the environment variable $HOME</emphasis>.  If the home directory is
+bogus, <command>ssh</command> fails horribly.   The best way to see what is going on is to say
+<programlisting>
+  ssh -v cvs.haskell.org
+</programlisting>
+which makes <command>ssh</command> print out information about its activity.
+</para>
+<para> You can fix this problem, either by correcting the home-directory field in 
+<filename>c:/cygwin/etc/passwd</filename>, or by simply deleting the entire entry for your userid. If
+you do that, <command>ssh</command> uses the $HOME environment variable instead.
+</para>
+
+</listitem>
+
+<listitem>
+           <para>To protect your
+            <literal>.ssh</literal> from access by anyone else,
+            right-click your <literal>.ssh</literal> directory, and
+            select <literal>Properties</literal>.  If you are not on
+            the access control list, add yourself, and give yourself
+            full permissions (the second panel).  Remove everyone else
+            from the access control list.  Don't leave them there but
+            deny them access, because 'they' may be a list that
+            includes you!</para>
+</listitem>
+
+<listitem>
+           <para>In fact <command>ssh</command> 3.6.1 now seems to <emphasis>require</emphasis>
+             you to have Unix permissions 600 (read/write for owner only) 
+             on the <literal>.ssh/identity</literal> file, else it 
+             bombs out.  For your local C drive, it seems that <literal>chmod 600 identity</literal> works,
+             but on Windows NT/XP, it doesn't work on a network drive (exact dteails obscure).  
+             The solution seems to be to set the $CYGWIN environment
+             variable to "<literal>ntsec neta</literal>".  The $CYGWIN environment variable is discussed
+             in <ulink url="http://cygwin.com/cygwin-ug-net/using-cygwinenv.html">the Cygwin User's Guide</ulink>,
+             and there are more details in <ulink url="http://cygwin.com/faq/faq_4.html#SEC44">the Cygwin FAQ</ulink>.
+             </para>
+</listitem>
+</itemizedlist>
+</para>
+</sect2>
+
+<sect2><title>Other things you need to install</title>
+
+<para>You have to install the following other things to build GHC, listed below.</para>
+
+<para>On Windows you often install executables in directories with spaces, such as 
+"<filename>Program Files</filename>". However, the <literal>make</literal> system for fptools doesn't 
+deal with this situation (it'd have to do more quoting of binaries), so you are strongly advised
+to put binaries for all tools in places with no spaces in their path.
+On both MSYS and Cygwin, it's perfectly OK to install such programs in the standard Unixy places,
+<filename>/usr/local/bin</filename> and <filename>/usr/local/lib</filename>.  But it doesn't matter,
+provided they are in your path.
 <itemizedlist>
 <listitem>
 <para>
@@ -4332,22 +4894,37 @@ you need to add upon completion.
 <listitem>
 <para>
 Install an executable Happy, from <ulink url="http://www.haskell.org/happy">http://www.haskell.org/happy</ulink>.
-Happy is a parser generator used to compile the Haskell grammar.  Add it in your
+Happy is a parser generator used to compile the Haskell grammar.  Under MSYS or Cygwin you can easily
+build it from the source distribution using
+<programlisting>
+  ./configure
+  make
+  make install
+</programlisting>
+This should install it in <filename>/usr/local/bin</filename> (which maps to <filename>c:/msys/1.0/local/bin</filename>
+on MSYS).
+Make sure the installation directory is in your
 <constant>PATH</constant>.
 </para>
 </listitem>
 
+         <listitem>
+           <para>Install Alex.  This can be done by building from the
+           source distribution in the same way as Happy.  Sources are
+           available from <ulink
+           url="http://www.haskell.org/alex">http://www.haskell.org/alex</ulink>.</para>
+         </listitem>
 
 <listitem>
 <para>GHC uses the <emphasis>mingw</emphasis> C compiler to
-generate code, so you have to install that (see <xref linkend="cygwin-and-mingw">). 
+generate code, so you have to install that (see <xref linkend="cygwin-and-mingw"/>). 
 Just pick up a mingw bundle at
 <ulink url="http://www.mingw.org/">http://www.mingw.org/</ulink>.
 We install it in <filename>c:/mingw</filename>.
 </para>
 <para>Do <emphasis>not</emphasis> add any of the <emphasis>mingw</emphasis> binaries to your  path.
 They are only going to get used by explicit access (via the --with-gcc flag you
-give to <Command>configure</Command> later).  If you do add them to your path
+give to <command>configure</command> later).  If you do add them to your path
 you are likely to get into a mess because their names overlap with Cygwin binaries.
 </para>
 </listitem>
@@ -4367,26 +4944,25 @@ so you will need to add <filename>emacs/bin</filename> to your <literal>PATH</li
 
 <listitem>
 <para> Finally, check out a copy of GHC sources from
-the CVS repository, following the instructions above (<xref linkend="cvs-access">).
+the CVS repository, following the instructions above (<xref linkend="cvs-access"/>).
 </para>
 </listitem>
 </itemizedlist>
 </para>
 </sect2>
 
-<Sect2><Title>Building GHC</Title>
+<sect2><title>Building GHC</title>
 
 <para>OK!  
-Now go read the documentation above on building from source (<xref linkend="sec-building-from-source">); 
+Now go read the documentation above on building from source (<xref linkend="sec-building-from-source"/>); 
 the bullets below only tell
 you about Windows-specific wrinkles.</para>
-<ItemizedList>
+<itemizedlist>
 <listitem>
 <para>
-Run <Command>autoconf</Command> both in <filename>fptools</filename>
-and in <filename>fptools/ghc</filename>.  If you omit the latter step you'll
-get an error when you run <filename>./configure</filename>:
-<Screen>
+If you used <command>autoconf</command> instead of <command>autoreconf</command>,
+you'll get an error when you run <filename>./configure</filename>:
+<screen>
 ...lots of stuff...
 creating mk/config.h
 mk/config.h is unchanged
@@ -4394,12 +4970,12 @@ configuring in ghc
 running /bin/sh ./configure  --cache-file=.././config.cache --srcdir=.
 ./configure: ./configure: No such file or directory
 configure: error: ./configure failed for ghc
-</Screen>
+</screen>
 </para>
 </listitem>
 
-<listitem> <para><command>autoconf</command> seems to create the file <filename>configure</filename>
-read-only.  So if you need to run autoconf again (which I sometimes do for safety's sake),
+<listitem> <para><command>autoreconf</command> seems to create the file <filename>configure</filename>
+read-only.  So if you need to run autoreconf again (which I sometimes do for safety's sake),
 you get
 <screen>
 /usr/bin/autoconf: cannot create configure: permission denied
@@ -4408,60 +4984,79 @@ Solution: delete <filename>configure</filename> first.
 </para></listitem>
 
 <listitem>
-<para>
-You either need to add <filename>ghc</filename> to your
-<constant>PATH</constant> before you invoke
-<Command>configure</Command>, or use the <Command>configure</Command>
-option <option>--with-ghc=c:/ghc/ghc-some-version/bin/ghc</option>.
-</para>
-</listitem>
-
-<listitem><para>
-If you are paranoid, delete <filename>config.cache</filename> if it exists.
-This file occasionally remembers out-of-date configuration information, which 
-can be really confusing.
-</para>
-</listitem>
-
-<listitem>
   <para> 
-    After <command>autoconf</command> run <command>./configure</command> in
+    After <command>autoreconf</command> run <command>./configure</command> in
     <filename>fptools/</filename> thus:
 
-<Screen>
+<screen>
   ./configure --host=i386-unknown-mingw32 --with-gcc=c:/mingw/bin/gcc
-</Screen>
+</screen>
 This is the point at which you specify that you are building GHC-mingw
-(see <xref linkend="ghc-mingw">). </para>
+(see <xref linkend="ghc-mingw"/>). </para>
 
 <para> Both these options are important! It's possible to get into
-trouble using the wrong C compiler!
-Furthermore, it's very important that you specify a 
-full mingw path for <command>gcc</command>, not a cygwin path, because GHC (which
-uses this path to invoke <command>gcc</command>) is a Mingw program and won't
-understand a cygwin path..  For example, if you 
+trouble using the wrong C compiler!</para>
+<para>
+Furthermore, it's <emphasis>very important</emphasis> that you specify a 
+full MinGW path for <command>gcc</command>, not a Cygwin path, because GHC (which
+uses this path to invoke <command>gcc</command>) is a MinGW program and won't
+understand a Cygwin path.  For example, if you 
 say <literal>--with-gcc=/mingw/bin/gcc</literal>, it'll be interpreted as
 <filename>/cygdrive/c/mingw/bin/gcc</filename>, and GHC will fail the first
-time it tries to invoke it.   (Worse, the failure does not come with
-a helpful error message, unfortunately.)
+time it tries to invoke it.   Worse, the failure comes with
+no error message whatsoever.  GHC simply fails silently when first invoked, 
+typically leaving you with this:
+<programlisting>
+make[4]: Leaving directory `/cygdrive/e/fptools-stage1/ghc/rts/gmp'
+../../ghc/compiler/ghc-inplace -optc-mno-cygwin -optc-O 
+  -optc-Wall -optc-W -optc-Wstrict-prototypes -optc-Wmissing-prototypes 
+  -optc-Wmissing-declarations -optc-Winline -optc-Waggregate-return 
+  -optc-Wbad-function-cast -optc-Wcast-align -optc-I../includes 
+  -optc-I. -optc-Iparallel -optc-DCOMPILING_RTS 
+  -optc-fomit-frame-pointer -O2 -static 
+  -package-name rts -O -dcore-lint -c Adjustor.c -o Adjustor.o
+make[2]: *** [Adjustor.o] Error 1
+make[1]: *** [all] Error 1
+make[1]: Leaving directory `/cygdrive/e/fptools-stage1/ghc'
+make: *** [all] Error 1
+</programlisting>
+Be warned!
 </para>
 
 <para>
-If you want to build GHC-cygwin (<xref linkend="ghc-cygwin">)
+If you want to build GHC-cygwin (<xref linkend="ghc-cygwin"/>)
 you'll have to do something more like:
-<Screen>
+<screen>
   ./configure --with-gcc=...the Cygwin gcc...
-</Screen>
+</screen>
+</para>
+</listitem>
+
+<listitem><para>
+If you are paranoid, delete <filename>config.cache</filename> if it exists.
+This file occasionally remembers out-of-date configuration information, which 
+can be really confusing.
+</para>
+</listitem>
+
+<listitem><para> You almost certainly want to set
+<programlisting>
+  SplitObjs = NO
+</programlisting>
+in your <filename>build.mk</filename> configuration file (see <xref linkend="sec-build-config"/>).
+This tells the build system not to split each library into a myriad of little object files, one
+for each function.  Doing so reduces binary sizes for statically-linked binaries, but on Windows
+it dramatically increases the time taken to build the libraries in the first place.
 </para>
 </listitem>
 
 <listitem><para> Do not attempt to build the documentation.
 It needs all kinds of wierd Jade stuff that we haven't worked out for
 Win32.</para></listitem>
-</ItemizedList>
-</Sect2>
+</itemizedlist>
+</sect2>
 
 
 </sect1>
 
-</Article>
+</article>