7 files changed, 111 insertions, 44 deletions

diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index a5295adc368..99e21bac469 100644
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,3 +1,25 @@
+2012-11-21  Glenn Morris  <rgm@gnu.org>
+
+        * display.texi (Attribute Functions):
+        Update for set-face-* name changes.
+        Add new "inherit" argument for face-bold-p etc.
+        Move description of this argument to a common section, like "frame".
+
+        * debugging.texi (Profiling): New section.
+        (Debugging): Mention profiling in the introduction.
+        * tips.texi (Compilation Tips): Move profiling to separate section.
+        * elisp.texi: Add Profiling to detailed menu.
+
+2012-11-21  Martin Rudalics  <rudalics@gmx.at>
+
+        * windows.texi (Display Action Functions): Fix recently added
+        example.  Suggested by Michael Heerdegen.
+
+2012-11-21  Paul Eggert  <eggert@cs.ucla.edu>
+
+        Minor cleanup for times as lists of four integers.
+        * os.texi (Time Parsing): Time values can now be four integers.
+
 2012-11-18  Glenn Morris  <rgm@gnu.org>
 
         * loading.texi (How Programs Do Loading): Add eager macro expansion.
diff --git a/doc/lispref/debugging.texi b/doc/lispref/debugging.texi
index 11532b19781..3439a8ae152 100644
--- a/doc/lispref/debugging.texi
+++ b/doc/lispref/debugging.texi
@@ -32,6 +32,9 @@ program.
 @item
 You can use the ERT package to write regression tests for the program.
 @xref{Top,the ERT manual,, ERT, ERT: Emacs Lisp Regression Testing}.
+
+@item
+You can profile the program to get hints about how to make it more efficient.
 @end itemize
 
   Other useful tools for debugging input and output problems are the
@@ -43,6 +46,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 +813,63 @@ 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 so 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 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).
+
+The profiler report buffer shows, on each line, a function that was
+called, followed by how much resource (processor or memory) it used in
+absolute and percentage times since profiling started.  If a given
+line has a @samp{+} symbol at the left-hand side, you can expand that
+line by typing @key{RET}, in order to see the function(s) called by
+the higher-level function.  Pressing @key{RET} again will collapse
+back to the original state.
+
+Press @kbd{j} or @kbd{mouse-2} to jump to the definition of a function.
+Press @kbd{d} to view a function's documentation.
+You can save a profile to a file using @kbd{C-x C-w}.
+You can compare two profiles using @kbd{=}.
+
+@c FIXME reversed calltree?
+
+@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}.
+
+@c Not worth putting in the printed manual.
+@ifnottex
+@cindex --enable-profiling option of configure
+For low-level profiling of Emacs itself, you can build it using the
+@option{--enable-profiling} option of @command{configure}.  When Emacs
+exits, it generates a file @file{gmon.out} that you can examine using
+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
diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi
index 475a9550f99..5148c6ec22e 100644
--- a/doc/lispref/display.texi
+++ b/doc/lispref/display.texi
@@ -2425,12 +2425,12 @@ This sets the @code{:stipple} attribute of @var{face} to
 This sets the @code{:font} attribute of @var{face} to @var{font}.
 @end deffn
 
-@defun set-face-bold-p face bold-p &optional frame
+@defun set-face-bold face bold-p &optional frame
 This sets the @code{:weight} attribute of @var{face} to @var{normal}
 if @var{bold-p} is @code{nil}, and to @var{bold} otherwise.
 @end defun
 
-@defun set-face-italic-p face italic-p &optional frame
+@defun set-face-italic face italic-p &optional frame
 This sets the @code{:slant} attribute of @var{face} to @var{normal} if
 @var{italic-p} is @code{nil}, and to @var{italic} otherwise.
 @end defun
@@ -2440,7 +2440,7 @@ This sets the @code{:underline} attribute of @var{face} to
 @var{underline}.
 @end defun
 
-@defun set-face-inverse-video-p face inverse-video-p &optional frame
+@defun set-face-inverse-video face inverse-video-p &optional frame
 This sets the @code{:inverse-video} attribute of @var{face} to
 @var{inverse-video-p}.
 @end defun
@@ -2453,59 +2453,48 @@ This swaps the foreground and background colors of face @var{face}.
 don't specify @var{frame}, they refer to the selected frame; @code{t}
 refers to the default data for new frames.  They return the symbol
 @code{unspecified} if the face doesn't define any value for that
