Rewrite introductory section, and remove old section. (It was already commented-out, but why keep it?)

Doc/library/profile.rst

@@ -41,82 +41,49 @@ Introduction to the profilers
    single: deterministic profiling
    single: profiling, deterministic
 
-A :dfn:`profiler` is a program that describes the run time performance of a
-program, providing a variety of statistics.  This documentation describes the
-profiler functionality provided in the modules :mod:`profile` and :mod:`pstats`.
-This profiler provides :dfn:`deterministic profiling` of any Python programs.
-It also provides a series of report generation tools to allow users to rapidly
+A :dfn:`profiler` is a program that describes the run time performance
+of a program, providing a variety of statistics.  This documentation
+describes the profiler functionality provided in the modules
+:mod:`cProfile`, :mod:`profile` and :mod:`pstats`.  This profiler
+provides :dfn:`deterministic profiling` of Python programs.  It also
+provides a series of report generation tools to allow users to rapidly
 examine the results of a profile operation.
 
 The Python standard library provides three different profilers:
 
-#. :mod:`profile`, a pure Python module, described in the sequel. Copyright ©
-   1994, by InfoSeek Corporation.
-
-   .. versionchanged:: 2.4
-      also reports the time spent in calls to built-in functions and methods.
-
-#. :mod:`cProfile`, a module written in C, with a reasonable overhead that makes
-   it suitable for profiling long-running programs. Based on :mod:`lsprof`,
-   contributed by Brett Rosen and Ted Czotter.
+#. :mod:`cProfile` is recommended for most users; it's a C extension 
+   with reasonable overhead
+   that makes it suitable for profiling long-running programs. 
+   Based on :mod:`lsprof`,
+   contributed by Brett Rosen and Ted Czotter.  
 
    .. versionadded:: 2.5
 
-#. :mod:`hotshot`, a C module focusing on minimizing the overhead while
-   profiling, at the expense of long data post-processing times.
+#. :mod:`profile`, a pure Python module whose interface is imitated by
+   :mod:`cProfile`.  Adds significant overhead to profiled programs. 
+   If you're trying to extend 
+   the profiler in some way, the task might be easier with this module.
+   Copyright © 1994, by InfoSeek Corporation.
+
+   .. versionchanged:: 2.4
+      Now also reports the time spent in calls to built-in functions and methods.
+
+#. :mod:`hotshot` was an experimental C module that focused on minimizing
+   the overhead of profiling, at the expense of longer data
+   post-processing times.  It is no longer maintained and may be
+   dropped in a future version of Python.
+ 
 
    .. versionchanged:: 2.5
-      the results should be more meaningful than in the past: the timing core
+      The results should be more meaningful than in the past: the timing core
       contained a critical bug.
 
 The :mod:`profile` and :mod:`cProfile` modules export the same interface, so
-they are mostly interchangeables; :mod:`cProfile` has a much lower overhead but
-is not so far as well-tested and might not be available on all systems.
+they are mostly interchangeable; :mod:`cProfile` has a much lower overhead but
+is newer and might not be available on all systems.
 :mod:`cProfile` is really a compatibility layer on top of the internal
-:mod:`_lsprof` module.  The :mod:`hotshot` module is reserved to specialized
-usages.
-
-.. \section{How Is This Profiler Different From The Old Profiler?}
-   \nodename{Profiler Changes}
-   
-   (This section is of historical importance only; the old profiler
-   discussed here was last seen in Python 1.1.)
-   
-   The big changes from old profiling module are that you get more
-   information, and you pay less CPU time.  It's not a trade-off, it's a
-   trade-up.
-   
-   To be specific:
-   
-   \begin{description}
-   
-   \item[Bugs removed:]
-   Local stack frame is no longer molested, execution time is now charged
-   to correct functions.
-   
-   \item[Accuracy increased:]
-   Profiler execution time is no longer charged to user's code,
-   calibration for platform is supported, file reads are not done \emph{by}
-   profiler \emph{during} profiling (and charged to user's code!).
-   
-   \item[Speed increased:]
-   Overhead CPU cost was reduced by more than a factor of two (perhaps a
-   factor of five), lightweight profiler module is all that must be
-   loaded, and the report generating module (\module{pstats}) is not needed
-   during profiling.
-   
-   \item[Recursive functions support:]
-   Cumulative times in recursive functions are correctly calculated;
-   recursive entries are counted.
-   
-   \item[Large growth in report generating UI:]
-   Distinct profiles runs can be added together forming a comprehensive
-   report; functions that import statistics take arbitrary lists of
-   files; sorting criteria is now based on keywords (instead of 4 integer
-   options); reports shows what functions were profiled as well as what
-   profile file was referenced; output format has been improved.
-   
-   \end{description}
+:mod:`_lsprof` module.  The :mod:`hotshot` module is reserved for specialized
+usage.
 
 
 .. _profile-instant: