Update docs on ticky-ticky profiling

3 files changed, 50 insertions, 30 deletions

diff --git a/docs/users_guide/flags.xml b/docs/users_guide/flags.xml
index 75d240c528..cd6b5b38f9 100644
--- a/docs/users_guide/flags.xml
+++ b/docs/users_guide/flags.xml
@@ -1556,7 +1556,7 @@ phase <replaceable>n</replaceable></entry>
 	    </row>
 	    <row>
 	      <entry><option>-ticky</option></entry>
-	      <entry>Turn on ticky-ticky profiling</entry>
+	      <entry><link linkend="ticky-ticky">Turn on ticky-ticky profiling</link></entry>
 	      <entry>static</entry>
 	      <entry>-</entry>
 	    </row>
diff --git a/docs/users_guide/profiling.xml b/docs/users_guide/profiling.xml
index 0410d9e32e..0138e57d81 100644
--- a/docs/users_guide/profiling.xml
+++ b/docs/users_guide/profiling.xml
@@ -1596,13 +1596,13 @@ Options:
 
     <para>(ToDo: document properly.)</para>
 
-    <para>It is possible to compile Glasgow Haskell programs so that
+    <para>It is possible to compile Haskell programs so that
     they will count lots and lots of interesting things, e.g., number
     of updates, number of data constructors entered, etc., etc.  We
     call this &ldquo;ticky-ticky&rdquo;
     profiling,<indexterm><primary>ticky-ticky
     profiling</primary></indexterm> <indexterm><primary>profiling,
-    ticky-ticky</primary></indexterm> because that's the sound a Sun4
+    ticky-ticky</primary></indexterm> because that's the sound a CPU
     makes when it is running up all those counters
     (<emphasis>slowly</emphasis>).</para>
 
@@ -1610,25 +1610,52 @@ Options:
     it is quite separate from the main &ldquo;cost-centre&rdquo;
     profiling system, intended for all users everywhere.</para>
 
-    <para>To be able to use ticky-ticky profiling, you will need to
-    have built the ticky RTS. (This should be described in 
-    the building guide, but amounts to building the RTS with way
-    "t" enabled.)</para>
+    <para>
+      You don't need to build GHC, the libraries, or the RTS a special
+      way in order to use ticky-ticky profiling.  You can decide on a
+      module-by-module basis which parts of a program have the
+      counters compiled in, using the
+      compile-time <option>-ticky</option> option.  Those modules that
+      were not compiled with <option>-ticky</option> won't contribute
+      to the ticky-ticky profiling results, and that will normally
+      include all the pre-compiled packages that your program links
+      with.
+    </para>
 
-    <para>To get your compiled program to spit out the ticky-ticky
-    numbers, use a <option>-r</option> RTS
-    option<indexterm><primary>-r RTS option</primary></indexterm>.
-    See <xref linkend="runtime-control"/>.</para>
+    <para>
+      To get your compiled program to spit out the ticky-ticky
+      numbers:
 
-    <para>Compiling your program with the <option>-ticky</option>
-    switch yields an executable that performs these counts.  Here is a
-    sample ticky-ticky statistics file, generated by the invocation
-    <command>foo +RTS -rfoo.ticky</command>.</para>
+      <itemizedlist>
+        <listitem>
+          <para>
+            Link the program with <option>-debug</option>
+            (<option>-ticky</option> is a synonym
+            for <option>-debug</option> at link-time).  This links in
+            the debug version of the RTS, which includes the code for
+            aggregating and reporting the results of ticky-ticky
+            profilng.
+          </para>
+        </listitem>
+        <listitem>
+          <para>
+            Run the program with the <option>-r</option> RTS
+            option<indexterm><primary>-r RTS option</primary></indexterm>.
+            See <xref linkend="runtime-control"/>.
+          </para>
+        </listitem>
+      </itemizedlist>
+    </para>
 
+    <para>
+      Here is a sample ticky-ticky statistics file, generated by
+      the invocation
+      <command>foo +RTS -rfoo.ticky</command>.
+      </para>
+    
 <screen>
  foo +RTS -rfoo.ticky
 
-
 ALLOCATIONS: 3964631 (11330900 words total: 3999476 admin, 6098829 goods, 1232595 slop)
                                 total words:        2     3     4     5    6+
   69647 (  1.8%) function values                 50.0  50.0   0.0   0.0   0.0
diff --git a/docs/users_guide/runtime_control.xml b/docs/users_guide/runtime_control.xml
index 2b16234496..c482a28a91 100644
--- a/docs/users_guide/runtime_control.xml
+++ b/docs/users_guide/runtime_control.xml
@@ -973,20 +973,13 @@
         </term>
 	<listitem>
 	  <para>Produce &ldquo;ticky-ticky&rdquo; statistics at the
-          end of the program run.  The <replaceable>file</replaceable>
-          business works just like on the <option>-S</option> RTS
-          option (above).</para>
-
-	  <para>&ldquo;Ticky-ticky&rdquo; statistics are counts of
-          various program actions (updates, enters, etc.)  The program
-          must have been compiled using
-          <option>-ticky</option><indexterm><primary><option>-ticky</option></primary></indexterm>
-          (a.k.a. &ldquo;ticky-ticky profiling&rdquo;), and, for it to
-          be really useful, linked with suitable system libraries.
-          Not a trivial undertaking: consult the installation guide on
-          how to set things up for easy &ldquo;ticky-ticky&rdquo;
-          profiling.  For more information, see <xref
-          linkend="ticky-ticky"/>.</para>
+          end of the program run (only available if the program was
+          linked with <option>-debug</option>).
+          The <replaceable>file</replaceable> business works just like
+          on the <option>-S</option> RTS option, above.</para>
+
+          <para>For more information on ticky-ticky profiling, see
+          <xref linkend="ticky-ticky"/>.</para>
 	</listitem>
       </varlistentry>