scratch/bulk-tracing d596474af0 3/3: WIP: Add a 'tracing' section to the elisp manual debugging node

[Phil Sainty]

branch: scratch/bulk-tracing
commit d596474af03d2eba2986af5588fc66a817cdc747
Author: Phil Sainty <psainty@orcon.net.nz>
Commit: Phil Sainty <psainty@orcon.net.nz>

    WIP: Add a 'tracing' section to the elisp manual debugging node
---
 doc/lispref/debugging.texi | 152 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 152 insertions(+)

diff --git a/doc/lispref/debugging.texi b/doc/lispref/debugging.texi
index 9fbf3a69f0..afb4e4cbd7 100644
--- a/doc/lispref/debugging.texi
+++ b/doc/lispref/debugging.texi
@@ -1074,3 +1074,155 @@ the @command{gprof} utility.  This feature is mainly 
useful for
 debugging Emacs.  It actually stops the Lisp-level @kbd{M-x
 profiler-@dots{}} commands described above from working.
 @end ifnottex
+
+
+@node Tracing
+@section Tracing
+@cindex tracing
+@cindex trace
+@cindex trace function
+@cindex trace functions
+
+You can trace the execution of functions using the tracing facilities
+provided by the @file{trace.el} package.  Many functions may be traced
+at the same time.  The functions @code{trace-function-foreground} and
+@code{trace-function-background} add a new trace to a single specified
+function.  The functions @code{trace-package}, @code{trace-regexp},
+and @code{trace-library} enable traces to be added to multiple
+functions in bulk.  Calls to traced functions, including the values
+of their arguments, are logged to the @file{*trace-output*} buffer
+(or another buffer as specified).
+
+In addition, you can call @code{trace-values} in your code to output
+the values of its arguments to the trace buffer, to provide more trace
+information than is provided by the function calls alone.
+
+@deffn Command trace-function-foreground function &optional buffer context
+This function adds a foreground trace to @var{function}.  When called
+interactively, it prompts for @var{function} in the minibuffer.  With
+a prefix argument, also prompt for the trace output @var{buffer}
+(defaulting to the value of @var{trace-buffer}), and a Lisp expression
+@var{context}.  When called from Lisp, @var{context} should be a
+function of no arguments which returns a value to insert into
+@var{buffer} during the trace.
+
+Tracing a function causes every call to that function to insert into
+@var{buffer} Lisp-style trace messages that display the function's
+arguments and return values.  It also evaluates @var{context}, if that
+is non-nil, and inserts its value too.  For example, you can use this
+to track the current buffer, or position of point.
+
+This function creates @var{buffer} if it does not exist.  This buffer
+will popup whenever FUNCTION is called.  Do not use this function to
+trace functions that switch buffers, or do any other display-oriented
+stuff - use `trace-function-background' instead.
+
+Calling `trace-function-foreground' again for the same FUNCTION will
+update the optional argument behaviours to respect the new values.
+@end defun
+
+@deffn Command trace-function-background function &optional buffer context
+This function adds a background trace to @var{function}.  This is like
+@code{trace-function-foreground}, but without popping up the output
+buffer or changing the window configuration.
+@end defun
+
+@deffn Command trace-package prefix &optional after-load buffer context
+This function calls @code{trace-function-background} for all functions
+with names starting with @var{prefix}.
+
+For any autoload declarations matching @var{prefix}, the associated
+function will be traced if and when it is defined.
+
+With a prefix argument, also prompt for the optional arguments.  If
+AFTER-LOAD is non-nil then re-process @var{prefix} after loading any
+file.  See `trace-function-foreground' for details of @var{buffer} and
+@var{context}, and of foreground vs background tracing.
+
+Calling `trace-package' again for the same @var{prefix} will update
+the optional argument behaviours to respect the new values.
+@end defun
+
+@deffn Command trace-regexp regexp &optional after-load buffer context
+This function calls @code{trace-function-background} for all functions
+matching in @var{regexp}.
+
+Warning: Do not attempt to trace all functions.  Tracing too many
+functions at one time will render Emacs unusable.
+
+Background tracing is used.  Switch to the trace output buffer to view
+the results.  For any autoload declarations matching @var{regexp}, the
+associated function will be traced if and when it is defined.
+
+With a prefix argument, also prompt for the optional arguments.  If
+AFTER-LOAD is non-nil then re-process @var{regexp} after loading any
+file.  See `trace-function-foreground' for details of @var{buffer} and
+@var{context}, and of foreground vs background tracing.
+
+Calling `trace-regexp' again for the same @var{regexp} will update the
+optional argument behaviours to respect the new values.
+@end defun
+
+@deffn Command trace-library library &optional after-load buffer context
+This function calls @code{trace-function-background} for all functions
+defined in @var{library}.
+
+For any autoload declarations with a file name matching @var{library},
+the associated function will be traced if and when it is defined.
+(Autoload file names will not match if @var{library} specifies a
+longer, more specific path.)
+
+With a prefix argument, also prompt for the optional arguments.  If
+AFTER-LOAD is non-nil then re-process @var{library} after loading it
+\(ensuring that all of its functions will be traced).  See
+`trace-function-foreground' for details of @var{buffer} and
+@var{context}, and of foreground vs background tracing.
+
+Calling `trace-library' again for the same @var{library} will update
+the optional argument behaviours to respect the new values.
+@end defun
+
+@deffn Command trace-currently-traced &optional display-message
+This function returns the list of currently traced function symbols.
+When called interactively, or if @var{display-message} is non-nil, it
+displays the list as a message.
+@end defun
+
+@deffn Command untrace-function function
+This function removes the trace on @var{function}.  When called
+interactively, it prompts for @var{function} in the minibuffer.
+Calling @code{untrace-function} has no effect if @var{function} is not
+currently traced.
+@end defun
+
+@deffn Command untrace-package prefix
+This function calls @code{untrace-function} for all functions with
+names starting with @var{prefix}.  When called interactively, it
+prompts for @var{prefix} in the minibuffer.
+@end defun
+
+@deffn Command untrace-regexp regexp
+This function calls @code{untrace-function} for all functions matching
+@var{regexp}.  When called interactively, it prompts for @var{regexp}
+in the minibuffer.
+@end defun
+
+@deffn Command untrace-library library
+This function calls @code{untrace-function} for all functions defined
+in @var{library}.  When called interactively, it prompts for
+@var{library} in the minibuffer.
+@end defun
+
+@deffn Command untrace-all
+This function calls @code{untrace-function} for all functions.
+@end defun
+
+@deffn Function trace-values &rest values
+This function inserts a message showing @var{values} into the trace
+buffer.  You can add explicit calls to @code{trace-values} into your
+functions in order to provide additional tracing information.
+@end defun
+
+@defvar Variable inhibit-trace
+If non-nil, all tracing is inhibited.
+@end defvar