From 949ce3bb4ef2654a814b3549051e439daf82b5e9 Mon Sep 17 00:00:00 2001
From: Simon Marlow <marlowsd@gmail.com>
Date: Thu, 19 Jun 2008 12:12:01 +0000
Subject: [PATCH] Document the change to +RTS -S/-s/-t

---
 docs/users_guide/runtime_control.xml |   53 ++++++++++++++--------------------
 docs/users_guide/sooner.xml          |    8 ++---
 docs/users_guide/using.xml           |    2 +-
 3 files changed, 26 insertions(+), 37 deletions(-)

diff --git a/docs/users_guide/runtime_control.xml b/docs/users_guide/runtime_control.xml
index 183cd9c..725ee88 100644
--- a/docs/users_guide/runtime_control.xml
+++ b/docs/users_guide/runtime_control.xml
@@ -436,46 +436,35 @@
       </varlistentry>
 
       <varlistentry>
+        <term>
+          <option>-t</option><optional><replaceable>file</replaceable></optional>
+          <indexterm><primary><option>-t</option></primary><secondary>RTS option</secondary></indexterm>
+        </term>
 	<term>
-          <option>-s</option><replaceable>file</replaceable>
+          <option>-s</option><optional><replaceable>file</replaceable></optional>
           <indexterm><primary><option>-s</option></primary><secondary>RTS option</secondary></indexterm>
         </term>
 	<term>
-          <option>-S</option><replaceable>file</replaceable>
+          <option>-S</option><optional><replaceable>file</replaceable></optional>
           <indexterm><primary><option>-S</option></primary><secondary>RTS option</secondary></indexterm>
         </term>
 	<listitem>
-	  <para>Write modest (<option>-s</option>) or verbose
-          (<option>-S</option>) garbage-collector statistics into file
-          <replaceable>file</replaceable>. The default
-          <replaceable>file</replaceable> is
-          <filename><replaceable>program</replaceable>.stat</filename>. The
-          <replaceable>file</replaceable> <constant>stderr</constant>
-          is treated specially, with the output really being sent to
-          <constant>stderr</constant>.</para>
-
-	  <para>This option is useful for watching how the storage
-          manager adjusts the heap size based on the current amount of
-          live data.</para>
-	</listitem>
-      </varlistentry>
+	  <para>These options produce runtime-system statistics, such
+	  as the amount of time spent executing the program and in the
+	  garbage collector, the amount of memory allocated, the
+	  maximum size of the heap, and so on.  The three
+	  variants give different levels of detail:
+	  <option>-t</option> produces a single line of output in the
+	  same format as GHC's <option>-Rghc-timing</option> option,
+	  <option>-s</option> produces a more detailed summary at the
+	  end of the program, and <option>-S</option> additionally
+	  produces information about each and every garbage
+	  collection.</para>
 
-      <varlistentry>
-	<term>
-          <option>-t<replaceable>file</replaceable></option>
-          <indexterm><primary><option>-t</option></primary><secondary>RTS option</secondary></indexterm>
-        </term>
-	<listitem>
-	  <para>Write a one-line GC stats summary after running the
-	  program.  This output is in the same format as that produced
-	  by the <option>-Rghc-timing</option> option.</para>
-
-	  <para>As with <option>-s</option>, the default
-          <replaceable>file</replaceable> is
-          <filename><replaceable>program</replaceable>.stat</filename>. The
-          <replaceable>file</replaceable> <constant>stderr</constant>
-          is treated specially, with the output really being sent to
-          <constant>stderr</constant>.</para>
+          <para>The output is placed in
+          <replaceable>file</replaceable>.  If
+          <replaceable>file</replaceable> is omitted, then the output
+          is sent to <constant>stderr</constant>.</para>
 	</listitem>
       </varlistentry>
     </variablelist>
diff --git a/docs/users_guide/sooner.xml b/docs/users_guide/sooner.xml
index bb2eb87..d1aeb0f 100644
--- a/docs/users_guide/sooner.xml
+++ b/docs/users_guide/sooner.xml
@@ -32,7 +32,7 @@ should go here!</para>
           garbage collection for GHC, which means less compilation
           time.  If you use the <option>-Rghc-timing</option> option,
           you'll get a garbage-collector report.  (Again, you can use
-          the cheap-and-nasty <option>+RTS -Sstderr -RTS</option>
+          the cheap-and-nasty <option>+RTS -S -RTS</option>
           option to send the GC stats straight to standard
           error.)</para>
 
@@ -511,13 +511,13 @@ Use <literal>strip</literal> on your executables.
 
 <para>
 &ldquo;I think I have a space leak&hellip;&rdquo; Re-run your program
-with <option>+RTS -Sstderr</option>, and remove all doubt!  (You'll
+with <option>+RTS -S</option>, and remove all doubt!  (You'll
 see the heap usage get bigger and bigger&hellip;)
 &lsqb;Hmmm&hellip;this might be even easier with the
 <option>-G1</option> RTS option; so&hellip; <command>./a.out +RTS
--Sstderr -G1</command>...]
+-S -G1</command>...]
 <indexterm><primary>-G RTS option</primary></indexterm>
-<indexterm><primary>-Sstderr RTS option</primary></indexterm>
+<indexterm><primary>-S RTS option</primary></indexterm>
 </para>
 
 <para>
diff --git a/docs/users_guide/using.xml b/docs/users_guide/using.xml
index ef62d59..60b8f3e 100644
--- a/docs/users_guide/using.xml
+++ b/docs/users_guide/using.xml
@@ -1770,7 +1770,7 @@ f "2"    = 2
     <sect2>
       <title>Hints for using SMP parallelism</title>
 
-      <para>Add the <literal>-sstderr</literal> RTS option when
+      <para>Add the <literal>-s</literal> RTS option when
 	running the program to see timing stats, which will help to tell you
 	whether your program got faster by using more CPUs or not.  If the user
 	time is greater than
-- 
1.7.10.4