Merge from emacs-24; up to 2012-11-17T22:12:47Z!eggert@cs.ucla.edu

8 files changed, 145 insertions, 63 deletions

diff --git a/doc/emacs/ChangeLog b/doc/emacs/ChangeLog
index dc5fa539cd1..af22f0628d1 100644
--- a/doc/emacs/ChangeLog
+++ b/doc/emacs/ChangeLog
@@ -1,3 +1,9 @@
+2012-11-21  Dani Moncayo  <dmoncayo@gmail.com>
+
+        * display.texi (Auto Scrolling): Fix some inaccuracies, plus
+        clarifications (Bug#12865).
+        (Horizontal Scrolling): Clarifications.
+
 2012-11-18  Dani Moncayo  <dmoncayo@gmail.com>
 
         * mark.texi (Disabled Transient Mark): Doc fixes (Bug#12746).
diff --git a/doc/emacs/display.texi b/doc/emacs/display.texi
index b6ab4913f9c..876c46bdf1a 100644
--- a/doc/emacs/display.texi
+++ b/doc/emacs/display.texi
@@ -213,59 +213,62 @@ entire current defun onto the screen if possible.
 @node Auto Scrolling
 @section Automatic Scrolling
 
+@cindex automatic scrolling
   Emacs performs @dfn{automatic scrolling} when point moves out of the
-visible portion of the text.
+visible portion of the text.  Normally, automatic scrolling centers
+point vertically in the window, but there are several ways to alter
+this behavior.
 
 @vindex scroll-conservatively
-  Normally, this centers point vertically within the window.  However,
-if you set @code{scroll-conservatively} to a small number @var{n},
-then if you move point just a little off the screen (less than @var{n}
-lines), Emacs scrolls the text just far enough to bring point back on
-screen.  If doing so fails to make point visible, Emacs centers point
-in the window.  By default, @code{scroll-conservatively} is@tie{}0.
-If you set @code{scroll-conservatively} to a large number (larger than
-100), Emacs will never center point as result of scrolling, even if
-point moves far away from the text previously displayed in the window.
-With such a large value, Emacs will always scroll text just enough for
-bringing point into view, so point will end up at the top or bottom of
-the window, depending on the scroll direction.
+  If you set @code{scroll-conservatively} to a small number @var{n},
+then moving point just a little off the screen (no more than @var{n}
+lines) causes Emacs to scroll just enough to bring point back on
+screen; if doing so fails to make point visible, Emacs scrolls just
+far enough to center point in the window.  If you set
+@code{scroll-conservatively} to a large number (larger than 100),
+automatic scrolling never centers point, no matter how far point
+moves; Emacs always scrolls text just enough to bring point into view,
+either at the top or bottom of the window depending on the scroll
+direction.  By default, @code{scroll-conservatively} is@tie{}0, which
+means to always center point in the window.
 
 @vindex scroll-step
-  An alternative way of controlling how Emacs scrolls text is by
-customizing the variable @code{scroll-step}.  Its value determines how
-many lines to scroll the window when point moves off the screen.  If
-moving by that number of lines fails to bring point back into view,
-point is centered instead.  The default value is zero, which causes
-point to always be centered after scrolling.
-
-  Since both @code{scroll-conservatively} and @code{scroll-step}
-control automatic scrolling in contradicting ways, you should set only
-one of them.  If you customize both, the value of
-@code{scroll-conservatively} takes precedence.
+  Another way to control automatic scrolling is to customize the
+variable @code{scroll-step}.  Its value determines the number of lines
+by which to automatically scroll, when point moves off the screen.  If
+scrolling by that number of lines fails to bring point back into view,
+point is centered instead.  The default value is zero, which (by
+default) causes point to always be centered after scrolling.
 
 @cindex aggressive scrolling
 @vindex scroll-up-aggressively
 @vindex scroll-down-aggressively
-  When the window does scroll by a distance longer than
-@code{scroll-step}, you can control how aggressively it scrolls by
-setting the variables @code{scroll-up-aggressively} and
-@code{scroll-down-aggressively}.  The value of
-@code{scroll-up-aggressively} should be either @code{nil}, or a
-fraction @var{f} between 0 and 1.  A fraction specifies where on the
-screen to put point when scrolling upward, i.e.@: forward.  When point
-goes off the window end, the new start position is chosen to put point
-@var{f} parts of the window height from the bottom margin.  Thus,
-larger @var{f} means more aggressive scrolling: more new text is
-brought into view.  The default value, @code{nil}, is equivalent to
-0.5.
-
-  Likewise, @code{scroll-down-aggressively} is used for scrolling
-down, i.e.@: backward.  The value specifies how far point should be
-placed from the top margin of the window; thus, as with
-@code{scroll-up-aggressively}, a larger value is more aggressive.
-
-  These two variables are ignored if either @code{scroll-step} or
-@code{scroll-conservatively} are set to a non-zero value.
+  A third way to control automatic scrolling is to customize the
+variables @code{scroll-up-aggressively} and
+@code{scroll-down-aggressively}, which directly specify the vertical
+position of point after scrolling.  The value of
+@code{scroll-up-aggressively} should be either @code{nil} (the
+default), or a floating point number @var{f} between 0 and 1.  The
+latter means that when point goes below the bottom window edge (i.e.@:
+scrolling forward), Emacs scrolls the window so that point is @var{f}
+parts of the window height from the bottom window edge.  Thus, larger
+@var{f} means more aggressive scrolling: more new text is brought into
+view.  The default value, @code{nil}, is equivalent to 0.5.
+
+  Likewise, @code{scroll-down-aggressively} is used when point goes
+above the bottom window edge (i.e.@: scrolling backward).  The value
+specifies how far point should be from the top margin of the window
+after scrolling.  Thus, as with @code{scroll-up-aggressively}, a
+larger value is more aggressive.
+
+  Note that the variables @code{scroll-conservatively},
+@code{scroll-step}, and @code{scroll-up-aggressively} /
+@code{scroll-down-aggressively} control automatic scrolling in
+contradictory ways.  Therefore, you should pick no more than one of
+these methods to customize automatic scrolling.  In case you customize
+multiple variables, the order of priority is:
+@code{scroll-conservatively}, then @code{scroll-step}, and finally
+@code{scroll-up-aggressively} / @code{scroll-down-aggressively}.
 
 @vindex scroll-margin
   The variable @code{scroll-margin} restricts how close point can come
@@ -295,10 +298,10 @@ the cursor is left at the edge instead.)
 
 @vindex hscroll-margin
   The variable @code{hscroll-margin} controls how close point can get
-to the window's edges before automatic scrolling occurs.  It is
-measured in columns.  For example, if the value is 5, then moving
-point within 5 columns of an edge causes horizontal scrolling away
-from that edge.
+to the window's left and right edges before automatic scrolling
+occurs.  It is measured in columns.  For example, if the value is 5,
+then moving point within 5 columns of an edge causes horizontal
+scrolling away from that edge.
 
 @vindex hscroll-step
   The variable @code{hscroll-step} determines how many columns to
diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index a5295adc368..db896984c86 100644
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,3 +1,20 @@
+2012-11-21  Glenn Morris  <rgm@gnu.org>
+
+        * 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/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