From 586149353a755cf7ba7c0bd499a397c3c8230839 Mon Sep 17 00:00:00 2001
From: Pepe Iborra <mnislaih@gmail.com>
Date: Sun, 7 Jan 2007 19:12:27 +0000
Subject: [PATCH] Extended the debugger documentation with a 'tips' section

---
 docs/users_guide/ghci.xml |   42 ++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 40 insertions(+), 2 deletions(-)

diff --git a/docs/users_guide/ghci.xml b/docs/users_guide/ghci.xml
index 94d352b..e722739 100644
--- a/docs/users_guide/ghci.xml
+++ b/docs/users_guide/ghci.xml
@@ -1641,6 +1641,7 @@ qsort2.hs:2:15-46>
       type to do its work. </para>
       <para> Let's go on with the debugging session of the <code>qsort</code>
       example:
+<example id="debuggingEx"><title>A short debugging session</title>
 <programlisting>
 qsort2.hs:2:15-46> x
 This is an untyped, unevaluated computation. You can use seq to 
@@ -1658,7 +1659,7 @@ x - 10
 qsort2.hs:2:15-46> :t x <co id="seq5"/>
 x :: Int
 </programlisting>
-
+</example>
       <calloutlist>
 	<callout arearefs="seq1">
 	  <para>GHCi reminds us that this value is untyped, and instructs us to force its evaluation </para>
@@ -1767,7 +1768,44 @@ x :: Int
       </itemizedlist>      
      </para>
     </sect2>
-    </sect1>
+    <sect2><title>Tips</title>
+      <variablelist>
+	<varlistentry><term>* Use PRAGMAs to fine tune which modules are loaded under debugging mode</term>
+	  <listitem>
+	    <programlisting>{-# OPTIONS_GHC -fdebugging #-}</programlisting>
+	  </listitem>
+	</varlistentry>
+	<varlistentry> <term>* Repeated use of <code>seq</code> and 
+	    <literal>:print</literal> may be necessary to observe unevaluated
+	    untyped bindings</term> 
+	  <listitem><para>see <xref linkend="debuggingEx"/> 
+	  </para></listitem>
+	</varlistentry>
+	<varlistentry> <term> * <code>GHC.Exts.unsafeCoerce</code> can help if you are positive about the type of a binding</term> 
+	  <listitem><para><programlisting>
+type MyLongType a = [Maybe [Maybe a]]
+
+main:Main> :m +GHC.Exts
+main:Main> main
+Local bindings in scope:
+  x :: a
+Main.hs:15> let x' = unsafeCoerce x :: MyLongType Bool
+Main.hs:15> x'
+[Just [Just False, Just True]]
+	  </programlisting>
+	   Note that a wrong coercion will likely result in your debugging session being interrupted by a segmentation fault 
+	  </para></listitem>
+	</varlistentry>
+	<varlistentry> <term> * The undocumented (and unsupported) &colon;force command </term>
+	  <listitem><para> 
+	      equivalent to <literal> :print</literal> with automatic 
+	      <code>seq</code> forcing, 
+	      may prove useful to replace sequences of <code>seq</code> and 
+	      <literal>&colon;print</literal> in some situations. 
+	  </para></listitem>
+	</varlistentry> 
+    </variablelist>
+    </sect2></sect1>
   <sect1 id="ghci-dot-files">
     <title>The <filename>.ghci</filename> file</title>
     <indexterm><primary><filename>.ghci</filename></primary><secondary>file</secondary>
-- 
1.7.10.4