Add documentation for -interactive-print (#5461)

Based on a patch by Vitaly Bragilevsky <bravit111@gmail.com>

2 files changed, 62 insertions, 0 deletions

diff --git a/docs/users_guide/flags.xml b/docs/users_guide/flags.xml
index 3b4f36db6c..11e4f8f7d3 100644
--- a/docs/users_guide/flags.xml
+++ b/docs/users_guide/flags.xml
@@ -535,6 +535,13 @@
             <entry>dynamic</entry>
             <entry>-</entry>
           </row>
+          <row>
+            <entry><option>-interactive-print</option></entry>
+            <entry><link linkend="ghci-interactive-print">Select the function
+                    to use for printing evaluated expressions in GHCi</link></entry>
+            <entry>dynamic</entry>
+            <entry>-</entry>
+          </row>
 
         </tbody>
       </tgroup>
diff --git a/docs/users_guide/ghci.xml b/docs/users_guide/ghci.xml
index 3d629db9a6..5726a41baf 100644
--- a/docs/users_guide/ghci.xml
+++ b/docs/users_guide/ghci.xml
@@ -1090,6 +1090,61 @@ def = toEnum 0
     printf.
    </para>
     </sect2>
+   <sect2 id="ghci-interactive-print">
+     <title>Using a custom interactive printing function</title>
+     <para>[<emphasis role="bold">New in version 7.6.1</emphasis>]
+        By default, GHCi prints the result of expressions typed at the prompt
+        using the function <literal>System.IO.print</literal>. Its type
+        signature is <literal>Show a => a -> IO ()</literal>, and it works by
+        converting the value to <literal>String</literal> using
+        <literal>show</literal>.
+     </para>
+     <para>
+        This is not ideal in certain cases, like when the output is long, or
+        contains strings with non-ascii characters.
+     </para>
+     <para>
+       The <literal>-interactive-print</literal> flag allows to specify any
+       function of type <literal>C a => a -> IO ()</literal>, for some
+       constraint <literal>C</literal>, as the function for printing evaluated
+       expressions. The function can reside in any loaded module or any
+       registered package.
+     </para>
+     <para>
+       As an example, suppose we have following special printing module:
+       <programlisting>
+	 module SpecPrinter where
+	 import System.IO
+
+	 sprint a = putStrLn $ show a ++ "!"
+       </programlisting>
+       The <literal>sprint</literal> function adds an exclamation mark at the
+       end of any printed value. Running GHCi with the command:
+       <programlisting>
+	 ghci -interactive-print=SpecPrinter.sprinter SpecPrinter
+       </programlisting>
+       will start an interactive session where values with be printed using
+       <literal>sprint</literal>:
+       <programlisting>
+	 *SpecPrinter> [1,2,3]
+	 [1,2,3]!
+	 *SpecPrinter> 42
+	 42!
+       </programlisting>
+     </para>
+     <para>
+       A custom pretty printing function can be used, for example, to format
+       tree-like and nested structures in a more readable way.
+     </para>
+     <para>
+       The <literal>-interactive-print</literal> flag can also be used when
+       running GHC in <literal>-e mode</literal>:
+       <programlisting>
+	 % ghc -e "[1,2,3]" -interactive-print=SpecPrinter.sprint SpecPrinter
+	 [1,2,3]!
+       </programlisting>
+     </para>
+   </sect2>
   </sect1>
 
   <sect1 id="ghci-debugger">