[project @ 2001-04-23 15:21:05 by rrt]
[ghc-hetmet.git] / ghc / docs / users_guide / installing.sgml
index d57f268..7d59e4c 100644 (file)
@@ -1,26 +1,72 @@
 <Chapter id="sec-installing-bin-distrib">
-<Title>Installing from binary distributions</Title>
+  <Title>Installing GHC</Title>
 <IndexTerm><Primary>binary installations</Primary></IndexTerm>
 <IndexTerm><Primary>installation, of binaries</Primary></IndexTerm>
 
 <Para>
 Installing from binary distributions is easiest, and recommended!
-(Why binaries?  Because GHC is a Haskell compiler written in Haskell,
-so you've got to &ldquo;bootstrap&rdquo; it, somehow.  We provide
-machine-generated C-files-from-Haskell for this purpose, but it's
-really quite a pain to use them.  If you must build GHC from its
-sources, using a binary-distributed GHC to do so is a sensible way to
-proceed. For the other <Literal>fptools</Literal> programs, many are written in Haskell,
-so binary distributions allow you to install them without having a Haskell compiler.)
+(Why binaries? Because GHC is a Haskell compiler written in Haskell,
+so you've got to bootstrap it somehow.  We provide machine-generated
+C-files-from-Haskell for this purpose, but it's really quite a pain to
+use them.  If you must build GHC from its sources, using a
+binary-distributed GHC to do so is a sensible way to proceed. For the
+other <Literal>fptools</Literal> programs, many are written in
+Haskell, so binary distributions allow you to install them without
+having a Haskell compiler.)
 </Para>
 
 <Para>This guide is in two parts: installing on Unix-a-likes, and installing on Windows.</Para>
 
 
-<Sect1><Title>Installing on Unix-a-likes</Title>
+  <Sect1><Title>Installing on Unix-a-likes</Title>
+
+    <sect2>
+      <title>When a platform-specific package is available</title>
+      
+      <para>For certain platforms, we provide GHC binaries packaged
+      using the native package format for the platform.  This is
+      likely to be by far the best way to install GHC for your
+      platform if one of these packages is available, since
+      dependencies will automatically be handled and the package
+      system normally provides a way to uninstall the package at a
+      later date.</para>
+
+      <para>We generally provide the following packages:</para>
+
+      <variablelist>
+       <varlistentry>
+         <term>RedHat Linux/x86</term>
+         <listitem>
+           <para>RPM source & binary packages for RedHat Linux (x86
+           only) are available for most major releases.</para>
+         </listitem>
+       </varlistentry>
+
+       <varlistentry>
+         <term>Debian Linux/x86</term>
+         <listitem>
+           <para>Debian packages for Linux (x86 only), also for most
+           major releases.</para>
+         </listitem>
+       </varlistentry>
+
+       <varlistentry>
+         <term>FreeBSD/x86</term>
+         <listitem>
+           <para>On FreeBSD/x86, GHC can be installed using either
+           the ports tree (<literal>cd /usr/ports/lang/ghc && make
+           install</literal>) or from a pre-compiled package
+           available from your local FreeBSD mirror.</para>
+         </listitem>
+       </varlistentry>
+      </variablelist>
+      
+      <para>Other platform-specific packages may be available, check
+      the GHC download page for details.</para>
+    </sect2>
 
 <Sect2>
-<Title>Bundle structure</Title>
+<Title>GHC binary distributions</Title>
 
 <Para>
 <IndexTerm><Primary>bundles of binary stuff</Primary></IndexTerm>
@@ -28,7 +74,7 @@ so binary distributions allow you to install them without having a Haskell compi
 
 <Para>
 Binary distributions come in &ldquo;bundles,&rdquo; one bundle per file called
-<Literal>&lt;bundle&gt;-&lt;platform&gt;.tar.gz</Literal>.  (See the building guide for the definition of a platform.)  Suppose that you untar a binary-distribution bundle, thus:
+<literal><replaceable>bundle</replaceable>-<replaceable>platform</replaceable>.tar.gz</Literal>.  (See the building guide for the definition of a platform.)  Suppose that you untar a binary-distribution bundle, thus:
 </Para>
 
 <Para>
