exporting patch:
# HG changeset patch
# User Daniel Kraft <address@hidden>
# Date 1313685838 -7200
# Node ID 2e20c26b10075fe6521d5884a9fe27e01e6f1f91
# Parent  6590446c2498ab12e775bfeaa06d34d6cfccbd04
Document the profiler functions.

debug.txi: Document profile and profshow in the manual.

diff -r 6590446c2498 -r 2e20c26b1007 doc/interpreter/debug.txi
--- a/doc/interpreter/debug.txi	Tue Aug 16 22:19:56 2011 -0700
+++ b/doc/interpreter/debug.txi	Thu Aug 18 18:43:58 2011 +0200
@@ -35,6 +35,7 @@
 * Breakpoints::
 * Debug Mode::
 * Call Stack::
+* Profiling::
 @end menu
 
 @node Entering Debug Mode
@@ -182,3 +183,44 @@
 @DOCSTRING(dbup)
 
 @DOCSTRING(dbdown)
+
address@hidden Profiling
address@hidden Profiling
address@hidden profiler
address@hidden code profiling
+
+Octave supports profiling of code-execution on a per-function level.  If
+profiling is enabled, each call to a function (supporting built-ins,
+operators, functions in oct- and mex- files, user-defined functions
+in Octave code and anonymous functions) is recorded while running
+Octave code.  After that, this data can aid in analyzing the code-behaviour,
+and is in particular helpful for finding ``hot spots'' in the code
+which use up a lot of computation time and are the best targets to spend
+optimization efforts on.
+
+The main command for profiling is @code{profile}, which can be used
+to start / stop the profiler and also to query collected data afterwards.
+The data is returned in an Octave data-structure which can then be
+examined or further processed by other routines or tools.
+
address@hidden(profile)
+
+An easy way to get an overview over the collected data is @code{profshow}.
+This function takes the profiler-data returned by @code{profile} as input
+and prints a flat profile, for instance:
+
address@hidden
+ Function Attr     Time (s)        Calls
+----------------------------------------
+   >myfib    R        2.195        13529
+binary <=             0.061        13529
+ binary -             0.050        13528
+ binary +             0.026         6764
address@hidden example
+
+This shows that most of the runtime was spent executing the function
address@hidden, and some minor proportion evaluating the listed binary operators.
+Furthermore, it is shown how often the function was called and the profiler
+also found out that it is recursive.
+
address@hidden(profshow)