</Sect2>
-<Sect2><Title>Software required</Title>
+<Sect2><Title>Your environment variables</Title>
+
+<Para>
+Much of the Unixy stuff below involves setting environment variables. For example, on WinNT/Win2k, to edit your <Constant>PATH</Constant> variable,
+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 PATH</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 ``user variables'' and
+some are ``system variables''. I'm not sure of the difference
+but both are changed though the same dialogue.
+</Para>
+
+<Para>
+In addition, when running a Cygwin (see <XRef LinkEnd="sec-required">) shell
+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 need to reboot to make
+the new settings take effect.
+</Para>
+
+</Sect2>
+
+
+<Sect2 id="sec-required"><Title>Software required</Title>
<VariableList>
<VarListEntry>
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.
+so you'll need to install these tools first. You also need
+Cygwin to use CVS.
+</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.
+</Para>
+</ListItem>
+
+</ItemizedList>
+
+<Para>
+Here's how to install Cygwin.
+</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>
+Add the two <Filename>bin</Filename> directories to your <Constant>PATH</Constant>.
+</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>. This is where Emacs looks for a shell (I think).
+</Para>
+</ListItem>
+
+<ListItem>
+<Para>
+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>
+Add <Filename>C:\cygnus\cygwin-b20\H-i586-cygwin32\bin</Filename> to your <Constant>PATH</Constant>.
+<Command>bash</Command> needs this, and when it is invoked from <Filename>/bin</Filename> it can't
+find it.
+</Para>
+</ListItem>
+
+<ListItem>
+<Para>
+Set your <Constant>SHELL</Constant> user environment variable to <Filename>c:/bin/sh</Filename>.
+</Para>
+</ListItem>
+
+<ListItem>
+<Para>
+Set your <Filename>HOME</Filename> user environment variable to point to your
+home directory. This is where, for example,
+<Command>bash</Command> will look for your <Filename>.bashrc</Filename>
+file.
+</Para>
+</ListItem>
+
+<ListItem>
+<Para>
+Set your <Constant>MAKE_MODE</Constant> user environment variable 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>
+</ListItem>
+
+<ListItem>
+<Para>
+Set the <Constant>TMPDIR</Constant> user environment variable to <Filename>/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>
+</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>
+
+</ListItem>
</VarListEntry>
<VarListEntry>
<ListItem>
<Para>
-Packaged up using an installer that should be familiar-looking to
-Windows users. Unpack and double click on <Filename>setup.exe</Filename>.
+(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>.
</Para>
<Para>