-attribute.
+attribute.  If @var{inherit} is @code{nil}, only an attribute directly
+defined by the face is returned.  If @var{inherit} is non-@code{nil},
+any faces specified by its @code{:inherit} attribute are considered as
+well, and if @var{inherit} is a face or a list of faces, then they are
+also considered, until a specified attribute is found.  To ensure that
+the return value is always specified, use a value of @code{default} for
+@var{inherit}.
+
+@defun face-font face &optional frame
+This function returns the name of the font of face @var{face}.
+@end defun
 
 @defun face-foreground face &optional frame inherit
 @defunx face-background face &optional frame inherit
 These functions return the foreground color (or background color,
 respectively) of face @var{face}, as a string.
-
-If @var{inherit} is @code{nil}, only a color directly defined by the face is
-returned.  If @var{inherit} is non-@code{nil}, any faces specified by its
-@code{:inherit} attribute are considered as well, and if @var{inherit}
-is a face or a list of faces, then they are also considered, until a
-specified color is found.  To ensure that the return value is always
-specified, use a value of @code{default} for @var{inherit}.
 @end defun
 
 @defun face-stipple face &optional frame inherit
 This function returns the name of the background stipple pattern of face
 @var{face}, or @code{nil} if it doesn't have one.
-
-If @var{inherit} is @code{nil}, only a stipple directly defined by the
-face is returned.  If @var{inherit} is non-@code{nil}, any faces
-specified by its @code{:inherit} attribute are considered as well, and
-if @var{inherit} is a face or a list of faces, then they are also
-considered, until a specified stipple is found.  To ensure that the
-return value is always specified, use a value of @code{default} for
-@var{inherit}.
-@end defun
-
-@defun face-font face &optional frame
-This function returns the name of the font of face @var{face}.
 @end defun
 
-@defun face-bold-p face &optional frame
+@defun face-bold-p face &optional frame inherit
 This function returns a non-@code{nil} value if the @code{:weight}
 attribute of @var{face} is bolder than normal (i.e., one of
 @code{semi-bold}, @code{bold}, @code{extra-bold}, or
 @code{ultra-bold}).  Otherwise, it returns @code{nil}.
 @end defun
 
-@defun face-italic-p face &optional frame
+@defun face-italic-p face &optional frame inherit
 This function returns a non-@code{nil} value if the @code{:slant}
 attribute of @var{face} is @code{italic} or @code{oblique}, and
 @code{nil} otherwise.
 @end defun
 
-@c Note the weasel words.  A face that inherits from an underlined
-@c face but does not specify :underline will return nil.
-@defun face-underline-p face &optional frame
+@defun face-underline-p face &optional frame inherit
 This function returns non-@code{nil} if face @var{face} specifies
 a non-@code{nil} @code{:underline} attribute.
 @end defun
 
-@defun face-inverse-video-p face &optional frame
+@defun face-inverse-video-p face &optional frame inherit
 This function returns non-@code{nil} if face @var{face} specifies
 a non-@code{nil} @code{:inverse-video} attribute.
 @end defun
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/os.texi b/doc/lispref/os.texi
index 2f06e207fc4..7552aaccc53 100644
--- a/doc/lispref/os.texi
+++ b/doc/lispref/os.texi
@@ -1373,8 +1373,8 @@ on others, years as early as 1901 do work.
 @node Time Parsing
 @section Parsing and Formatting Times
 
-  These functions convert time values (lists of two or three integers)
-to text in a string, and vice versa.
+  These functions convert time values to text in a string, and vice versa.
+Time values are lists of two to four integers (@pxref{Time of Day}).
 
 @defun date-to-time string
 This function parses the time-string @var{string} and returns the
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.
diff --git a/doc/lispref/windows.texi b/doc/lispref/windows.texi
index b8581b1cc62..e515b24db93 100644
--- a/doc/lispref/windows.texi
+++ b/doc/lispref/windows.texi
@@ -2038,7 +2038,8 @@ Evaluating the form above will cause @code{display-buffer} to proceed as
 follows: If `*foo*' already appears on a visible or iconified frame, it
 will reuse its window.  Otherwise, it will try to pop up a new window
 or, if that is impossible, a new frame.  If all these steps fail, it
-will try to use some existing window.
+will proceed using whatever @code{display-buffer-base-action} and
+@code{display-buffer-fallback-action} prescribe.
 
    Furthermore, @code{display-buffer} will try to adjust a reused window
 (provided `*foo*' was put by @code{display-buffer} there before) or a