@@ -96,7 +142,7 @@ Guide and this file isn't present.
 </Para>
 </ListItem></VarListEntry>
 <VarListEntry>
-<Term><Literal>bin/&lt;platform&gt;</Literal></Term>
+           <Term><Literal>bin/<replaceable>platform</replaceable></Literal></Term>
 <ListItem>
 <Para>
 contains platform-specific executable
@@ -105,7 +151,7 @@ must end up in your path.
 </Para>
 </ListItem></VarListEntry>
 <VarListEntry>
-<Term><Literal>lib/&lt;platform&gt;/</Literal></Term>
+<Term><Literal>lib/<replaceable>platform</replaceable>/</Literal></Term>
 <ListItem>
 <Para>
 contains platform-specific support
@@ -180,41 +226,6 @@ contains Unix manual pages.
 </VariableList>
 </Para>
 
-<Para>
-This structure is designed so that you can unpack multiple bundles
-(including ones from different releases or platforms) into a single
-<Literal>fptools</Literal> directory
-<FOOTNOTE>
-
-<Para>
-this doesn't work at the
-moment
-</Para>
-
-</FOOTNOTE>
-:
-</Para>
-
-<Para>
-
-<Screen>
-% cd /your/scratch/space
-% gunzip &#60; ghc-x.xx-sun-sparc-solaris2.tar.gz | tar xvf -
-% gunzip &#60; happy-x.xx-sun-sparc-sunos4.tar.gz | tar xvf -</Screen>
-
-</Para>
-
-<Para>
-When you do multiple unpacks like this, the top level <Literal>Makefile</Literal>,
-<Literal>README</Literal>, and <Literal>INSTALL</Literal> get overwritten each time.
-That's fine&mdash;they should be the same.  Likewise, the
-<Literal>ANNOUNCE-&lt;bundle&gt;</Literal> and <Literal>NEWS-&lt;bundle&gt;</Literal>
-files will be duplicated across multiple platforms, so they will be
-harmlessly overwritten when you do multiple unpacks.  Finally, the
-<Literal>share/</Literal> stuff will get harmlessly overwritten when you do
-multiple unpacks for one bundle on different platforms.
-</Para>
-
 <Sect3 id="sec-install">
 <Title>Installing</Title>
 
@@ -380,11 +391,12 @@ regardless, <Literal>ghc-x.xx</Literal> should always invoke GHC version <Litera
 <Title>What bundles there are</Title>
 
 <Para>
-<IndexTerm><Primary>bundles, binary</Primary></IndexTerm>
-There are plenty of &ldquo;non-basic&rdquo; GHC bundles.  The files for them are
-called <Literal>ghc-x.xx-&lt;bundle&gt;-&lt;platform&gt;.tar.gz</Literal>, where
-the <Literal>&lt;platform&gt;</Literal> is as above, and <Literal>&lt;bundle&gt;</Literal> is one
-of these:
+<IndexTerm><Primary>bundles, binary</Primary></IndexTerm> There are
+plenty of &ldquo;non-basic&rdquo; GHC bundles.  The files for them are
+called
+<Literal>ghc-x.xx-<replaceable>bundle</replaceable>-<replaceable>platform</replaceable>.tar.gz</Literal>,
+where the <replaceable>platform</replaceable> is as above, and
+<replaceable>bundle</replaceable> is one of these:
 </Para>
 
 <Para>
@@ -439,6 +451,12 @@ binary bundles&mdash;basic, and profiling.  We don't usually make the
 rest, although you can build them yourself from a source distribution.
 </Para>
 
+<para>The various GHC bundles are designed to be unpacked into the
+same directory; then installing as per the directions above will
+install the whole lot in one go.  Note: you <emphasis>must</emphasis>
+at least have the basic GHC binary distribution bundle, these extra
+bundles won't install on their own.</para>
+
 </Sect3>
 
 <Sect3 id="sec-GHC-test">
