Better document :stepover and its limitations

[ghc-hetmet.git] / docs / users_guide / ghci.xml

diff --git a/docs/users_guide/ghci.xml b/docs/users_guide/ghci.xml
index c0167bf..a8ebbd7 100644 (file)
--- a/docs/users_guide/ghci.xml
+++ b/docs/users_guide/ghci.xml
@@ -1106,10 +1106,12 @@ right :: [a]
 
       <para>Single-stepping is a great way to visualise the execution of your
         program, and it is also a useful tool for identifying the source of a
-        bug.  The concept is simple: single-stepping enables all the
-        breakpoints in the program and executes until the next breakpoint is
-        reached, at which point you can single-step again, or continue
-        normally.  For example:</para>
+        bug. GHCi offers two variants of stepping. Use 
+       <literal>:step</literal>  to enable all the
+        breakpoints in the program, and execute until the next breakpoint is
+        reached. Use <literal>:stepover</literal> to step over function
+       applications, which of course are executed all the same. 
+       For example:</para>
 
 <screen>
 *Main> :step main
@@ -1118,10 +1120,11 @@ _result :: IO ()
 </screen>
 
       <para>The command <literal>:step
-          <replaceable>expr</replaceable></literal> begins the evaluation of
+        <replaceable>expr</replaceable></literal> begins the evaluation of
         <replaceable>expr</replaceable> in single-stepping mode.  If
         <replaceable>expr</replaceable> is ommitted, then it single-steps from
-        the current breakpoint.</para>
+        the current breakpoint. <literal>:stepover</literal> 
+        works similarly.</para>
 
       <para>The <literal>:list</literal> command is particularly useful when
         single-stepping, to see where you currently are:</para>
@@ -1923,6 +1926,12 @@ Prelude> :. cmds.ghci
          will be printed.  If <replaceable>name</replaceable> has
          been loaded from a source file, then GHCi will also display
          the location of its definition in the source.</para>
+         <para>For types and classes, GHCi also summarises instances that
+         mention them.  To avoid showing irrelevant information, an instance
+         is shown only if (a) its head mentions <replaceable>name</replaceable>, 
+         and (b) all the other things mentioned in the instance
+         are in scope (either qualified or otherwise) as a result of 
+         a <literal>:load</literal> or <literal>:module</literal> commands. </para>
        </listitem>
       </varlistentry>
 
@@ -2587,6 +2596,18 @@ Prelude> :set -fno-glasgow-exts
           <para>See <xref linkend="ghci-windows"/>.</para>
         </listitem>
       </varlistentry>
+
+      <varlistentry>
+       <term>The default buffering mode is different in GHCi to GHC.</term>
+        <listitem>
+          <para>
+            In GHC, the stdout handle is line-buffered by default.
+            However, in GHCi we turn off the buffering on stdout,
+            because this is normally what you want in an interpreter:
+            output appears as it is generated.
+          </para>
+        </listitem>
+      </varlistentry>
     </variablelist>
   </sect1>