From c61001a6d252f2f260c271de30d76e64e4626c4f Mon Sep 17 00:00:00 2001
From: Simon Marlow <simonmar@microsoft.com>
Date: Tue, 5 Dec 2006 16:11:40 +0000
Subject: [PATCH] add Windows-specific GHCi information, and a FAQ about ^C in
 GHCi on Windows

---
 docs/users_guide/ghci.xml       |    9 ++++++++-
 docs/users_guide/win32-dlls.xml |   41 ++++++++++++++++++++++++++++++++++++++-
 2 files changed, 48 insertions(+), 2 deletions(-)

diff --git a/docs/users_guide/ghci.xml b/docs/users_guide/ghci.xml
index cd2a836..f56c079 100644
--- a/docs/users_guide/ghci.xml
+++ b/docs/users_guide/ghci.xml
@@ -1511,7 +1511,7 @@ Prelude> :set -fno-glasgow-exts
 
   </sect1>
 
-  <sect1>
+  <sect1 id="ghci-faq">
     <title>FAQ and Things To Watch Out For</title>
     
     <variablelist>
@@ -1585,6 +1585,13 @@ Prelude> :set -fno-glasgow-exts
 	</listitem>
       </varlistentry>
 
+      <varlistentry>
+	<term>I can't use Control-C to interrupt computations in
+          GHCi on Windows.</term>
+        <listitem>
+          <para>See <xref linkend="ghci-windows">.</xref></para>
+        </listitem>
+      </varlistentry>
     </variablelist>
   </sect1>
 
diff --git a/docs/users_guide/win32-dlls.xml b/docs/users_guide/win32-dlls.xml
index 959f7ce..be56591 100644
--- a/docs/users_guide/win32-dlls.xml
+++ b/docs/users_guide/win32-dlls.xml
@@ -4,7 +4,7 @@
 
 <sect1>
 <title>
-Starting GHC on Win32 platforms</title>
+Starting GHC on Windows platforms</title>
 
 <para>
 The installer that installs GHC on Win32 also sets up the file-suffix associations
@@ -36,6 +36,45 @@ Notice how the "%1" argument is quoted (or not).
 
 </sect1>
 
+<sect1 id="ghci-windows">
+<title>Running GHCi on Windows</title>
+
+  <para>We recommend running GHCi in a standard Windows console:
+  select the <literal>GHCi</literal> option from the start menu item
+  added by the GHC installer, or use
+  <literal>Start->Run->cmd</literal> to get a Windows console and
+  invoke <literal>ghci</literal> from there (as long as it's in your
+  <literal>PATH</literal>).</para>
+
+  <para>If you run GHCi in a Cygwin or MSYS shell, then the Control-C
+  behaviour is adversely affected.  In one of these environments you
+  should use the <literal>ghcii.sh</literal> script to start GHCi,
+  otherwise when you hit Control-C you'll be returned to the shell
+  prompt but the GHCi process will still be running.  However, even
+  using the <literal>ghcii.sh</literal> script, if you hit Control-C
+  then the GHCi process will be killed immediately, rather than
+  letting you interrupt a running program inside GHCi as it should.
+  This problem is caused by the fact that the Cygwin and MSYS shell
+  environments don't pass Control-C events to non-Cygwin child
+  processes, because in order to do that there needs to be a Windows
+  console.</para>
+
+  <para>There's an exception: you can use a Cygwin shell if the
+  <literal>CYGWIN</literal> environment variable does
+  <emphasis>not</emphasis> contain <literal>tty</literal>.  In this
+  mode, the Cygwin shell behaves like a Windows console shell and
+  console events are propagated to child processes.  Note that the
+  <literal>CYGWIN</literal> environment variable must be set
+  <emphasis>before</emphasis> starting the Cygwin shell; changing it
+  afterwards has no effect on the shell.</para>
+
+  <para>This problem doesn't just affect GHCi, it affects any
+  GHC-compiled program that wants to catch console events.  See the
+  <ulink
+  url="../libraries/base/GHC-ConsoleHandler.html">GHC.ConsoleHandler</ulink>
+  module.</para>
+</sect1>
+
 <sect1>
 <title>
 Interacting with the terminal</title>
-- 
1.7.10.4