@@ -488,12 +506,8 @@ Some simple-but-profitable tests are to compile and run the notorious
 distributed in <Literal>ghc/misc/examples/nfib/</Literal> in a source distribution.
 </Para>
 
-<Para>
-For more information on how to &ldquo;drive&rdquo; GHC, either do <Literal>ghc -help</Literal> or
-consult the User's Guide (distributed in several pre-compiled formats
-with a binary distribution, or in source form in
-<Literal>ghc/docs/users&lowbar;guide</Literal> in a source distribution).
-</Para>
+<para>For more information on how to &ldquo;drive&rdquo; GHC, read
+on...</para>
 
 </Sect3>
 
@@ -506,323 +520,46 @@ with a binary distribution, or in source form in
 
 <Para>
 Getting the Glasgow Haskell Compiler (GHC) to run on Windows platforms can
-be a bit of a trying experience. This document tries to simplify the task by
-enumerating the steps you need to follow in order to set up and configure
-your machine to run GHC (at least that's the intention ;-)
-</Para>
-
-<Sect2><Title>System requirements</Title>
-
-<Para>
-An installation of GHC requires ca. 70M of disk space. The size of the
-installed GHC distribution is just(!) 17M, the rest is needed by
-supporting software.
-</Para>
-
-<Para>
-To run GHC comfortably, your machine should have at least 32M of memory.
-</Para>
-
-</Sect2>
-
-
-<Sect2 id="sec-required"><Title>Software required</Title>
-
-<Para>
-You need two chunks of software other than GHC itself: the Cygwin toolchain, and Perl.  Here's how to get and install them.
-</Para>
-
-<Sect3><Title>The cygwin toolchain (beta20.1)</Title>
-
-<Para>
-GHC depends at the moment on the cygwin tools to operate, which
-dresses up the Win32 environment into something more UNIX-like.
-(notably, it provides <Command>gcc</Command>, <Command>as</Command> and <Command>ld</Command>),
-so you'll need to install these tools first. You also need
-Cygwin to use CVS. (We don't yet support later versions of Cygwin.)
-</Para>
-
-<Para>
-Important grungy information about Cygwin:
-</Para>
-
-<ItemizedList>
-
-<ListItem>
-<Para>
-Cygwin doesn't deal well with filenames that include
-spaces. "<Filename>Program Files</Filename>" and "<Filename>Local files</Filename>" are
-common gotchas.
-</Para>
-</ListItem>
-
-<ListItem>
-<Para>
-Cygwin implements a symbolic link as a text file with some
-magical text in it.  So programs that don't use Cygwin's
-I/O libraries won't recognise such files as symlinks.  
-In particular, programs compiled by GHC are meant to be runnable
-without having Cygwin, so they don't use the Cygwin library, so
-they don't recognise symlinks.
+be a bit of a trying experience. It should be much easier now than in the
+past, since all the software required to build and use GHC is included in
+the InstallShield.
 </Para>
-</ListItem>
-
-</ItemizedList>
 
 <Para>
-Here's how to install Cygwin.
+An installation of GHC requires about 70M of disk space (which can be
+reduced by choosing a &ldquo;compact&rdquo; installation).
+To run GHC comfortably, your machine should have at least
+64M of memory.
 </Para>
 
-<ItemizedList>
-
-<ListItem>
-<Para>
-Download cygwin, beta20.1 (<filename>full.exe</filename>) from
-<ULink URL="http://sourceware.cygnus.com/cygwin/">sourceware.cygnus.com</ULink>
-Install this somewhere locally.
-</Para>
-</ListItem>
-
-<ListItem>
-<Para>
-Create the following directories (if they aren't already there):
-</Para>
-
-<ItemizedList>
-<ListItem><Para><Filename>c:/etc</Filename></Para></ListItem>
-<ListItem><Para><Filename>c:/bin</Filename></Para></ListItem>
-<ListItem><Para><Filename>c:/usr/local/bin</Filename></Para></ListItem>
-</ItemizedList>
-
-<Para>
-(using <Command>mkdir -p /bin</Command>, etc.)
-</Para>
-</ListItem>
-
-<ListItem>
-<Para>
-Copy <Filename>bash.exe</Filename> from the <Filename>bin</Filename>
-directory of the cygwin tree
-(<Filename>cygwin-b20/H-i586-cygwin32/bin/bash.exe</Filename>) to
-<Filename>/bin</Filename> as <Filename>sh.exe</Filename>.  You might
-think that it was easier to use bash directly from it original Cygwin
-directory, but (a) some UNIX utils have got
-<Filename>/bin/sh</Filename> hardwired in, and (b) the path following
-<Literal>#!</Literal> is limited to 32 characters.
-</Para>
-</ListItem>
-
-<ListItem>
-<Para>
-If you're an Emacs user and want to be able to run <Command>bash</Command>
-from within a shell buffer, see the <ULink URL="http://www.cs.washington.edu/homes/voelker/ntemacs.html">NT Emacs home page</ULink> for
-instructions on how to set this up.
-</Para>
-</ListItem>
-
-</ItemizedList>
-
-</Sect3>
-
-
-<Sect3><Title>Environment variables</Title>
-
-<Para>
-In case you don't already know how to set environment variables on a Windows
-machine, here's how. On WinNT/Win2k, to edit your <Constant>PATH</Constant>
-variable (for example), do the following:
-</Para>
-
-<ItemizedList>
-<ListItem><Para>Press Start/Settings/Control Panels</Para></ListItem>
-<ListItem><Para>Double-click System</Para></ListItem>
-<ListItem><Para>Press Advanced</Para></ListItem>
-<ListItem><Para>Press Environment Variables</Para></ListItem>
-<ListItem><Para>Under System Variables, select <Constant>PATH</Constant></Para></ListItem>
-<ListItem><Para>Press Edit</Para></ListItem>
-<ListItem><Para>Add "<Filename>;C:/whatever/</Filename>" to the end of the string (for example)</Para></ListItem>
-<ListItem><Para>Press OK</Para></ListItem>
-</ItemizedList>
-
-<Para>
-Some environment variables are &ldquo;user variables&rdquo; and
-some are &ldquo;system variables&rdquo;.  I'm not sure of the difference
-but both are changed though the same dialogue.
-</Para>
-
-<Para>
-In addition, when running <Command>bash</Command>
-you can set environment variables in your <Filename>.bashrc</Filename> file.
-But it is better to set your environment variables from the
-control panel (they get inherited by bash) because then they are visible
-to applications that aren't started by bash.  For example,
-when you're invoking CVS (and ssh) via Emacs keybindings;
-it invokes <Filename>cvs.exe</Filename> without going via bash.
-</Para>
-
-<Para>
-On a Win9x machine you need to edit <Filename>autoexec.bat</Filename> using
-<Filename>Windows/system/Sysedit</Filename>.  You must reboot to make
-the new settings take effect.
-</Para>
-
-<Para>
-The following environment variables must be set:
-</Para>
-
-<Para>
-<InformalTable>
-<TGroup cols="2">
-<ColSpec Align="Left" Colsep="0">
-<ColSpec Align="Left" Colsep="0">
-<TBody>
-
-<Row>
-<Entry><Constant>PATH</Constant></Entry>
-<Entry>System</Entry>
-<Entry><Para>
-Add <Filename>C:/cygnus/cygwin-b20/H-i586-cygwin32/bin</Filename>.
-<Command>bash</Command> needs this, and when it is invoked from <Filename>/bin</Filename> it can't
-find it. <Filename>c:/bin</Filename> and <Filename>c:/usr/local/bin</Filename> should also be added.
-</Para></Entry>
-</Row>
-
-<Row>
-<Entry><Constant>SHELL</Constant></Entry>
-<Entry>User</Entry>
-<Entry><Para>
-<Filename>c:/bin/sh</Filename>.
-</Para></Entry>
-</Row>
-
-<Row>
-<Entry><Constant>HOME</Constant></Entry>
-<Entry>User</Entry>
-<Entry><Para>
-Set to point to your home directory.  This is where, for example,
-<Command>bash</Command> will look for your <Filename>.bashrc</Filename>
-file.
-</Para></Entry>
-</Row>
-
-<Row>
-<Entry><Constant>MAKE_MODE</Constant></Entry>
-<Entry>User</Entry>
-<Entry><Para>
-Set to <Literal>UNIX</Literal>.  If you don't do
-this you get very weird messages when you type `<Command>make</Command>', such as:
-</Para><Screen>
-/c: /c: No such file or directory</Screen></Entry>
-</Row>
-
-<Row>
-<Entry><Constant>TMPDIR</Constant></Entry>
-<Entry>User</Entry>
-<Entry><Para>
-Set to <Filename>c:/tmp</Filename>. For some reason, Win2k invisibly sets
-this variable to point to a temporary directory in your profile, that
-contains embedded spaces.  If GHC sees the <Constant>TMPDIR</Constant>
-variable set, it tries to use it for temporary files, but Cygwin
-doesn't grok filenames with spaces, so disaster results.
-</Para><Para>
-Furthermore, it seems that <Constant>TMPDIR</Constant> must be set to a directory
-in the same file system in which you invoke GHC.  Otherwise you get very werid messages
-when you invoke GHC, such as:
-<Screen>
-does not exist
-Action: openFile
-Reason: file does not exist /tmp/ghc11068.cpp</Screen>
-We think this is due to a bug in Cygwin.
-</Para></Entry>
-</Row>
-</TBody>
-
-</TGroup>
-</InformalTable>
-</Para>
-
-<Para>
-In addition, we've had problems in the past with certain environment
-variables being set that seem to have bad effects on GHC. If you have
-installed other systems ported from Unix, you might too. If you get weird
-inexplicable failures to build GHC, then it might be worth weeding out unused
-environment variables. Known culprits from the past include
-<Constant>GCC_EXEC_PREFIX</Constant> and <Constant>INCLUDE</Constant>.
-</Para>
-
-</Sect3>
-
-
-<Sect3><Title>Perl5</Title>
-
-<Para>
-The driver script is written in Perl, so you'll need to have this
-installed too. However, the ghc binary distribution includes a
-perl binary for you to make use of, should you not already have a
-cygwin compatible one. Note: GHC does <Emphasis>not</Emphasis>
-work with the ActiveState port of perl.
-</Para>
-
-</Sect3>  <!-- Perl -->
-
-</Sect2>  <!-- Reqd software -->
-
 
 <Sect2><Title>Installing GHC</Title>
 
 <Para>
-Download a GHC distribution:
-</Para>
-
-<VariableList>
-
-<VarListEntry>
-<Term>ghc-4.08&mdash;InstallShield installer, 20M: <ULink
-URL="http://www.haskell.org/ghc/dist/ghc-4-08.exe">http</ULink>
-</Term>
-
-<ListItem>
-<Para>
-(The version number may change.) It is packaged up using an installer that should be familiar-looking to Windows users. Unpack and double click on <Filename>setup.exe</Filename>.
+Download the latest GHC distribution (ghc-4.08 InstallShield installer, 19M)
+from <ULink
+URL="http://www.haskell.org/ghc/download.html">http://www.haskell.org/ghc/download.html</ULink>
+It is packaged up using an installer that should be familiar-looking to
+Windows users.
 </Para>
 
 <Para>
-Note: The cygwin support for long file names containing
+Note: The Cygwin support for long file names containing
 spaces is not 100%, so make sure that you install ghc in a directory
 that has no embedded spaces (i.e., resist the temptation to put it
 in <Filename>/Program Files/</Filename>!)
 </Para>
 
 <Para>
-When the installer has completed its job, you may delete the
-<Filename>ghcInstall</Filename> directory.
-</Para>
-
-<Para>
 When the installer has completed, make sure you add the location of the
-ghc <Filename>bin/</Filename> directory to your path (i.e.
-<Filename>/path/to/wherever/ghc-4.08/bin </Filename>).
-You need to do this in order to bring the various GHC DLLs into scope;
-if not, then you need to copy the DLLs into a directory that is (the
-system directory, for example).
+ghc <Filename>bin/</Filename> directory to your path (e.g.
+<Filename>/ghc/ghc-4.08/bin </Filename>).
+You need to do this in order to bring the various GHC binaries into scope.
+Also, if the directory <Filename>C:/TEMP</Filename> doesn't already exist,
+you should create it.
 </Para>
 
 <Para>
-Note: In case you haven't got perl already installed,
-you will have to manually copy the <Filename>perl.exe</Filename> binary from the
-ghc <Filename>bin/</Filename> into your <Filename>/bin</Filename> directory before continuing&mdash;the installer will not currently do this.
-</Para>
-</ListItem>
-
-</VarListEntry>
-
-</VariableList>
-
-<Para>
-Make sure that you set all the environment variables described above
-under Cygwin installation, including <Constant>TMPDIR</Constant>
-</Para>
-<Para>
 To test the fruits of your labour, try now to compile a simple
 Haskell program:
 </Para>
@@ -832,7 +569,7 @@ bash$ cat main.hs
 module Main(main) where
 
 main = putStrLn "Hello, world!"
-bash$ /path/to/the/ghc/bin/directory/ghc-4.08 -o main main.hs
+bash$ ghc -o main main.hs
 ..
 bash$ ./main
 Hello, world!
@@ -844,7 +581,12 @@ Haskell programs :-) If not, consult the installation FAQ (<XRef LinkEnd="winfaq
 </Para>
 
 <Para>
-Further information on using GHC under Windows can be found in <ULink URL="http://www.dcs.gla.ac.uk/~sof/ghc-win32.html">Sigbj&oslash;rn Finne's pages</ULink>.
+Further information on using GHC under Windows can be found in <ULink
+URL="http://www.dcs.gla.ac.uk/~sof/ghc-win32.html">Sigbj&oslash;rn Finne's
+pages</ULink>. Note: ignore the installation instructions, which are rather
+out of date; the <Emphasis>Miscellaneous</Emphasis> section at the bottom of
+the page is of most interest, covering topics beyond the scope of this
+manual.
 </Para>
 
 </Sect2>
@@ -858,30 +600,6 @@ Further information on using GHC under Windows can be found in <ULink URL="http:
 
 <Question>
 <Para>
-Invoking ghc doesn't seem to do anything, it immediately returns without having compiled the input file.
-</Para>
-</Question>
-
-<Answer>
-<Para>
-One cause of this is that <Filename>/bin/sh</Filename> is missing. To verify, open up a
-bash session and type <Command>ls -l /bin/sh.exe</Command>. If <Filename>sh.exe</Filename> is 
-reported as not being there, copy <Filename>bash.exe</Filename> (which you'll find
-inside the cygwin installation tree as <Filename>H-i586-cygwin32/bin/bash.exe</Filename>)
-to <Filename>/bin/sh.exe</Filename>.
-</Para>
-
-<Para>
-All being well, ghc should then start to function.
-</Para>
-</Answer>
-
-</QandAEntry>
-
-<QandAEntry>
-
-<Question>
-<Para>
 I'm having trouble with symlinks.
 </Para>
 </Question>
@@ -900,7 +618,7 @@ work with symlinks.
 
 <Question>
 <Para>
-I'm getting ``permission denied'' messages from <Command>rm</Command> or
+I'm getting &ldquo;permission denied&rdquo; messages from <Command>rm</Command> or
 <Command>mv</Command>.
 </Para>
 </Question>
@@ -931,74 +649,6 @@ unfortunately. Anyway, better to install 4.08 binaries and use those.
 
 </QandAEntry>
 
-<!--
-<QandAEntry>
-
-<Question>
-<Para>
-When compiling up the <Literal>Hello World</Literal> example, the following happens:
-</Para>
-
-<Screen>
-bash$ /ghc/ghc-4.05/bin/ghc-4.05 main.hs
-&lt;stdin&gt;:0:25: Character literal '{-# LINE 1 "main.hs" -}' too long
-&lt;stdin&gt;:0:25:  on input: "'"
-bash$ </Screen>
-
-<Para>
-or
-</Para>
-
-<Screen>
-bash$ /ghc/ghc-4.05/bin/ghc-4.05 main.hs
-Program too big fit into memory under NT
-bash$ </Screen>
-</Question>
-
-<Answer>
-<Para>
-The cause of this is that you're using a version of <Command>perl</Command> that employs the Microsoft <Command>cmd</Command>/<Command>command</Command> shell when launching sub-processes to execute <Function>system()</Function> calls.
-</Para>
-
-<Para>
-The GHC driver really needs a <Command>perl</Command> which uses a `UNIX'y  shell instead, so
-make sure that the version you're using is of an compatible ilk. In particular, 
-if <Command>perl -v</Command> reports that you've got a copy of the (otherwise fine) port
-of perl done by ActiveState, you're in trouble.
-</Para>
-
-<Para>
-If you're stuck with an incompatible <Command>perl</Command>, the GHC installation comes with a very basic <Command>perl</Command> binary for you to use. Simply copy it into the <Command>/bin</Command> directory.
-</Para>
-
-<Para>
-Notice that copying <Filename>perl.exe</Filename> into <Filename>/bin</Filename> will not cause
-the GHC install to suddenly start functioning. If you don't want to
-re-run the InstallShield installer again, you need to edit the following
-files within the directory tree that the installer created:
-</Para>
-
-<Screen>
-bin/ghc-4.xx    where xx is the minor release number
-bin/stat2resid
-bin/hstags
-lib/mkdependHS</Screen>
-
-<Para>
-For each of these files, you need to edit the first line from instead
-saying <Command>#!/path/to/your/other/perl/install</Command> to <Command>#!/bin/perl</Command>.
-Once that is done, try compiling up the Hello, World example again.
-</Para>
-
-<Para>
-Should you want to pick up a complete installation of a ghc-friendly port
-of perl instead, a <ULink URL="http://cygutils.netpedia.net/">cygwin port</ULink> is available.
-</Para>
-</Answer>
-
-</QandAEntry>
--->
-
 </QandASet>
 
 </Sect2>
@@ -1010,7 +660,10 @@ of perl instead, a <ULink URL="http://cygutils.netpedia.net/">cygwin port</ULink
 <Title>Building the documentation</Title>
 
 <Para>
-We use the DocBook DTD, which is widely used. Most shrink-wrapped distributions seem to be broken in one way or another; thanks to heroic efforts by Sven Panne and Manuel Chakravarty, we now support most of them, plus properly installed versions.
+We use the DocBook DTD, which is widely used. Most shrink-wrapped
+distributions seem to be broken in one way or another; thanks to
+heroic efforts by Sven Panne and Manuel Chakravarty, we now support
+most of them, plus properly installed versions.
 </Para>
 
 <Para>
@@ -1020,21 +673,40 @@ Instructions on installing and configuring the DocBook tools follow.
 <Sect2>
 <Title>Installing the DocBook tools from RPMs</Title>
 
-<Para>
-If you're using a system that can handle RedHat RPM packages, you can
-probably use the <ULink
+<Para> If you're 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 suite that we could
-find. You need all the RPMs except for psgml (i.e.
+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 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> at the moment.
-</Para>
+<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>
 
 </Sect2>
 
+    <sect2>
+      <title>Installing DocBook on FreeBSD</title>
+
+      <para>On FreeBSD systems, the easiest way to get DocBook up and
+      running is to install it from the ports tree or a pre-compiled
+      package (packages are available from your local FreeBSD mirror
+      site).</para>
+
+      <para>To use the ports tree, do this:
+<screen>
+      $ cd /usr/ports/textproc/docproj
+      $ make install
+</screen>
+      This installs the FreeBSD documentation project tools, which
+      includes everything needed to format the GHC
+      documentation.</para>
+    </sect2>
 
 <Sect2>
 <Title>Installing from binaries on Windows</Title>
@@ -1042,9 +714,12 @@ architecture neutral, so are likely to be found in a
 <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 they actually end up in <Filename>\docbook\stylesheets\docbook</Filename>).
+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 they actually
+end up in <Filename>\docbook\stylesheets\docbook</Filename>).
 </Para>
 
 </Sect2>