Merge from trunk

13 files changed, 193 insertions, 144 deletions

diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index b0156e5ac7e..ce99c81a912 100644
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,3 +1,56 @@
+2012-09-11  Paul Eggert  <eggert@cs.ucla.edu>
+
+        Simplify, document, and port floating-point (Bug#12381).
+        * numbers.texi (Float Basics, Arithmetic Operations, Math Functions):
+        Document that / and mod (with floating point arguments), along
+        with asin, acos, log, log10, expt and sqrt, return special values
+        instead of signaling exceptions.
+        (Float Basics): Document that logb operates on the absolute value
+        of its argument.
+        (Math Functions): Document that (log ARG BASE) also returns NaN if
+        BASE is negative.  Document that (expt X Y) returns NaN if X is a
+        finite negative number and Y a finite non-integer.
+
+2012-09-09  Chong Yidong  <cyd@gnu.org>
+
+        * lists.texi (Sets And Lists): Explain that the return value for
+        delete should be used, like for delq.
+
+        * minibuf.texi (Yes-or-No Queries): Document recentering and
+        scrolling in y-or-n-p.  Remove gratuitous example.
+
+        * searching.texi (Search and Replace): Document window scrolling
+        entries in query-replace-map.
+
+2012-09-08  Chong Yidong  <cyd@gnu.org>
+
+        * syntax.texi (Syntax Table Internals): Define "raw syntax
+        descriptor" terminology (Bug#12383).
+        (Syntax Descriptors): Mention raw syntax descriptors.
+
+2012-09-07  Chong Yidong  <cyd@gnu.org>
+
+        * variables.texi (Creating Buffer-Local): Fix description of
+        local-variable-if-set-p (Bug#10713).
+
+        * eval.texi (Intro Eval): Add index entry for sexp (Bug#12233).
+
+        * windows.texi (Display Action Functions)
+        (Choosing Window Options): Remove obsolete variable
+        display-buffer-reuse-frames.
+        (Switching Buffers): Minor doc tweak for switch-to-buffer.
+
+        * positions.texi (Narrowing): Document buffer-narrowed-p.
+
+        * markers.texi (Moving Markers): Add xref to Point (Bug#7151).
+
+        * syntax.texi (Low-Level Parsing): Add xref to Parser State
+        (Bug#12269).
+
+2012-09-04  Lars Ingebrigtsen  <larsi@gnus.org>
+
+        * debugging.texi (Explicit Debug): Document `debug-on-message'.
+
 2012-09-02  Chong Yidong  <cyd@gnu.org>
 
         * windows.texi (Window Configurations): Recommend against using
diff --git a/doc/lispref/commands.texi b/doc/lispref/commands.texi
index 7e24de94fbe..dc0fa4c639d 100644
--- a/doc/lispref/commands.texi
+++ b/doc/lispref/commands.texi
@@ -2738,17 +2738,6 @@ This function converts the string or vector @var{key} to a list of
 individual events, which you can put in @code{unread-command-events}.
 @end defun
 
-@ignore
-@defvar unread-command-char
-This variable holds a character to be read as command input.
-A value of -1 means ``empty''.
-
-This variable is mostly obsolete now that you can use
-@code{unread-command-events} instead; it exists only to support programs
-written for Emacs versions 18 and earlier.
-@end defvar
-@end ignore
-
 @defun input-pending-p
 @cindex waiting for command key input
 This function determines whether any command input is currently
diff --git a/doc/lispref/debugging.texi b/doc/lispref/debugging.texi
index 00e8d84e9b3..5aeff576d09 100644
--- a/doc/lispref/debugging.texi
+++ b/doc/lispref/debugging.texi
@@ -298,6 +298,11 @@ of @code{(debug)} isn't ignored, it will alter the execution of the
 program!)  The most common suitable places are inside a @code{progn} or
 an implicit @code{progn} (@pxref{Sequencing}).
 
+  If you don't know exactly where in the source code you want to put
+the debug statement, but you want to display a backtrace when a
+certain message is displayed, you can set @code{debug-on-message} to a
+regular expression matching the desired message.
+
 @node Using Debugger
 @subsection Using the Debugger
 
diff --git a/doc/lispref/eval.texi b/doc/lispref/eval.texi
index 6dc6287b803..b373ecfbe62 100644
--- a/doc/lispref/eval.texi
+++ b/doc/lispref/eval.texi
@@ -40,6 +40,7 @@ interpreter.
 @cindex form
 @cindex expression
 @cindex S-expression
+@cindex sexp
   A Lisp object that is intended for evaluation is called a @dfn{form}
 or @dfn{expression}@footnote{It is sometimes also referred to as an
 @dfn{S-expression} or @dfn{sexp}, but we generally do not use this
diff --git a/doc/lispref/lists.texi b/doc/lispref/lists.texi
index 023f8ba18dd..d685ce0aa74 100644
--- a/doc/lispref/lists.texi
+++ b/doc/lispref/lists.texi
@@ -1293,14 +1293,19 @@ compare @var{object} against the elements of the list.  For example:
 @defun delq object list
 @cindex deleting list elements
 This function destructively removes all elements @code{eq} to
-@var{object} from @var{list}.  The letter @samp{q} in @code{delq} says
-that it uses @code{eq} to compare @var{object} against the elements of
-the list, like @code{memq} and @code{remq}.
+@var{object} from @var{list}, and returns the resulting list.  The
+letter @samp{q} in @code{delq} says that it uses @code{eq} to compare
+@var{object} against the elements of the list, like @code{memq} and
+@code{remq}.
+
+Typically, when you invoke @code{delq}, you should use the return
+value by assigning it to the variable which held the original list.
+The reason for this is explained below.
 @end defun
 
-When @code{delq} deletes elements from the front of the list, it does so
-simply by advancing down the list and returning a sublist that starts
-after those elements:
+The @code{delq} function deletes elements from the front of the list
+by simply advancing down the list, and returning a sublist that starts
+after those elements.  For example:
 
 @example
 @group
@@ -1308,6 +1313,7 @@ after those elements:
 @end group
 @end example
 
+@noindent
 When an element to be deleted appears in the middle of the list,
 removing it involves changing the @sc{cdr}s (@pxref{Setcdr}).
 
@@ -1432,12 +1438,15 @@ Compare this with @code{memq}:
 @end defun
 
 @defun delete object sequence
-If @code{sequence} is a list, this function destructively removes all
-elements @code{equal} to @var{object} from @var{sequence}.  For lists,
-@code{delete} is to @code{delq} as @code{member} is to @code{memq}: it
-uses @code{equal} to compare elements with @var{object}, like
-@code{member}; when it finds an element that matches, it cuts the
-element out just as @code{delq} would.
+This function removes all elements @code{equal} to @var{object} from
+@var{sequence}, and returns the resulting sequence.
+
+If @var{sequence} is a list, @code{delete} is to @code{delq} as
+@code{member} is to @code{memq}: it uses @code{equal} to compare
+elements with @var{object}, like @code{member}; when it finds an
+element that matches, it cuts the element out just as @code{delq}
+would.  As with @code{delq}, you should typically use the return value
+by assigning it to the variable which held the original list.
 
 If @code{sequence} is a vector or string, @code{delete} returns a copy
 of @code{sequence} with all elements @code{equal} to @code{object}
diff --git a/doc/lispref/markers.texi b/doc/lispref/markers.texi
index 22e806defec..80136f2e6f4 100644
--- a/doc/lispref/markers.texi
+++ b/doc/lispref/markers.texi
@@ -355,9 +355,9 @@ the current buffer.
 
 If @var{position} is less than 1, @code{set-marker} moves @var{marker}
 to the beginning of the buffer.  If @var{position} is greater than the
-size of the buffer, @code{set-marker} moves marker to the end of the
-buffer.  If @var{position} is @code{nil} or a marker that points
-nowhere, then @var{marker} is set to point nowhere.
+size of the buffer (@pxref{Point}), @code{set-marker} moves marker to
+the end of the buffer.  If @var{position} is @code{nil} or a marker
+that points nowhere, then @var{marker} is set to point nowhere.
 
 The value returned is @var{marker}.
 
diff --git a/doc/lispref/minibuf.texi b/doc/lispref/minibuf.texi
index 4cf096b8663..3d6e80bf3f0 100644
--- a/doc/lispref/minibuf.texi
+++ b/doc/lispref/minibuf.texi
@@ -1888,47 +1888,14 @@ Echo Area}), which uses the same screen space as the minibuffer.  The
 cursor moves to the echo area while the question is being asked.
 
 The answers and their meanings, even @samp{y} and @samp{n}, are not
-hardwired.  The keymap @code{query-replace-map} specifies them.
-@xref{Search and Replace}.
-
-In the following example, the user first types @kbd{q}, which is
-invalid.  At the next prompt the user types @kbd{y}.
-
-@c Need an interactive example, because otherwise the return value
-@c obscures the display of the valid answer.
-@smallexample
-@group
-(defun ask ()
-  (interactive)
-  (y-or-n-p "Do you need a lift? "))
-
-;; @r{After evaluation of the preceding definition, @kbd{M-x ask}}
-;;   @r{causes the following prompt to appear in the echo area:}
-@end group
-
-@group
----------- Echo area ----------
-Do you need a lift? (y or n)
----------- Echo area ----------
-@end group
-
-;; @r{If the user then types @kbd{q}, the following appears:}
-
-@group
----------- Echo area ----------
-Please answer y or n.  Do you need a lift? (y or n)
----------- Echo area ----------
-@end group
-
-;; @r{When the user types a valid answer,}
-;;   @r{it is displayed after the question:}
-
-@group
----------- Echo area ----------
-Do you need a lift? (y or n) y
----------- Echo area ----------
-@end group
-@end smallexample
+hardwired, and are specified by the keymap @code{query-replace-map}
+(@pxref{Search and Replace}).  In particular, if the user enters the
+special responses @code{recenter}, @code{scroll-up},
+@code{scroll-down}, @code{scroll-other-window}, or
+@code{scroll-other-window-down} (respectively bound to @kbd{C-l},
+@kbd{C-v}, @kbd{M-v}, @kbd{C-M-v} and @kbd{C-M-S-v} in
+@code{query-replace-map}), this function performs the specified window
+recentering or scrolling operation, and poses the question again.
 
 @noindent
 We show successive lines of echo area messages, but only one actually
diff --git a/doc/lispref/numbers.texi b/doc/lispref/numbers.texi
index 17f3ee099bd..7c9672a38c0 100644
--- a/doc/lispref/numbers.texi
+++ b/doc/lispref/numbers.texi
@@ -196,6 +196,14 @@ numerical functions return such values in cases where there is no
 correct answer.  For example, @code{(/ 0.0 0.0)} returns a NaN.  (NaN
 values can also carry a sign, but for practical purposes there's no
 significant difference between different NaN values in Emacs Lisp.)
+
+When a function is documented to return a NaN, it returns an
+implementation-defined value when Emacs is running on one of the
+now-rare platforms that do not use @acronym{IEEE} floating point.  For
+example, @code{(log -1.0)} typically returns a NaN, but on
+non-@acronym{IEEE} platforms it returns an implementation-defined
+value.
+
 Here are the read syntaxes for these special floating point values:
 
 @table @asis
@@ -241,7 +249,7 @@ numbers.
 
 @defun logb number
 This function returns the binary exponent of @var{number}.  More
-precisely, the value is the logarithm of @var{number} base 2, rounded
+precisely, the value is the logarithm of |@var{number}| base 2, rounded
 down to an integer.
 
 @example
@@ -694,7 +702,8 @@ arguments.  It also permits floating point arguments; it rounds the
 quotient downward (towards minus infinity) to an integer, and uses that
 quotient to compute the remainder.
 
-An @code{arith-error} results if @var{divisor} is 0.
+If @var{divisor} is zero, @code{mod} signals an @code{arith-error}
+error if both arguments are integers, and returns a NaN otherwise.
 
 @example
 @group
@@ -1096,8 +1105,8 @@ pi/2
 @tex
 @math{\pi/2}
 @end tex
-(inclusive) whose sine is @var{arg}; if, however, @var{arg} is out of
-range (outside [@minus{}1, 1]), it signals a @code{domain-error} error.
+(inclusive) whose sine is @var{arg}.  If @var{arg} is out of range
+(outside [@minus{}1, 1]), @code{asin} returns a NaN.
 @end defun
 
 @defun acos arg
@@ -1108,8 +1117,8 @@ pi
 @tex
 @math{\pi}
 @end tex
-(inclusive) whose cosine is @var{arg}; if, however, @var{arg} is out
-of range (outside [@minus{}1, 1]), it signals a @code{domain-error} error.
+(inclusive) whose cosine is @var{arg}.  If @var{arg} is out of range
+(outside [@minus{}1, 1]), @code{acos} returns a NaN.
 @end defun
 
 @defun atan y &optional x
@@ -1141,8 +1150,8 @@ This is the exponential function; it returns @math{e} to the power
 @defun log arg &optional base
 This function returns the logarithm of @var{arg}, with base
 @var{base}.  If you don't specify @var{base}, the natural base
-@math{e} is used.  If @var{arg} is negative, it signals a
-@code{domain-error} error.
+@math{e} is used.  If @var{arg} or @var{base} is negative, @code{log}
+returns a NaN.
 @end defun
 
 @ignore
@@ -1160,21 +1169,21 @@ lose accuracy.
 @end ignore
 
 @defun log10 arg
-This function returns the logarithm of @var{arg}, with base 10.  If
-@var{arg} is negative, it signals a @code{domain-error} error.
-@code{(log10 @var{x})} @equiv{} @code{(log @var{x} 10)}, at least
-approximately.
+This function returns the logarithm of @var{arg}, with base 10:
+@code{(log10 @var{x})} @equiv{} @code{(log @var{x} 10)}.
 @end defun
 
 @defun expt x y
 This function returns @var{x} raised to power @var{y}.  If both
 arguments are integers and @var{y} is positive, the result is an
 integer; in this case, overflow causes truncation, so watch out.
+If @var{x} is a finite negative number and @var{y} is a finite
+non-integer, @code{expt} returns a NaN.
 @end defun
 
 @defun sqrt arg
 This returns the square root of @var{arg}.  If @var{arg} is negative,
-it signals a @code{domain-error} error.
+@code{sqrt} returns a NaN.
 @end defun
 
 In addition, Emacs defines the following common mathematical
diff --git a/doc/lispref/positions.texi b/doc/lispref/positions.texi
index a0c65319850..c4576e6456d 100644
--- a/doc/lispref/positions.texi
+++ b/doc/lispref/positions.texi
@@ -874,18 +874,18 @@ commands to a limited range of characters in a buffer.  The text that
 remains addressable is called the @dfn{accessible portion} of the
 buffer.
 
-  Narrowing is specified with two buffer positions which become the
-beginning and end of the accessible portion.  For most editing commands
-and most Emacs primitives, these positions replace the values of the
-beginning and end of the buffer.  While narrowing is in effect, no text
-outside the accessible portion is displayed, and point cannot move
-outside the accessible portion.
-
-  Values such as positions or line numbers, which usually count from the
-beginning of the buffer, do so despite narrowing, but the functions
-which use them refuse to operate on text that is inaccessible.
-
-  The commands for saving buffers are unaffected by narrowing; they save
+  Narrowing is specified with two buffer positions, which become the
+beginning and end of the accessible portion.  For most editing
+commands and primitives, these positions replace the values of the
+beginning and end of the buffer.  While narrowing is in effect, no
+text outside the accessible portion is displayed, and point cannot
+move outside the accessible portion.  Note that narrowing does not
+alter actual buffer positions (@pxref{Point}); it only determines
+which positions are considered the accessible portion of the buffer.
+Most functions refuse to operate on text that is outside the
+accessible portion.
+
+  Commands for saving buffers are unaffected by narrowing; they save
 the entire buffer regardless of any narrowing.
 
   If you need to display in a single buffer several very different
@@ -924,6 +924,11 @@ It is equivalent to the following expression:
 @end example
 @end deffn
 
+@defun buffer-narrowed-p
+This function returns non-@code{nil} if the buffer is narrowed, and
+@code{nil} otherwise.
+@end defun
+
 @defspec save-restriction body@dots{}
 This special form saves the current bounds of the accessible portion,
 evaluates the @var{body} forms, and finally restores the saved bounds,
diff --git a/doc/lispref/searching.texi b/doc/lispref/searching.texi
index 0fa681ecb51..edd1d30e28d 100644
--- a/doc/lispref/searching.texi
+++ b/doc/lispref/searching.texi
@@ -1796,7 +1796,13 @@ Delete the text being considered, then enter a recursive edit to replace
 it.
 
 @item recenter
-Redisplay and center the window, then ask the same question again.
+@itemx scroll-up
+@itemx scroll-down
+@itemx scroll-other-window
+@itemx scroll-other-window-down
+Perform the specified window scroll operation, then ask the same
+question again.  Only @code{y-or-n-p} and related functions use this
+answer.
 
 @item quit
 Perform a quit right away.  Only @code{y-or-n-p} and related functions
diff --git a/doc/lispref/syntax.texi b/doc/lispref/syntax.texi
index ab685290901..624b5a92d6e 100644
--- a/doc/lispref/syntax.texi
+++ b/doc/lispref/syntax.texi
@@ -130,6 +130,10 @@ comment-ender), and the entry for @samp{/} is @samp{@w{. 14}} (i.e.,
 punctuation, matching character slot unused, first character of a
 comment-starter, second character of a comment-ender).
 
+  Emacs also defines @dfn{raw syntax descriptors}, which are used to
+describe syntax classes at a lower level.  @xref{Syntax Table
+Internals}.
+
 @menu
 * Syntax Class Table::      Table of syntax classes.
 * Syntax Flags::            Additional flags each character can have.
@@ -531,8 +535,9 @@ the current buffer's syntax table to determine the syntax for the
 underlying text character.
 
 @item @code{(@var{syntax-code} . @var{matching-char})}
-A cons cell of this format specifies the syntax for the underlying
-text character.  (@pxref{Syntax Table Internals})
+A cons cell of this format is a raw syntax descriptor (@pxref{Syntax
+Table Internals}), which directly specifies a syntax class for the
+underlying text character.
 
 @item @code{nil}
 If the property is @code{nil}, the character's syntax is determined from
@@ -878,6 +883,9 @@ This function parses a sexp in the current buffer starting at
 @var{start}, not scanning past @var{limit}.  It stops at position
 @var{limit} or when certain criteria described below are met, and sets
 point to the location where parsing stops.  It returns a parser state
+@ifinfo
+(@pxref{Parser State})
+@end ifinfo
 describing the status of the parse at the point where it stops.
 
 @cindex parenthesis depth
@@ -937,16 +945,20 @@ documented in this section.  This internal format can also be assigned
 as syntax properties (@pxref{Syntax Properties}).
 
 @cindex syntax code
-  Each entry in a syntax table is a cons cell of the form
-@code{(@var{syntax-code} . @var{matching-char})}.  @var{syntax-code}
-is an integer that encodes the syntax class and syntax flags,
-according to the table below.  @var{matching-char}, if non-@code{nil},
-specifies a matching character (similar to the second character in a
-syntax descriptor).
+@cindex raw syntax descriptor
+  Each entry in a syntax table is a @dfn{raw syntax descriptor}: a
+cons cell of the form @code{(@var{syntax-code}
+. @var{matching-char})}.  @var{syntax-code} is an integer which
+encodes the syntax class and syntax flags, according to the table
+below.  @var{matching-char}, if non-@code{nil}, specifies a matching
+character (similar to the second character in a syntax descriptor).
+
+  Here are the syntax codes corresponding to the various syntax
+classes:
 
 @multitable @columnfractions .2 .3 .2 .3
 @item
-@i{Syntax code} @tab @i{Class} @tab @i{Syntax code} @tab @i{Class}
+@i{Code} @tab @i{Class} @tab @i{Code} @tab @i{Class}
 @item
 0 @tab whitespace @tab 8 @tab paired delimiter
 @item
@@ -967,7 +979,7 @@ syntax descriptor).
 
 @noindent
 For example, in the standard syntax table, the entry for @samp{(} is
-@code{(4 . 41)}.  (41 is the character code for @samp{)}.)
+@code{(4 . 41)}.  41 is the character code for @samp{)}.
 
   Syntax flags are encoded in higher order bits, starting 16 bits from
 the least significant bit.  This table gives the power of two which
@@ -987,33 +999,35 @@ corresponds to each syntax flag.
 @end multitable
 
 @defun string-to-syntax @var{desc}
-Given a syntax descriptor @var{desc}, this function returns the
-corresponding internal form, a cons cell @code{(@var{syntax-code}
-. @var{matching-char})}.
+Given a syntax descriptor @var{desc} (a string), this function returns
+the corresponding raw syntax descriptor.
 @end defun
 
 @defun syntax-after pos
-This function returns the syntax code of the character in the buffer
-after position @var{pos}, taking account of syntax properties as well
-as the syntax table.  If @var{pos} is outside the buffer's accessible
-portion (@pxref{Narrowing, accessible portion}), this function returns
-@code{nil}.
+This function returns the raw syntax descriptor for the character in
+the buffer after position @var{pos}, taking account of syntax
+properties as well as the syntax table.  If @var{pos} is outside the
+buffer's accessible portion (@pxref{Narrowing, accessible portion}),
+the return value is @code{nil}.
 @end defun
 
 @defun syntax-class syntax
-This function returns the syntax class of the syntax code
-@var{syntax}.  (It masks off the high 16 bits that hold the flags
-encoded in the syntax descriptor.)  If @var{syntax} is @code{nil}, it
-returns @code{nil}; this is so evaluating the expression
+This function returns the syntax code for the raw syntax descriptor
+@var{syntax}.  More precisely, it takes the raw syntax descriptor's
+@var{syntax-code} component, masks off the high 16 bits which record
+the syntax flags, and returns the resulting integer.
+
+If @var{syntax} is @code{nil}, the return value is returns @code{nil}.
+This is so that the expression
 
 @example
 (syntax-class (syntax-after pos))
 @end example
 
 @noindent
-where @code{pos} is outside the buffer's accessible portion, will
-yield @code{nil} without throwing errors or producing wrong syntax
-class codes.
+evaluates to @code{nil} if @code{pos} is outside the buffer's
+accessible portion, without throwing errors or returning an incorrect
+code.
 @end defun
 
 @node Categories
diff --git a/doc/lispref/variables.texi b/doc/lispref/variables.texi
index 3b078e7e19f..c5b66757ace 100644
--- a/doc/lispref/variables.texi
+++ b/doc/lispref/variables.texi
@@ -1302,9 +1302,10 @@ This returns @code{t} if @var{variable} is buffer-local in buffer
 @end defun
 
 @defun local-variable-if-set-p variable &optional buffer
-This returns @code{t} if @var{variable} will become buffer-local in
-buffer @var{buffer} (which defaults to the current buffer) if it is
-set there.
+This returns @code{t} if @var{variable} either has a buffer-local
+value in buffer @var{buffer}, or is automatically buffer-local.
+Otherwise, it returns @code{nil}.  If omitted or @code{nil},
+@var{buffer} defaults to the current buffer.
 @end defun
 
 @defun buffer-local-value variable buffer
diff --git a/doc/lispref/windows.texi b/doc/lispref/windows.texi
index 5fe007ba02d..ea48a46359c 100644
--- a/doc/lispref/windows.texi
+++ b/doc/lispref/windows.texi
@@ -1492,12 +1492,10 @@ to make a buffer current to modify it in Lisp, use
 @code{set-buffer}.  @xref{Current Buffer}.
 
 @deffn Command switch-to-buffer buffer-or-name &optional norecord force-same-window
-This function displays @var{buffer-or-name} in the selected window,
-and makes it the current buffer.  (In contrast, @code{set-buffer}
-makes the buffer current but does not display it; @pxref{Current
-Buffer}).  It is often used interactively (as the binding of @kbd{C-x
-b}), as well as in Lisp programs.  The return value is the buffer
-switched to.
+This command attempts to display @var{buffer-or-name} in the selected
+window, and makes it the current buffer.  It is often used
+interactively (as the binding of @kbd{C-x b}), as well as in Lisp
+programs.  The return value is the buffer switched to.
 
 If @var{buffer-or-name} is @code{nil}, it defaults to the buffer
 returned by @code{other-buffer} (@pxref{The Buffer List}).  If
@@ -1506,17 +1504,18 @@ buffer, this function creates a new buffer with that name; the new
 buffer's major mode is determined by the variable @code{major-mode}
 (@pxref{Major Modes}).
 
-Normally the specified buffer is put at the front of the buffer
+Normally, the specified buffer is put at the front of the buffer
 list---both the global buffer list and the selected frame's buffer
 list (@pxref{The Buffer List}).  However, this is not done if the
 optional argument @var{norecord} is non-@code{nil}.
 
-If this function is unable to display the buffer in the selected
-window---usually because the selected window is a minibuffer window or
-is strongly dedicated to its buffer (@pxref{Dedicated Windows})---then
-it normally tries to display the buffer in some other window, in the
-manner of @code{pop-to-buffer} (see below).  However, if the optional
-argument @var{force-same-window} is non-@code{nil}, it signals an error
+Sometimes, @code{switch-to-buffer} may be unable to display the buffer
+in the selected window.  This happens if the selected window is a
+minibuffer window, or if the selected window is strongly dedicated to
+its buffer (@pxref{Dedicated Windows}).  In that case, the command
+normally tries to display the buffer in some other window, by invoking
+@code{pop-to-buffer} (see below).  However, if the optional argument
+@var{force-same-window} is non-@code{nil}, it signals an error
 instead.
 @end deffn
 
@@ -1728,8 +1727,7 @@ A frame means consider windows on that frame only.
 @end itemize
 
 If @var{alist} contains no @code{reusable-frames} entry, this function
-normally searches just the selected frame; however, if either the
-variable @code{display-buffer-reuse-frames} or the variable
+normally searches just the selected frame; however, if the variable
 @code{pop-up-frames} is non-@code{nil}, it searches all frames on the
 current terminal.  @xref{Choosing Window Options}.
 
@@ -1769,14 +1767,6 @@ The behavior of the standard display actions of @code{display-buffer}
 (@pxref{Choosing Window}) can be modified by a variety of user
 options.
 
-@defopt display-buffer-reuse-frames
-If the value of this variable is non-@code{nil}, @code{display-buffer}
-may search all frames on the current terminal when looking for a
-window already displaying the specified buffer.  The default is
-@code{nil}.  This variable is consulted by the action function
-@code{display-buffer-reuse-window} (@pxref{Display Action Functions}).
-@end defopt
-
 @defopt pop-up-windows
 If the value of this variable is non-@code{nil}, @code{display-buffer}
 is allowed to split an existing window to make a new window for