Make a start on a Profiling section in the lispref

* doc/lispref/debugging.texi (Profiling): New section, in progress.
* doc/lispref/tips.texi (Compilation Tips): Move profiling to separate section.
* doc/lispref/elisp.texi: Add Profiling to detailed menu.

4 files changed, 49 insertions, 12 deletions

diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index bdf4ef13488..9d71d4b4420 100644
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,3 +1,9 @@
+2012-11-20  Glenn Morris  <rgm@gnu.org>
+
+        * debugging.texi (Profiling): New section, in progress.
+        * tips.texi (Compilation Tips): Move profiling to separate section.
+        * elisp.texi: Add Profiling to detailed menu.
+
 2012-11-18  Martin Rudalics  <rudalics@gmx.at>
 
         * windows.texi (Display Action Functions): Fix recently added
diff --git a/doc/lispref/debugging.texi b/doc/lispref/debugging.texi
index 11532b19781..53d739f2295 100644
--- a/doc/lispref/debugging.texi
+++ b/doc/lispref/debugging.texi
@@ -43,6 +43,7 @@ function (@pxref{Terminal Output}).
 * Edebug::              A source-level Emacs Lisp debugger.
 * Syntax Errors::       How to find syntax errors.
 * Test Coverage::       Ensuring you have tested all branches in your code.
+* Profiling::           Measuring the resources that your code uses.
 @end menu
 
 @node Debugger
@@ -809,3 +810,42 @@ never return.  If it ever does return, you get a run-time error.
   Edebug also has a coverage testing feature (@pxref{Coverage
 Testing}).  These features partly duplicate each other, and it would
 be cleaner to combine them.
+
+
+@node Profiling
+@section Profiling
+@cindex profiling
+@cindex measuring resource usage
+@cindex memory usage
+
+If your program is working correctly, but you want to make it run more
+quickly or efficiently, the first thing to do is @dfn{profile} your
+code that you know how it is using resources.  If you find that one
+particular function is responsible for a significant portion of the
+runtime, you can start by looking for ways to optimize that piece.
+
+Emacs has built-in support for this.  To begin profiling, type
+@kbd{M-x profiler-start}.  You can choose to profile by processor
+usage, memory usage, or both.  After doing some work, type
+@kbd{M-x profiler-report} to display a summary buffer for each
+resource that you chose to profile.  The names of the report buffers
+include the times at which the reports were generated, so you can
+generate another report later on without erasing previous results.
+When you have finished profiling, type @kbd{M-x profiler-stop} (there
+is a small overhead associated with profiling).
+
+@c FIXME
+@c Basic apperance of the report buffer:
+
+@c The following commands are available in the report buffer:
+
+@cindex @file{elp.el}
+@cindex timing programs
+The @file{elp} library offers an alternative approach.  See the file
+@file{elp.el} for instructions.
+
+@cindex @file{benchmark.el}
+@cindex benchmarking
+You can check the speed of individual Emacs Lisp forms using the
+@file{benchmark} library.  See the functions @code{benchmark-run} and
+@code{benchmark-run-compiled} in @file{benchmark.el}.
diff --git a/doc/lispref/elisp.texi b/doc/lispref/elisp.texi
index a70558bf09f..cb00b5e9889 100644
--- a/doc/lispref/elisp.texi
+++ b/doc/lispref/elisp.texi
@@ -617,6 +617,7 @@ Debugging Lisp Programs
 * Edebug::                  A source-level Emacs Lisp debugger.
 * Syntax Errors::           How to find syntax errors.
 * Test Coverage::           Ensuring you have tested all branches in your code.
+* Profiling::               Measuring the resources that your code uses.
 
 The Lisp Debugger
 
diff --git a/doc/lispref/tips.texi b/doc/lispref/tips.texi
index 4336baa128f..bba416d5614 100644
--- a/doc/lispref/tips.texi
+++ b/doc/lispref/tips.texi
@@ -460,18 +460,8 @@ Lisp programs.
 
 @itemize @bullet
 @item
-@cindex profiling
-@cindex timing programs
-@cindex @file{elp.el}
-Profile your program with the @file{elp} library.  See the file
-@file{elp.el} for instructions.
-
-@item
-@cindex @file{benchmark.el}
-@cindex benchmarking
-Check the speed of individual Emacs Lisp forms using the
-@file{benchmark} library.  See the functions @code{benchmark-run} and
-@code{benchmark-run-compiled} in @file{benchmark.el}.
+Profile your program, to find out where the time is being spent.
+@xref{Profiling}.
 
 @item
 Use iteration rather than recursion whenever possible.