16 files changed, 1042 insertions, 492 deletions

diff --git a/doc/emacs/ChangeLog b/doc/emacs/ChangeLog
index 163eabed2a6..ac913fc3264 100644
--- a/doc/emacs/ChangeLog
+++ b/doc/emacs/ChangeLog
@@ -1,3 +1,17 @@
+2011-09-24  Chong Yidong  <cyd@stupidchicken.com>
+
+        * windows.texi (Pop Up Window): Defer discussion of window
+        splitting to the Window Choice node.  Add index entries.
+        (Force Same Window): Node deleted.
+        (Displaying Buffers, Window Choice): New nodes.
+
+        * buffers.texi (Select Buffer): Clarify description of
+        buffer-switching commands.  Add xref to Window Display node.
+        Don't repeat confirm-nonexistent-file-or-buffer description from
+        Visiting node.  Remove even-window-heights.
+
+        * frames.texi (Special Buffer Frames): Add xref to Window Choice.
+
 2011-09-18  Chong Yidong  <cyd@stupidchicken.com>
 
         * cmdargs.texi (Icons X): Fix description of Emacs icon.
diff --git a/doc/emacs/buffers.texi b/doc/emacs/buffers.texi
index c4880af2b5d..b82f3fac7d4 100644
--- a/doc/emacs/buffers.texi
+++ b/doc/emacs/buffers.texi
@@ -91,9 +91,9 @@ selected buffer other than the current buffer.
 @var{bufname} @key{RET}}.  This runs the command
 @code{switch-to-buffer} with argument @var{bufname}.  While entering
 the buffer name, you can use the usual minibuffer completion and
-history commands (@pxref{Minibuffer}).  An empty argument to @kbd{C-x
-b} specifies the buffer that was current most recently among those not
-now displayed in any window.
+history commands (@pxref{Minibuffer}).  An empty input specifies the
+buffer that was current most recently among those not now displayed in
+any window.
 
 @cindex minibuffer confirmation
 @cindex confirming in the minibuffer
@@ -107,16 +107,8 @@ catches a common mistake, in which one types @key{RET} before
 realizing that @key{TAB} did not complete far enough to yield the
 desired buffer name (@pxref{Completion}).  Emacs asks for confirmation
 by putting the message @samp{[Confirm]} in the minibuffer; type
-@key{RET} again to confirm and visit the buffer.
-
-@vindex confirm-nonexistent-file-or-buffer
-  The variable @code{confirm-nonexistent-file-or-buffer} controls
-whether Emacs asks for confirmation before visiting a buffer that did
-not previously exist.  The default value, @code{after-completion},
-gives the behavior we have just described.  If the value is
-@code{nil}, Emacs never asks for confirmation; for any other
-non-@code{nil} value, Emacs always asks for confirmation.  This
-variable also affects the @code{find-file} command (@pxref{Visiting}).
+@key{RET} again to confirm and visit the buffer.  @xref{Visiting}, for
+information about modifying this behavior.
 
   One reason to create a new buffer is to use it for making temporary
 notes.  If you try to save it, Emacs asks for the file name to use.
@@ -136,36 +128,26 @@ of most recent selection in the current frame), while @kbd{C-x @key{LEFT}}
 
 @kindex C-x 4 b
 @findex switch-to-buffer-other-window
-@vindex even-window-heights
   To select a buffer in a window other than the current one, type
 @kbd{C-x 4 b} (@code{switch-to-buffer-other-window}).  This prompts
 for a buffer name using the minibuffer, displays that buffer in
-another window, and selects that window.  By default, if displaying
-the buffer causes two vertically adjacent windows to be displayed, the
-heights of those windows are evened out; to countermand that and
-preserve the window configuration, set the variable
-@code{even-window-heights} to @code{nil}.
+another window, and selects that window.
 
 @kindex C-x 5 b
 @findex switch-to-buffer-other-frame
   Similarly, @kbd{C-x 5 b} (@code{switch-to-buffer-other-frame})
 prompts for a buffer name, displays that buffer in another frame, and
-selects that frame.
+selects that frame.  If the buffer is already being shown in a window
+on another frame, Emacs selects that window and frame instead of
+creating a new frame.
+
+  @xref{Displaying Buffers}, for how the @kbd{C-x 4 b} and @kbd{C-x 5
+b} commands get the window and/or frame to display in.
 
   In addition, @kbd{C-x C-f}, and any other command for visiting a
 file, can also be used to switch to an existing file-visiting buffer.
 @xref{Visiting}.
 
-@vindex display-buffer-reuse-frames
-  You can control how certain buffers are handled by these commands by
-customizing the variables @code{special-display-buffer-names},
-@code{special-display-regexps}, @code{same-window-buffer-names}, and
-@code{same-window-regexps}.  See @ref{Force Same Window}, and
-@ref{Special Buffer Frames}, for more about these variables.  In
-addition, if the value of @code{display-buffer-reuse-frames} is
-non-@code{nil}, and the buffer you want to switch to is already
-displayed in some frame, Emacs will just raise that frame.
-
 @findex goto-line
   @kbd{C-u M-g M-g}, that is @code{goto-line} with a plain prefix
 argument, reads a number @var{n} using the minibuffer, selects the
diff --git a/doc/emacs/emacs.texi b/doc/emacs/emacs.texi
index 2ba4af712af..bb675b61cff 100644
--- a/doc/emacs/emacs.texi
+++ b/doc/emacs/emacs.texi
@@ -488,9 +488,8 @@ Multiple Windows
 * Split Window::        New windows are made by splitting existing windows.
 * Other Window::        Moving to another window or doing something to it.
 * Pop Up Window::       Finding a file or buffer in another window.
-* Force Same Window::   Forcing certain buffers to appear in the selected
-                          window rather than in another window.
 * Change Window::       Deleting windows and changing their sizes.
+* Displaying Buffers::  How Emacs picks a window for displaying a buffer.
 * Window Convenience::  Convenience functions for window handling.
 
 Frames and Graphical Displays
diff --git a/doc/emacs/emacsver.texi b/doc/emacs/emacsver.texi
index ffa860585ba..9df86fd9275 100644
--- a/doc/emacs/emacsver.texi
+++ b/doc/emacs/emacsver.texi
@@ -1,4 +1,4 @@
 @c It would be nicer to generate this using configure and @version@.
 @c However, that would mean emacsver.texi would always be newer
 @c then the info files in release tarfiles.
-@set EMACSVER 24.0.50
+@set EMACSVER 24.0.90
diff --git a/doc/emacs/frames.texi b/doc/emacs/frames.texi
index 8ca598c3348..619252503a9 100644
--- a/doc/emacs/frames.texi
+++ b/doc/emacs/frames.texi
@@ -850,11 +850,12 @@ each others' edits if they are not careful.
 
 @vindex special-display-buffer-names
   You can make certain chosen buffers, which Emacs normally displays
-in ``another window,'' appear in special frames of their own.  To do
-this, set the variable @code{special-display-buffer-names} to a list
-of buffer names; any buffer whose name is in that list automatically
-gets a special frame, when an Emacs command wants to display it ``in
-another window.''
+in ``some other window'' (@pxref{Displaying Buffers}), appear in
+special frames of their own.  To do this, set the variable
+@code{special-display-buffer-names} to a list of buffer names; any
+buffer whose name is in that list automatically gets a special frame.
+@xref{Window Choice}, for how this fits in with the other ways for
+Emacs to choose a window to display in.
 
   For example, if you set the variable this way,
 
@@ -906,13 +907,6 @@ where @var{function} is a symbol.  Then the frame is constructed by
 calling @var{function}; its first argument is the buffer, and its
 remaining arguments are @var{args}.
 
-   An analogous feature lets you specify buffers which should be
-displayed in the selected window.  @xref{Force Same Window}.  The
-same-window feature takes precedence over the special-frame feature;
-therefore, if you add a buffer name to
-@code{special-display-buffer-names} and it has no effect, check to see
-whether that feature is also in use for the same buffer name.
-
 @node Frame Parameters
 @section Setting Frame Parameters
 @cindex Auto-Raise mode
diff --git a/doc/emacs/windows.texi b/doc/emacs/windows.texi
index 6aa8a06778b..dc92e4a519c 100644
--- a/doc/emacs/windows.texi
+++ b/doc/emacs/windows.texi
@@ -18,9 +18,8 @@ one frame.
 * Split Window::        New windows are made by splitting existing windows.
 * Other Window::        Moving to another window or doing something to it.
 * Pop Up Window::       Finding a file or buffer in another window.
-* Force Same Window::   Forcing certain buffers to appear in the selected
-                          window rather than in another window.
 * Change Window::       Deleting windows and changing their sizes.
+* Displaying Buffers::  How Emacs picks a window for displaying a buffer.
 * Window Convenience::  Convenience functions for window handling.
 @end menu
 
@@ -191,84 +190,47 @@ feature is off by default.
 
 @cindex selecting buffers in other windows
 @kindex C-x 4
-  @kbd{C-x 4} is a prefix key for commands that select another window
-(splitting the window if there is only one) and select a buffer in that
-window.  Different @kbd{C-x 4} commands have different ways of finding the
-buffer to select.
+  @kbd{C-x 4} is a prefix key for a variety of commands that switch to
+a buffer in a different window---either another existing window, or a
+new window created by splitting the selected window.  @xref{Window
+Choice}, for how Emacs picks or creates the window to use.
 
 @table @kbd
+@findex switch-to-buffer-other-window
 @item C-x 4 b @var{bufname} @key{RET}
-Select buffer @var{bufname} in another window.  This runs
-@code{switch-to-buffer-other-window}.
+Select buffer @var{bufname} in another window
+(@code{switch-to-buffer-other-window}).
+
+@findex display-buffer
 @item C-x 4 C-o @var{bufname} @key{RET}
-Display buffer @var{bufname} in another window, but
-don't select that buffer or that window.  This runs
-@code{display-buffer}.
+Display buffer @var{bufname} in some window, without trying to select
+it (@code{display-buffer}).  @xref{Displaying Buffers}, for details
+about how the window is chosen.
+
+@findex find-file-other-window
 @item C-x 4 f @var{filename} @key{RET}
-Visit file @var{filename} and select its buffer in another window.  This
-runs @code{find-file-other-window}.  @xref{Visiting}.
+Visit file @var{filename} and select its buffer in another window
+(@code{find-file-other-window}).  @xref{Visiting}.
+
+@findex dired-other-window
 @item C-x 4 d @var{directory} @key{RET}
-Select a Dired buffer for directory @var{directory} in another window.
-This runs @code{dired-other-window}.  @xref{Dired}.
+Select a Dired buffer for directory @var{directory} in another window
+(@code{dired-other-window}).  @xref{Dired}.
+
+@findex mail-other-window
 @item C-x 4 m
-Start composing a mail message in another window.  This runs
-@code{mail-other-window}; its same-window analogue is @kbd{C-x m}
-(@pxref{Sending Mail}).
+Start composing a mail message, similar to @kbd{C-x m} (@pxref{Sending
+Mail}), but in another window (@code{mail-other-window}).
+
+@findex find-tag-other-window
 @item C-x 4 .
-Find a tag in the current tags table, in another window.  This runs
-@code{find-tag-other-window}, the multiple-window variant of @kbd{M-.}
-(@pxref{Tags}).
+Find a tag in the current tags table, similar to @kbd{M-.}
+(@pxref{Tags}), but in another window (@code{find-tag-other-window}).
 @item C-x 4 r @var{filename} @key{RET}
 Visit file @var{filename} read-only, and select its buffer in another
-window.  This runs @code{find-file-read-only-other-window}.
-@xref{Visiting}.
+window (@code{find-file-read-only-other-window}).  @xref{Visiting}.
 @end table
 
-@vindex split-height-threshold
-@vindex split-width-threshold
-  By default, these commands split the window vertically when there is
-only one.  You can customize the variables @code{split-height-threshold}
-and @code{split-width-threshold} to split the window horizontally
-instead.
-
-
-@node Force Same Window
-@section Forcing Display in the Same Window
-
-  Certain Emacs commands switch to a specific buffer with special
-contents.  For example, @kbd{M-x shell} switches to a buffer named
-@samp{*shell*}.  By convention, all these commands are written to pop up
-the buffer in a separate window.  But you can specify that certain of
-these buffers should appear in the selected window.
-
-@vindex same-window-buffer-names
-  If you add a buffer name to the list @code{same-window-buffer-names},
-the effect is that such commands display that particular buffer by
-switching to it in the selected window.  For example, if you add the
-element @code{"*grep*"} to the list, the @code{grep} command will
-display its output buffer in the selected window.
-
-  The default value of @code{same-window-buffer-names} is not
-@code{nil}: it specifies buffer names @samp{*info*}, @samp{*mail*} and
-@samp{*shell*} (as well as others used by more obscure Emacs packages).
-This is why @kbd{M-x shell} normally switches to the @samp{*shell*}
-buffer in the selected window.  If you delete this element from the
-value of @code{same-window-buffer-names}, the behavior of @kbd{M-x
-shell} will change---it will pop up the buffer in another window
-instead.
-
-@vindex same-window-regexps
-  You can specify these buffers more generally with the variable
-@code{same-window-regexps}.  Set it to a list of regular expressions;
-then any buffer whose name matches one of those regular expressions is
-displayed by switching to it in the selected window.  (Once again, this
-applies only to buffers that normally get displayed for you in a
-separate window.)  The default value of this variable specifies Telnet
-and rlogin buffers.
-
-  An analogous feature lets you specify buffers which should be
-displayed in their own individual frames.  @xref{Special Buffer Frames}.
-
 @node Change Window
 @section Deleting and Rearranging Windows
 
@@ -356,6 +318,113 @@ heights of all the windows in the selected frame.
   Mouse clicks on the mode line provide another way to change window
 heights and to delete windows.  @xref{Mode Line Mouse}.
 
+@node Displaying Buffers
+@section Displaying a Buffer in a Window
+
+  It is a common Emacs operation to display or ``pop up'' some buffer
+in response to a user command.  There are several different ways by
+which commands do this.
+
+  Many commands, like @kbd{C-x C-f} (@code{find-file}), display the
+buffer by ``taking over'' the selected window, expecting that the
+user's attention will be diverted to that buffer.  These commands
+usually work by calling @code{switch-to-buffer} internally
+(@pxref{Select Buffer}).
+
+@findex display-buffer
+  Some commands try to display ``intelligently'', trying not to take
+over the selected window, e.g. by splitting the selected window and
+displaying the desired buffer in the child window.  Such commands,
+which include the various help commands (@pxref{Help}), work by
+calling @code{display-buffer} internally.  @xref{Window Choice}, for
+details.
+
+  Other commands do the same as @code{display-buffer}, and
+additionally select the displaying window so that you can begin
+editing its buffer.  The command @kbd{C-x `} (@code{next-error}) is
+one example (@pxref{Compilation Mode}).  Such commands work by calling
+@code{pop-to-buffer} internally.  @xref{Displaying Buffers,,Displaying
+Buffers in Windows, elisp, The Emacs Lisp Reference Manual}.
+
+  Commands with names ending in @code{-other-window} behave like
+@code{display-buffer}, except that they never display in the selected
+window.  Several of these commands are bound in the @kbd{C-x 4} prefix
+key (@pxref{Pop Up Window}).
+
+  Commands with names ending in @code{-other-frame} behave like
+@code{display-buffer}, except that they (i) never display in the
+selected window and (ii) prefer to create a new frame to display the
+desired buffer instead of splitting a window---as though the variable
+@code{pop-up-frames} is set to @code{t} (@pxref{Window Choice}).
+Several of these commands are bound in the @kbd{C-x 5} prefix key.
+
+@menu
+* Window Choice::   How @code{display-buffer} works.
+@end menu
+
+@node Window Choice
+@subsection How @code{display-buffer} works
+@findex display-buffer
+
+The @code{display-buffer} command (as well as commands that call it
+internally) chooses a window to display using the following steps:
+
+@itemize
+@vindex same-window-buffer-names
+@vindex same-window-regexps
+@item
+First, check if the buffer should be displayed in the selected window
+regardless of other considerations.  You can tell Emacs to do this by
+adding the desired buffer's name to the list
+@code{same-window-buffer-names}, or adding a matching regular
+expression to the list @code{same-window-regexps}.  By default, these
+variables are @code{nil}, so this step is skipped.
+
+@vindex display-buffer-reuse-frames
+@item
+Otherwise, if the buffer is already displayed in an existing window,
+``reuse'' that window.  Normally, only windows on the selected frame
+are considered, but windows on other frames are also reusable if you
+change @code{display-buffer-reuse-frames} to @code{t}, or if you
+change @code{pop-up-frames} (see below) to @code{t}.
+
+@item
+Otherwise, if you specified that the buffer should be displayed in a
+special frame by customizing @code{special-display-buffer-names} or
+@code{special-display-regexps}, do so.  @xref{Special Buffer Frames}.
+
+@vindex pop-up-frames
+@item
+Otherwise, optionally create a new frame and display the buffer there.
+By default, this step is skipped.  To enable it, change the variable
+@code{pop-up-frames} to a non-@code{nil} value.  The special value
+@code{graphic-only} means to do this only on graphical displays.
+
+@item
+Otherwise, try to create a new window by splitting the selected
+window, and display the buffer in that new window.
+
+@vindex split-height-threshold
+@vindex split-width-threshold
+The split can be either vertical or horizontal, depending on the
+variables @code{split-height-threshold} and
+@code{split-width-threshold}.  These variables should have integer
+values.  If @code{split-height-threshold} is smaller than the selected
+window's height, the split puts the new window below.  Otherwise, if
+@code{split-width-threshold} is smaller than the window's width, the
+split puts the new window on the right.  If neither condition holds,
+Emacs tries to split so that the new window is below---but only if the
+window was not split before (to avoid excessive splitting).
+
+@item
+Otherwise, display the buffer in an existing window on the selected
+frame.
+
+@item
+If all the above methods fail for whatever reason, create a new frame
+and display the buffer there.
+@end itemize
+
 @node Window Convenience
 @section Window Handling Convenience Features and Customization
 
diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index 0094e7c12a6..423e052068b 100644
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,3 +1,39 @@
+2011-09-25  Martin Rudalics  <rudalics@gmx.at>
+
+        * windows.texi (Windows and Frames, Display Action Functions)
+        (Switching Buffers): Fix some typos.
+        (Buffers and Windows): Remove reference to window-auto-delete.
+        Reword description of replace-buffer-in-windows.
+        (Window History): Fix some typos and refer to frame local buffer
+        list.
+        (Quitting Windows): New node.
+        (Window Configurations): Add descriptions of window-state-get
+        and window-state-put.
+        (Window Parameters): Describe variable ignore-window-parameters.
+        Sketch some window parameters currently in use.
+        * elisp.texi (Top): Update node listing.
+
+2011-09-25  Chong Yidong  <cyd@stupidchicken.com>
+
+        * windows.texi (Display Action Functions)
+        (Choosing Window Options): New nodes.
+
+2011-09-24  Chong Yidong  <cyd@stupidchicken.com>
+
+        * windows.texi (Window History): New node.  Move text here from
+        Buffers and Windows.
+        (Switching Buffers): Rename from Displaying Buffers, since we
+        don't document display-buffer here; callers changed.  Document
+        FORCE-SAME-WINDOW arg to switch-to-buffer and
+        switch-to-buffer-other-frame.  Delete duplicate
+        replace-buffer-in-windows doc.
+        (Choosing Window): Document display actions.
+
+2011-09-24  Eli Zaretskii  <eliz@gnu.org>
+
+        * display.texi (Forcing Redisplay): Update the description of
+        redisplay-dont-pause due to change in the default value.
+
 2011-09-23  Martin Rudalics  <rudalics@gmx.at>
 
         * frames.texi (Frames and Windows): Move section and rename to
diff --git a/doc/lispref/buffers.texi b/doc/lispref/buffers.texi
index 0f9de74c948..ce1a8b0fb4e 100644
--- a/doc/lispref/buffers.texi
+++ b/doc/lispref/buffers.texi
@@ -124,7 +124,7 @@ selected window.  This is to prevent confusion: it ensures that the
 buffer that the cursor is in, when Emacs reads a command, is the
 buffer to which that command applies (@pxref{Command Loop}).  Thus,
 you should not use @code{set-buffer} to switch visibly to a different
-buffer; for that, use the functions described in @ref{Displaying
+buffer; for that, use the functions described in @ref{Switching
 Buffers}.
 
   When writing a Lisp function, do @emph{not} rely on this behavior of
@@ -775,13 +775,14 @@ been displayed in a window.  Several functions, notably
 @code{other-buffer}, use this ordering.  A buffer list displayed for the
 user also follows this order.
 
-  Creating a buffer adds it to the end of the buffer list, and killing a
-buffer removes it from that list.  A buffer moves to the front of this
-list whenever it is chosen for display in a window (@pxref{Displaying
-Buffers}) or a window displaying it is selected (@pxref{Selecting
-Windows}).  A buffer moves to the end of the list when it is buried (see
-@code{bury-buffer}, below).  There are no functions available to the
-Lisp programmer which directly manipulate the buffer list.
+  Creating a buffer adds it to the end of the buffer list, and killing
+a buffer removes it from that list.  A buffer moves to the front of
+this list whenever it is chosen for display in a window
+(@pxref{Switching Buffers}) or a window displaying it is selected
+(@pxref{Selecting Windows}).  A buffer moves to the end of the list
+when it is buried (see @code{bury-buffer}, below).  There are no
+functions available to the Lisp programmer which directly manipulate
+the buffer list.
 
   In addition to the fundamental buffer list just described, Emacs
 maintains a local buffer list for each frame, in which the buffers that
@@ -888,24 +889,24 @@ as well as the fundamental buffer list; therefore, the buffer that you
 bury will come last in the value of @code{(buffer-list @var{frame})} and
 in the value of @code{(buffer-list)}.
 
-If @var{buffer-or-name} is @code{nil} or omitted, this means to bury the
-current buffer.  In addition, if the buffer is displayed in the selected
-window, this switches to some other buffer (obtained using
-@code{other-buffer}) in the selected window.  @xref{Displaying Buffers}.
-But if the selected window is dedicated to its buffer, it deletes that
-window if there are other windows left on its frame.  Otherwise, if the
-selected window is the only window on its frame, it iconifies that
-frame.  If @var{buffer-or-name} is displayed in some other window, it
-remains displayed there.
+If @var{buffer-or-name} is @code{nil} or omitted, this means to bury
+the current buffer.  In addition, if the buffer is displayed in the
+selected window, this switches to some other buffer (obtained using
+@code{other-buffer}) in the selected window.  @xref{Switching
+Buffers}.  But if the selected window is dedicated to its buffer, it
+deletes that window if there are other windows left on its frame.
+Otherwise, if the selected window is the only window on its frame, it
+iconifies that frame.  If @var{buffer-or-name} is displayed in some
+other window, it remains displayed there.
 
 To replace a buffer in all the windows that display it, use
 @code{replace-buffer-in-windows}.  @xref{Buffers and Windows}.
 @end deffn
 
 @deffn Command unbury-buffer
-This command switches to the last buffer in the local buffer list of the
-selected frame.  More precisely, it calls the function
-@code{switch-to-buffer} (@pxref{Displaying Buffers}), to display the
+This command switches to the last buffer in the local buffer list of
+the selected frame.  More precisely, it calls the function
+@code{switch-to-buffer} (@pxref{Switching Buffers}), to display the
 buffer returned by @code{last-buffer}, see above, in the selected
 window.
 @end deffn
diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi
index 3002a4c220d..724c46300fd 100644
--- a/doc/lispref/display.texi
+++ b/doc/lispref/display.texi
@@ -118,15 +118,12 @@ redisplay of all windows.
 to put more work on the queue to be done by redisplay whenever there
 is a chance.
 
-  Emacs redisplay normally stops if input arrives, and does not happen
-at all if input is available before it starts.  Most of the time, this
-is exactly what you want.  However, you can prevent preemption by
-binding @code{redisplay-dont-pause} to a non-@code{nil} value.
-
 @defvar redisplay-dont-pause
-If this variable is non-@code{nil}, pending input does not
-prevent or halt redisplay; redisplay occurs, and finishes,
-regardless of whether input is available.
+If this variable is non-@code{nil}, pending input does not prevent or
+halt redisplay; redisplay occurs, and finishes, regardless of whether
+input is available.  If it is @code{nil}, Emacs redisplay stops if
+input arrives, and does not happen at all if input is available before
+it starts.  The default is @code{t}.
 @end defvar
 
 @defvar redisplay-preemption-period
diff --git a/doc/lispref/elisp.texi b/doc/lispref/elisp.texi
index d3b96a0eb81..8350c9b7080 100644
--- a/doc/lispref/elisp.texi
+++ b/doc/lispref/elisp.texi
@@ -21,7 +21,7 @@
 @end ifset
 
 @c per rms and peterb, use 10pt fonts for the main text, mostly to
-@c save on paper cost.  
+@c save on paper cost.
 @c Do this inside @tex for now, so current makeinfo does not complain.
 @tex
 @ifset smallbook
@@ -935,11 +935,15 @@ Windows
 * Selecting Windows::       The selected window is the one that you edit in.
 * Cyclic Window Ordering::  Moving around the existing windows.
 * Buffers and Windows::     Each window displays the contents of a buffer.
-* Displaying Buffers::      Higher-level functions for displaying a buffer
-                              and choosing a window for it.
+* Switching Buffers::       Higher-level functions for switching to a buffer.
 * Choosing Window::         How to choose a window for displaying a buffer.
+* Display Action Functions:: Subroutines for @code{display-buffer}.
+* Choosing Window Options:: Extra options affecting how buffers are displayed.
+* Window History::          Each window remembers the buffers displayed in it.
 * Dedicated Windows::       How to avoid displaying another buffer in
                               a specific window.
+* Quitting Windows::        How to restore the state prior to displaying a
+                              buffer.
 * Window Point::            Each window has its own location of point.
 * Window Start and End::    Buffer positions indicating which text is
                               on-screen in a window.
diff --git a/doc/lispref/files.texi b/doc/lispref/files.texi
index bd904bf49c0..71b612c527d 100644
--- a/doc/lispref/files.texi
+++ b/doc/lispref/files.texi
@@ -103,7 +103,7 @@ function is basically equivalent to:
 @end smallexample
 
 @noindent
-(See @code{switch-to-buffer} in @ref{Displaying Buffers}.)
+(See @code{switch-to-buffer} in @ref{Switching Buffers}.)
 
 If @var{wildcards} is non-@code{nil}, which is always true in an
 interactive call, then @code{find-file} expands wildcard characters in
@@ -187,8 +187,9 @@ various files.
 
 @deffn Command find-file-other-window filename &optional wildcards
 This command selects a buffer visiting the file @var{filename}, but
-does so in a window other than the selected window.  It may use another
-existing window or split a window; see @ref{Displaying Buffers}.
+does so in a window other than the selected window.  It may use
+another existing window or split a window; see @ref{Switching
+Buffers}.
 
 When this command is called interactively, it prompts for
 @var{filename}.
diff --git a/doc/lispref/vol1.texi b/doc/lispref/vol1.texi
index 1275628cc94..0fa23d6412c 100644
--- a/doc/lispref/vol1.texi
+++ b/doc/lispref/vol1.texi
@@ -953,11 +953,13 @@ Windows
 * Selecting Windows::       The selected window is the one that you edit in.
 * Cyclic Window Ordering::  Moving around the existing windows.
 * Buffers and Windows::     Each window displays the contents of a buffer.
-* Displaying Buffers::      Higher-level functions for displaying a buffer
-                              and choosing a window for it.
+* Switching Buffers::       Higher-level functions for switching to a buffer.
 * Choosing Window::         How to choose a window for displaying a buffer.
+* Display Action Functions:: Subroutines for @code{display-buffer}.
+* Choosing Window Options:: Extra options affecting how buffers are displayed.
+* Window History::          Each window remembers the buffers displayed in it.
 * Dedicated Windows::       How to avoid displaying another buffer in
-                              a specific window.          
+                              a specific window.
 * Window Point::            Each window has its own location of point.
 * Window Start and End::    Buffer positions indicating which text is
                               on-screen in a window.
diff --git a/doc/lispref/vol2.texi b/doc/lispref/vol2.texi
index 3d849fa2dcf..2469a742900 100644
--- a/doc/lispref/vol2.texi
+++ b/doc/lispref/vol2.texi
@@ -952,11 +952,13 @@ Windows
 * Selecting Windows::       The selected window is the one that you edit in.
 * Cyclic Window Ordering::  Moving around the existing windows.
 * Buffers and Windows::     Each window displays the contents of a buffer.
-* Displaying Buffers::      Higher-level functions for displaying a buffer
-                              and choosing a window for it.
+* Switching Buffers::       Higher-level functions for switching to a buffer.
 * Choosing Window::         How to choose a window for displaying a buffer.
+* Display Action Functions:: Subroutines for @code{display-buffer}.
+* Choosing Window Options:: Extra options affecting how buffers are displayed.
+* Window History::          Each window remembers the buffers displayed in it.
 * Dedicated Windows::       How to avoid displaying another buffer in
-                              a specific window.          
+                              a specific window.
 * Window Point::            Each window has its own location of point.
 * Window Start and End::    Buffer positions indicating which text is
                               on-screen in a window.
diff --git a/doc/lispref/windows.texi b/doc/lispref/windows.texi
index b80fe02b0ff..96d489d1203 100644
--- a/doc/lispref/windows.texi
+++ b/doc/lispref/windows.texi
@@ -22,11 +22,15 @@ is displayed in windows.
 * Selecting Windows::       The selected window is the one that you edit in.
 * Cyclic Window Ordering::  Moving around the existing windows.
 * Buffers and Windows::     Each window displays the contents of a buffer.
-* Displaying Buffers::      Higher-level functions for displaying a buffer
-                              and choosing a window for it.
+* Switching Buffers::       Higher-level functions for switching to a buffer.
 * Choosing Window::         How to choose a window for displaying a buffer.
+* Display Action Functions:: Subroutines for @code{display-buffer}.
+* Choosing Window Options:: Extra options affecting how buffers are displayed.
+* Window History::          Each window remembers the buffers displayed in it.
 * Dedicated Windows::       How to avoid displaying another buffer in
                               a specific window.
+* Quitting Windows::        How to restore the state prior to displaying a
+                              buffer.
 * Window Point::            Each window has its own location of point.
 * Window Start and End::    Buffer positions indicating which text is
                               on-screen in a window.
@@ -292,7 +296,7 @@ optional argument @var{window} can be an arbitrary window and defaults
 to the selected one.  The return value is @code{nil} if @var{window} is
 a live window or its children form a vertical combination.  In the
 example above @code{(window-left-child W4)} is @code{W6} while
-@code{(window-top-child W3)} is @code{nil}.
+@code{(window-left-child W3)} is @code{nil}.
 @end defun
 
 @defun window-child window
@@ -1963,7 +1967,6 @@ set of windows to investigate.  See the description of
 @code{next-window} for details.
 @end defun
 
-
 @node Buffers and Windows
 @section Buffers and Windows
 @cindex examining windows
@@ -1982,10 +1985,11 @@ one.  If @var{window} is an internal window, this function returns
 
 The basic, low-level function to associate a window with a buffer is
 @code{set-window-buffer}.  Higher-level functions like
-@code{display-buffer} try to obey a number of user customizations
-regulating which windows are supposed to display which buffers.  When
-writing an application, programmers should therefore carefully evaluate
-whether they really need the power of @code{set-window-buffer}.
+@code{switch-to-buffer} and @code{display-buffer} try to obey a number
+of user customizations regulating which windows are supposed to
+display which buffers.  @xref{Switching Buffers}.  When writing an
+application, you should avoid using @code{set-window-buffer} unless
+you are sure you need it.
 
 @defun set-window-buffer window buffer-or-name &optional keep-margins
 This function makes @var{window} display @var{buffer-or-name} and
@@ -2067,310 +2071,258 @@ The two remaining arguments work like the same-named arguments of
 like the optional arguments of @code{get-buffer-window}.
 @end defun
 
-The following command removes a buffer from all windows showing it.
-
 @deffn Command replace-buffer-in-windows &optional buffer-or-name
-This function replaces @var{buffer-or-name} in all windows displaying it
-with some other buffer.  It uses @code{switch-to-prev-buffer}, see
-below, to choose that other buffer which is usually the last buffer
-displayed before @var{buffer-or-name} in the respective window.
+This command replaces @var{buffer-or-name} with some other buffer, in
+all windows displaying it.  For each such window, it choose another
+buffer using @code{switch-to-prev-buffer} (@pxref{Window History}).
 
-The argument @var{buffer-or-name} may be a buffer or the name of an
-existing buffer and defaults to the current buffer.
+@var{buffer-or-name} may be a buffer, or the name of an existing
+buffer; it defaults to the current buffer.
 
 If a window displaying @var{buffer-or-name} is dedicated
-(@pxref{Dedicated Windows}) has never displayed any other buffers and is
-not the only window on its frame, that window is deleted.  If that
-window is the only window on its frame and there are other frames left,
-the window's frame is deleted too.  If there are no other frames left,
-some other buffer is displayed in that window as explained above.  You
-can prevent the deletion of windows and/or frames by customizing the
-option @var{window-auto-delete}.
-
-This function returns @code{nil}.
+(@pxref{Dedicated Windows}), has never displayed any other buffers and
+is not the only window on its frame, that window is deleted.  If that
+window is the only window on its frame and there are other frames on the
+frame's terminal, that frame is deleted too; otherwise, the buffer
+provided by the function @code{switch-to-prev-buffer} (@pxref{Window
+History}) is displayed instead.
 @end deffn
 
-   When @code{replace-buffer-in-windows} has to show another buffer in a
-window, it tries to pick the buffer shown there before.  For this
-purpose each window remembers the buffers it has displayed earlier and
-the order in which these buffers have been removed from it.
-
-The list of @dfn{previous buffers} of a window is an association list
-where each entry specifies a buffer, the last start position of that
-buffer in the window (@pxref{Window Start and End}) and the last
-position of that buffer's point in the window (@pxref{Window Point}).
-This list is ordered by the times of the removal of the respective
-buffers from the window.  In particular, the first element of the list
-references the buffer removed most recently.  The function
-@code{set-window-buffer} pushes an entry for the old buffer of its
-window argument on that list before it shows its buffer argument in the
-window.
 
-The list of @dfn{next buffers} of a window is a list of buffers that
-have been recently re-shown by the function @code{switch-to-prev-buffer}
-and is used to avoid that that function switches to such a buffer again
-before showing other interesting buffers.
-
-The lists of previous and next buffers and the global buffer list
-(@pxref{The Buffer List}) allow to effectively display all buffers in a
-window while giving preference to the buffers previously shown in that
-window.  The commands used for this purpose are
-@code{switch-to-prev-buffer} and @code{switch-to-next-buffer} described
-below.
+@node Switching Buffers
+@section Switching to a Buffer in a Window
+@cindex switching to a buffer
+@cindex displaying a buffer
 
-The following functions directly operate on the lists of previous and
-next buffers.
+  This section describes high-level functions for switching to a
+specified buffer in some window.
+
+  Do @emph{not} use these functions to make a buffer temporarily
+current just so a Lisp program can access or modify it.  They have
+side-effects, such as changing window histories (@pxref{Window
+History}), which will surprise the user if used that way.  If you want
+to make a buffer current to modify it in Lisp, use
+@code{with-current-buffer}, @code{save-current-buffer}, or
+@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.
+
+If @var{buffer-or-name} is @code{nil}, it defaults to the buffer
+returned by @code{other-buffer} (@pxref{The Buffer List}).  If
+@var{buffer-or-name} is a string that is not the name of any existing
+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
+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
+instead.
+@end deffn
 
-@defun window-prev-buffers &optional window
-This function returns an alist specifying the buffers previously shown
-in @var{window} together with their window start and point positions.
-The argument @var{window} must be a live window and defaults to the
-selected one.
-@end defun
+The next two functions are similar to @code{switch-to-buffer}, except
+for the described features.
 
-@defun set-window-prev-buffers window prev-buffers
-This function sets @var{window}'s previous buffers to the value of
-@var{prev-buffers}.  The argument @var{window} must be a live window and
-defaults to the selected one.  This function returns
-@var{prev-buffers}.
+@deffn Command switch-to-buffer-other-window buffer-or-name &optional norecord
+This function makes the buffer specified by @var{buffer-or-name}
+current and displays it in some window other than the selected window.
+It uses the function @code{pop-to-buffer} internally (see below).
 
-If non-@code{nil}, @var{prev-buffers} must specify an alist of triples
-specifying a buffer and two markers for that buffer's start and point
-position in @var{window}.
-@end defun
+If the selected window already displays the specified buffer, it
+continues to do so, but another window is nonetheless found to display
+it as well.
 
-@defun window-next-buffers &optional window
-This function returns the list of buffers recently re-shown in
-@var{window}.  The argument @var{window} must be a live window and
-defaults to the selected one.
-@end defun
+The @var{buffer-or-name} and @var{norecord} arguments have the same
+meanings as in @code{switch-to-buffer}.
+@end deffn
 
-@defun set-window-next-buffers window next-buffers
-This function sets @var{window}'s next buffers to @var{next-buffers}.
-@var{window} must be a live window and defaults to the selected one.
-This fucntion returns @var{next-buffers}.
+@deffn Command switch-to-buffer-other-frame buffer-or-name &optional norecord
+This function makes the buffer specified by @var{buffer-or-name}
+current and displays it, usually in a new frame.  It uses the function
+@code{pop-to-buffer} (see below).
 
-If non-@code{nil}, the argument @var{next-buffers} should specify a list
-of buffers that shall be preferably not shown by the command
-@code{switch-to-prev-buffer}, see below.
-@end defun
+If the specified buffer is already displayed in another window, in any
+frame on the current terminal, this switches to that window instead of
+creating a new frame.  However, the selected window is never used for
+this.
 
-The following command is used by @code{replace-buffer-in-windows},
-@code{bury-buffer} and @code{quit-window} to show another buffer in a
-window.  It can be also used interactively to cycle through the list of
-all buffers in a window, preferably showing the buffers recently shown
-(but not buried or killed) in that window.
+The @var{buffer-or-name} and @var{norecord} arguments have the same
+meanings as in @code{switch-to-buffer}.
+@end deffn
 
-@deffn Command switch-to-prev-buffer &optional window bury-or-kill
-This function displays the previous buffer in @var{window}.  The
-argument @var{window} must be a live window and defaults to the selected
-one.  If the optional argument @var{bury-or-kill} is non-@code{nil},
-this means that the buffer currently shown in @var{window} is about to
-be buried or killed and consequently shall not be switched to in future
-invocations of this command.
+The above commands use @code{pop-to-buffer}, which is the function
+used by Lisp programs to flexibly display a buffer in some window and
+select that window for editing:
+
+@defun pop-to-buffer buffer-or-name &optional action norecord
+This function makes @var{buffer-or-name} the current buffer and
+displays it in some window, preferably not the window previously
+selected.  It then selects the displaying window.  If that window is
+on a different graphical frame, that frame is given input focus if
+possible (@pxref{Input Focus}).  The return value is the buffer that
+was switched to.
+
+This function uses @code{display-buffer} to display the buffer, so all
+the variables affecting @code{display-buffer} will affect it as well.
+@xref{Choosing Window}.
+
+If @var{buffer-or-name} is @code{nil}, it defaults to the buffer
+returned by @code{other-buffer} (@pxref{The Buffer List}).  If
+@var{buffer-or-name} is a string that is not the name of any existing
+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}).
+
+If @var{action} is non-@code{nil}, it should be a display action to
+pass to @code{display-buffer} (@pxref{Choosing Window}).
+Alternatively, a non-@code{nil}, non-list value means to pop to a
+window other than the selected one---even if the buffer is already
+displayed in the selected window.
+
+Like @code{switch-to-buffer}, this function updates the buffer list
+unless @var{norecord} is non-@code{nil}.
+@end defun
 
-The previous buffer is usually the buffer shown before the buffer
-currently shown in @var{window}.  However, a buffer that has been buried
-or killed or has been already shown by a recent invocation of
-@code{switch-to-prev-buffer} does not qualify as previous buffer.
+@node Choosing Window
+@section Choosing a Window for Display
 
-If repeated invocations of this command have already shown all buffers
-previously shown in @var{window}, further invocations will show buffers
-from the global buffer list starting with the buffer returned by
-@code{last-buffer} (@pxref{The Buffer List}).
-@end deffn
+  The command @code{display-buffer} flexibly chooses a window for
+display, and displays a specified buffer in that window.  It can be
+called interactively, via the key binding @kbd{C-x 4 o}.  It is also
+used as a subroutine by many functions and commands, including
+@code{switch-to-buffer} and @code{pop-to-buffer} (@pxref{Switching
+Buffers}).
+
+@cindex display action
+@cindex action function, for display-buffer
+@cindex action alist, for display-buffer
+  This command performs several complex steps to find a window to
+display in.  These steps are described by means of @dfn{display
+actions}, which have the form @code{(@var{function} . @var{alist})}.
+Here, @var{function} is either a function or a list of functions,
+which we refer to as @dfn{action functions}; @var{alist} is an
+association list, which we refer to as @dfn{action alists}.
+
+  An action function accepts two arguments: the buffer to display and
+an action alist.  It attempts to display the buffer in some window,
+picking or creating a window according to its own criteria.  If
+successful, it returns the window; otherwise, it returns @code{nil}.
+@xref{Display Action Functions}, for a list of predefined action
+functions.
 
-The following command can be used to undo the effect of the last undone
-@code{switch-to-prev-buffer} command.
+  @code{display-buffer} works by combining display actions from
+several sources, and calling the action functions in turn, until one
+of them manages to display the buffer and returns a non-@code{nil}
+value.
 
-@deffn Command switch-to-next-buffer &optional window
-This functions switches to the next buffer in @var{window} thus undoing
-the effect of the last @code{switch-to-prev-buffer} command in
-@var{window}.  The argument @var{window} must be a live window and
-defaults to the selected one.
+@deffn Command display-buffer buffer-or-name &optional action frame
+This command makes @var{buffer-or-name} appear in some window, without
+selecting the window or making the buffer current.  The argument
+@var{buffer-or-name} must be a buffer or the name of an existing
+buffer.  The return value is the window chosen to display the buffer.
 
-If there is no recent invocation of a @code{switch-to-prev-buffer} that
-can be undone, @code{switch-to-next-buffer} will try to show the first
-buffer from the global buffer list as returned by @code{other-buffer}
-(@pxref{The Buffer List}).
-@end deffn
+The optional argument @var{action}, if non-@code{nil}, should normally
+be a display action (described above).  @code{display-buffer} builds a
+list of action functions and an action alist, by consolidating display
+actions from the following sources (in order):
 
-   Together, @code{switch-to-prev-buffer} and
-@code{switch-to-next-buffer} permit to navigate the global buffer list
-much like @code{bury-buffer} and @code{unbury-buffer}.  In contrast with
-the latter, however, they may show a buffer even if it is already shown
-in another window.  Moreover, they try to restore the window specific
-start and point positions of buffers which should handle viewing one and
-the same buffer in multiple windows more easily.
+@itemize
+@item
+The variable @code{display-buffer-overriding-action}.
 
+@item
+The user option @code{display-buffer-alist}.
 
-@node Displaying Buffers
-@section Displaying Buffers in Windows
-@cindex switching to a buffer
-@cindex displaying a buffer
+@item
+The @var{action} argument.
 
-  In this section we describe convenient functions that choose a window
-automatically and use it to display a specified buffer.  These functions
-can also split an existing window in certain circumstances.  We also
-describe variables that parameterize the heuristics used for choosing a
-window.
-@iftex
-See the preceding section for
-@end iftex
-@ifnottex
-@xref{Buffers and Windows}, for
-@end ifnottex
-low-level primitives that give you more precise control.  All of these
-functions work by calling @code{set-window-buffer}.
-
-  Do not use the functions in this section in order to make a buffer
-current so that a Lisp program can access or modify it; they are too
-drastic for that purpose, since they change the display of buffers in
-windows, which would be gratuitous and surprise the user.  Instead, use
-@code{set-buffer} and @code{save-current-buffer} (@pxref{Current
-Buffer}), which designate buffers as current for programmed access
-without affecting the display of buffers in windows.
-
-@deffn Command switch-to-buffer buffer-or-name &optional norecord
-This function makes @var{buffer-or-name} the current buffer, and also
-displays the buffer in the selected window.  This means that a human can
-see the buffer and subsequent keyboard commands will apply to it.
-Contrast this with @code{set-buffer}, which makes @var{buffer-or-name}
-the current buffer but does not display it in the selected window;
-see @ref{Current Buffer}.
-
-If @var{buffer-or-name} is @code{nil}, @code{switch-to-buffer} chooses a
-buffer using @code{other-buffer}.  If @var{buffer-or-name} is a string
-that does not identify an existing buffer, then a new buffer by that
-name is created.  The major mode for the new buffer is set according to
-the variable @code{major-mode}; see @ref{Auto Major Mode}.
-
-When the selected window is the minibuffer window or is strongly
-dedicated to its buffer (@pxref{Dedicated Windows}), this function calls
-@code{pop-to-buffer} (see below) to display the buffer in some other
-window.
+@item
+The user option @code{display-buffer-base-action}.
 
-Normally the specified buffer is put at the front of the buffer list
-(both the selected frame's buffer list and the frame-independent buffer
-list).  This affects the operation of @code{other-buffer}.  However, if
-@var{norecord} is non-@code{nil}, this is not done.  @xref{The Buffer
-List}.
+@item
+The constant @code{display-buffer-fallback-action}.
+@end itemize
 
-The @code{switch-to-buffer} function is often used interactively, as
-the binding of @kbd{C-x b}.  It is also used frequently in programs.  It
-returns the buffer that it switched to.
+@noindent
+Each action function is called in turn, passing the buffer as the
+first argument and the combined action alist as the second argument,
+until one of the functions returns non-nil.
+
+The argument @var{action} can also have a non-@code{nil}, non-list
+value.  This has the special meaning that the buffer should be
+displayed in a window other than the selected one, even if the
+selected window is already displaying it.  If called interactively
+with a prefix argument, @var{action} is @code{t}.
+
+The optional argument @var{frame}, if non-@code{nil}, specifies which
+frames to check when deciding whether the buffer is already displayed.
+It is equivalent to adding an element @code{(reusable-frames
+. @var{frame})} to the action alist of @var{action}.  @xref{Display
+Action Functions}.
 @end deffn
 
-The next two functions are similar to @code{switch-to-buffer}, except
-for the described features.
-
-@deffn Command switch-to-buffer-other-window buffer-or-name &optional norecord
-This function makes the buffer specified by @var{buffer-or-name} current
-and displays it in a window not currently selected, using the function
-@code{pop-to-buffer} (see below).
+@defvar display-buffer-overriding-action
+The value of this variable should be a display action, which is
+treated with the highest priority by @code{display-buffer}.  The
+default value is empty, i.e. @code{(nil . nil)}.
+@end defvar
 
-The currently selected window is absolutely never used to do the job.
-If the selected window already displays @var{buffer-or-name}, then it
-continues to do so, but another window is nonetheless found to display
-it in as well.
+@defopt display-buffer-alist
+The value of this option is an alist mapping regular expressions to
+display actions.  If the name of the buffer passed to
+@code{display-buffer} matches a regular expression in this alist, then
+@code{display-buffer} uses the corresponding display action.
+@end defopt
 
-This function updates the buffer list just like @code{switch-to-buffer}
-unless @var{norecord} is non-@code{nil}.
-@end deffn
+@defopt display-buffer-base-action
+The value of this option should be a display action.  This option can
+be used to define a ``standard'' display action for calls to
+@code{display-buffer}.
+@end defopt
 
-@defun pop-to-buffer buffer-or-name &optional other-window norecord
-This function makes @var{buffer-or-name} the current buffer and switches
-to it in some window, preferably not the window previously selected.
-The ``popped-to'' window becomes the selected window.  Its frame is
-given the X server's focus, if possible; see @ref{Input Focus}.  The
-return value is the buffer that was switched to.
-
-If @var{buffer-or-name} is @code{nil}, that means to choose some other
-buffer, but you don't specify which.  If @var{buffer-or-name} is a
-string that does not name an existing buffer, a buffer by that name is
-created.  The major mode for the new buffer is set according to the
-variable @code{major-mode}.  @xref{Auto Major Mode}.
-
-If either of the variables @code{display-buffer-reuse-frames} or
-@code{pop-up-frames} is non-@code{nil}, @code{pop-to-buffer} looks for a
-window in any visible frame already displaying the buffer; if there is
-one, it selects and returns that window.  If no such window exists and
-@code{pop-up-frames} is non-@code{nil}, it creates a new frame and
-displays the buffer in it.  Otherwise, @code{pop-to-buffer} operates
-entirely within the selected frame.  (If the selected frame has just a
-minibuffer, @code{pop-to-buffer} operates within the most recently
-selected frame that was not just a minibuffer.)
-
-If the variable @code{pop-up-windows} is non-@code{nil}, windows may be
-split to create a new window that is different from the original window.
-For details, see @ref{Choosing Window}.
-
-If @var{other-window} is non-@code{nil}, @code{pop-to-buffer} finds or
-creates another window even if @var{buffer-or-name} is already visible
-in the selected window.  Thus @var{buffer-or-name} could end up
-displayed in two windows.  On the other hand, if @var{buffer-or-name} is
-already displayed in the selected window and @var{other-window} is
-@code{nil}, then the selected window is considered sufficient for
-displaying @var{buffer-or-name}, so that nothing needs to be done.
-
-All the variables that affect @code{display-buffer} affect
-@code{pop-to-buffer} as well.  @xref{Choosing Window}.
-
-This function updates the buffer list just like @code{switch-to-buffer}
-unless @var{norecord} is non-@code{nil}.
-@end defun
+@defvr Constant display-buffer-fallback-action
+This display action specifies the fallback behavior for
+@code{display-buffer} if no other display actions are given.
+@end defvr
 
-@deffn Command replace-buffer-in-windows &optional buffer-or-name
-This function replaces @var{buffer-or-name} in all windows displaying
-it with some other buffer.  It uses @code{other-buffer} to choose the
-other buffer.  In the usual applications of this function, you
-don't care which other buffer is used; you just want to make sure that
-@var{buffer-or-name} is no longer displayed.
+@node Display Action Functions
+@section Action Functions for @code{display-buffer}
 
-The argument @var{buffer-or-name} may be a buffer or the name of an
-existing buffer and defaults to the current buffer.
+The following basic action functions are defined in Emacs.  Each of
+these functions takes two arguments: @var{buffer}, the buffer to
+display, and @var{alist}, an action alist.  Each action function
+returns the window if it succeeds, and @code{nil} if it fails.
 
-If a window displaying @var{buffer-or-name} is dedicated
-(@pxref{Dedicated Windows}), and is not the only window on its frame,
-that window is deleted.  If that window is the only window on its frame
-and there are other frames left, the window's frame is deleted too.  If
-there are no other frames left, some other buffer is displayed in that
-window.
+@defun display-buffer-same-window buffer alist
+This function tries to display @var{buffer} in the selected window.
+It fails if the selected window is a minibuffer window or is dedicated
+to another buffer (@pxref{Dedicated Windows}).  It also fails if
+@var{alist} has a non-nil @code{inhibit-same-window} entry.
+@end defun
 
-This function returns @code{nil}.
-@end deffn
+@defun display-buffer-reuse-window buffer alist
+This function tries to ``display'' @var{buffer} by finding a window
+that is already displaying it.
 
-@node Choosing Window
-@section Choosing a Window for Display
+If @var{alist} has a non-@code{nil} @code{inhibit-same-window} entry,
+the selected window is not eligible for reuse.
 
-  This section describes the basic facility that chooses a window to
-display a buffer in---@code{display-buffer}.  Higher-level functions and
-commands, like @code{switch-to-buffer} and @code{pop-to-buffer}, use this
-subroutine.  Here we describe how to use @code{display-buffer} and how
-to customize it.
-
-@deffn Command display-buffer buffer-or-name &optional not-this-window frame
-This command makes @var{buffer-or-name} appear in some window, but it
-does not select that window and does not make the buffer specified by
-@var{buffer-or-name} current.  The identity of the selected window is
-unaltered by this function.  The argument @var{buffer-or-name} must be a
-buffer or the name of an existing buffer.
-
-@var{not-this-window} non-@code{nil} means to display the specified
-buffer in a window other than the selected one, even if it is already
-displayed in the selected window.  This can cause the buffer to appear
-in two windows at once.  Otherwise, if @var{buffer-or-name} is already
-being displayed in any window, that is good enough, so this function
-does nothing.
-
-@code{display-buffer} returns the window chosen to display
-@var{buffer-or-name}.
-
-If the optional argument @var{frame} is non-@code{nil}, it specifies
-which frames to check when deciding whether the buffer is already
-displayed.  If the buffer is already displayed in some window on one of
-these frames, @code{display-buffer} simply returns that window.  Here
-are the possible values of @var{frame}:
+If @var{alist} contains a @code{reusable-frames} entry, its value
+determines which frames to search for a reusable window:
 
 @itemize @bullet
 @item
@@ -2386,9 +2338,36 @@ are the possible values of @var{frame}:
 A frame means consider windows on that frame only.
 @end itemize
 
-Precisely how @code{display-buffer} finds or creates a window depends on
-the variables described below.
-@end deffn
+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
+@code{pop-up-frames} is non-@code{nil}, it searches all frames on the
+current terminal.  @xref{Choosing Window Options}.
+@end defun
+
+@defun display-buffer-pop-up-frame buffer alist
+This function creates a new frame, and displays the buffer in that
+frame's window.
+@end defun
+
+@defun display-buffer-pop-up-window buffer alist
+This function tries to display @var{buffer} by splitting the selected
+window.  It uses @code{split-window-sensibly} as a subroutine
+(@pxref{Choosing Window Options}).
+@end defun
+
+@defun display-buffer-use-some-window buffer alist
+This function tries to display @var{buffer} by choosing an existing
+window and displaying the buffer in that window.  It can fail if all
+windows are dedicated to another buffer (@pxref{Dedicated Windows}).
+@end defun
+
+@node Choosing Window Options
+@section Additional Options for Displaying Buffers
+
+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 this variable is non-@code{nil}, @code{display-buffer} searches
@@ -2652,6 +2631,101 @@ If all options described above fail to produce a suitable window,
 resort, it will try to display @var{buffer-or-name} on a separate frame.
 In that case, the value of @code{pop-up-frames} is disregarded.
 
+
+@node Window History
+@section Window History
+@cindex window history
+
+Each window remembers the buffers it has displayed earlier and the order
+in which these buffers have been removed from it.  This history is used,
+for example, by @code{replace-buffer-in-windows} (@pxref{Buffers and
+Windows}).  This list is automatically maintained by Emacs, but you can
+use the following functions to explicitly inspect or alter it:
+
+@defun window-prev-buffers &optional window
+This function returns a list specifying the previous contents of
+@var{window}, which should be a live window and defaults to the
+selected window.
+
+Each list element has the form @code{(@var{buffer} @var{window-start}
+@var{window-pos})}, where @var{buffer} is a buffer previously shown in
+the window, @var{window-start} is the window start position when that
+buffer was last shown, and @var{window-pos} is the point position when
+that buffer was last shown.
+
+The list is ordered so that earlier elements correspond to more
+recently-shown buffers, and the first element usually corresponds to the
+buffer most recently removed from the window.
+@end defun
+
+@defun set-window-prev-buffers window prev-buffers
+This function sets @var{window}'s previous buffers to the value of
+@var{prev-buffers}.  The argument @var{window} must be a live window
+and defaults to the selected one.  The argument @var{prev-buffers}
+should be a list of the same form as that returned by
+@code{window-prev-buffers}.
+@end defun
+
+In addition, each buffer maintains a list of @dfn{next buffers}, which
+is a list of buffers re-shown by @code{switch-to-prev-buffer} (see
+below).  This list is mainly used by @code{switch-to-prev-buffer} and
+@code{switch-to-next-buffer} for choosing buffers to switch to.
+
+@defun window-next-buffers &optional window
+This function returns the list of buffers recently re-shown in
+@var{window} via @code{switch-to-prev-buffer}.  The @var{window}
+argument must denote a live window or @code{nil} (meaning the selected
+window).
+@end defun
+
+@defun set-window-next-buffers window next-buffers
+This function sets the next buffer list of @var{window} to
+@var{next-buffers}.  The @var{window} argument should be a live window
+or @code{nil} (meaning the selected window).  The argument
+@var{next-buffers} should be a list of buffers.
+@end defun
+
+The following commands can be used to cycle through the global buffer
+list, much like @code{bury-buffer} and @code{unbury-buffer}.  However,
+they cycle according to the specified window's history list, rather
+than the global buffer list.  In addition, they restore
+window-specific window start and point positions, and may show a
+buffer even if it is already shown in another window.  The
+@code{switch-to-prev-buffer} command, in particular, is used by
+@code{replace-buffer-in-windows}, @code{bury-buffer} and
+@code{quit-window} to find a replacement buffer for a window.
+
+@deffn Command switch-to-prev-buffer &optional window bury-or-kill
+This command displays the previous buffer in @var{window}.  The
+argument @var{window} should be a live window or @code{nil} (meaning
+the selected window).  If the optional argument @var{bury-or-kill} is
+non-@code{nil}, this means that the buffer currently shown in
+@var{window} is about to be buried or killed and consequently shall
+not be switched to in future invocations of this command.
+
+The previous buffer is usually the buffer shown before the buffer
+currently shown in @var{window}.  However, a buffer that has been buried
+or killed or has been already shown by a recent invocation of
+@code{switch-to-prev-buffer} does not qualify as previous buffer.
+
+If repeated invocations of this command have already shown all buffers
+previously shown in @var{window}, further invocations will show buffers
+from the buffer list of the frame @var{window} appears on (@pxref{The
+Buffer List}).
+@end deffn
+
+@deffn Command switch-to-next-buffer &optional window
+This command switches to the next buffer in @var{window} thus undoing
+the effect of the last @code{switch-to-prev-buffer} command in
+@var{window}.  The argument @var{window} must be a live window and
+defaults to the selected one.
+
+If there is no recent invocation of a @code{switch-to-prev-buffer} that
+can be undone, this function tries to show a buffer from the buffer list
+of the frame @var{window} appears on (@pxref{The Buffer List}).
+@end deffn
+
+
 @node Dedicated Windows
 @section Dedicated Windows
 @cindex dedicated window
@@ -2666,15 +2740,15 @@ non-@code{nil}.  The behavior of @code{set-window-buffer}
 (@pxref{Buffers and Windows}) with respect to dedicated windows is
 slightly different, see below.
 
-When @code{delete-windows-on} (@pxref{Deleting Windows}) wants to delete
-a dedicated window and that window is the only window on its frame, it
-deletes the window's frame too, provided there are other frames left.
-@code{replace-buffer-in-windows} (@pxref{Displaying Buffers}) tries to
-delete all dedicated windows showing its buffer argument.  When such a
-window is the only window on its frame, that frame is deleted, provided
-there are other frames left.  If there are no more frames left, some
-other buffer is displayed in the window, and the window is marked as
-non-dedicated.
+When @code{delete-windows-on} (@pxref{Deleting Windows}) wants to
+delete a dedicated window and that window is the only window on its
+frame, it deletes the window's frame too, provided there are other
+frames left.  @code{replace-buffer-in-windows} (@pxref{Switching
+Buffers}) tries to delete all dedicated windows showing its buffer
+argument.  When such a window is the only window on its frame, that
+frame is deleted, provided there are other frames left.  If there are
+no more frames left, some other buffer is displayed in the window, and
+the window is marked as non-dedicated.
 
 When you kill a buffer (@pxref{Killing Buffers}) displayed in a
 dedicated window, any such window usually gets deleted too, since
@@ -2705,6 +2779,59 @@ display.  Other functions do not treat @code{t} differently from any
 non-@code{nil} value.
 @end defun
 
+
+@node Quitting Windows
+@section Quitting Windows
+
+When you want to get rid of a window used for displaying a buffer you
+can use the function @code{delete-window} (@pxref{Deleting Windows}) to
+remove that window from its frame.  If the buffer has been shown on a
+separate frame, you might want to call @code{delete-frame}
+(@pxref{Deleting Frames}) instead.  If, on the other hand, a window has
+been reused for displaying the buffer, you might prefer showing the
+buffer previously shown in that window by calling the function
+@code{switch-to-prev-buffer} (@pxref{Window History}).  Finally, you
+might want to either bury (@pxref{The Buffer List}) or kill
+(@pxref{Killing Buffers}) the window's buffer.
+
+   The following function uses information on how the window for
+displaying the buffer was obtained in the first place thus attempting to
+automatize the above decisions for you.
+
+@deffn Command quit-window &optional kill window
+This command quits @var{window} and buries its buffer.  The argument
+@var{window} must be a live window and defaults to the selected one.
+With prefix argument @var{kill} non-@code{nil}, it kills the buffer
+instead of burying it.
+
+Quitting @var{window} means to proceed as follows: If @var{window} was
+created specially for displaying its current buffer, delete @var{window}
+provided its frame contains at least one other live window.  If
+@var{window} is the only window on its frame and other frames still
+exist, delete the frame together with @var{window}.  If, however, there
+are no other frames left, display some other buffer in @var{window}.
+
+If @var{window} was reused for displaying its buffer, this command tries
+to display the buffer previously shown in it.  It also tries to restore
+the window start (@pxref{Window Start and End}) and point (@pxref{Window
+Point}) positions of the previously shown buffer.  If, in addition, the
+current buffer was temporarily resized, this command will also try to
+restore the original height of @var{window}.
+
+The three cases described so far require that the buffer shown in
+@var{window} is still the buffer displayed by the last buffer display
+function for this window.  If another buffer has been shown in the
+meantime or the buffer previously shown no longer exists, this command
+calls @code{switch-to-prev-buffer} (@pxref{Window History}) to show some
+other buffer instead.
+@end deffn
+
+The function @code{quit-window} bases its decisions on information
+stored in @var{window}'s @code{quit-restore} window parameter
+(@pxref{Window Parameters}) and resets that parameter to @code{nil}
+after it's done.
+
+
 @node Window Point
 @section Windows and Point
 @cindex window position
@@ -3451,14 +3578,13 @@ argument because it always uses the frame that @var{window} is on.
 @cindex window configurations
 @cindex saving window information
 
-  A @dfn{window configuration} records the entire layout of one
+A @dfn{window configuration} records the entire layout of one
 frame---all windows, their sizes, which buffers they contain, how those
 buffers are scrolled, and their values of point and the mark; also their
 fringes, margins, and scroll bar settings.  It also includes the value
 of @code{minibuffer-scroll-window}.  As a special exception, the window
 configuration does not record the value of point in the selected window
-for the current buffer.  Also, the window configuration does not record
-the values of window parameters; see @ref{Window Parameters}.
+for the current buffer.
 
   You can bring back an entire frame layout by restoring a previously
 saved window configuration.  If you want to record the layout of all
@@ -3568,24 +3694,62 @@ sense, but are not implemented because we did not need them.  See the
 file @file{winner.el} for some more operations on windows
 configurations.
 
+  The objects returned by @code{current-window-configuration} die
+together with the Emacs process.  In order to store a window
+configuration on disk and read it back in another Emacs session the
+following two functions can be used.
+
+@defun window-state-get &optional window markers
+This function returns the state of @var{window} as a Lisp object.  The
+argument @var{window} can be any window and defaults to the root window
+of the selected frame.
+
+The optional argument @var{markers} non-@code{nil} means to use markers
+for sampling positions like @code{window-point} or @code{window-start}.
+This argument should be non-@code{nil} only if the value is used for
+putting the state back in the same session since markers slow down
+processing.
+@end defun
+
+The value returned by @code{window-state-get} can be converted by using
+one of the functions defined by Desktop Save Mode (@pxref{Desktop Save
+Mode}) to an object that can be written to a file.  Such objects can be
+read back and converted to a Lisp object representing the state of the
+window.  That Lisp object can be used as argument for the following
+function in order to restore the state window in another window.
+
+@defun window-state-put state &optional window ignore
+This function puts the window state @var{state} into @var{window}.  The
+argument @var{state} should be the state of a window returned by an
+earlier invocation of @code{window-state-get}, see above.  The optional
+argument @var{window} must specify a live window and defaults to the
+selected one.
+
+The optional argument @var{ignore} non-@code{nil} means to ignore
+minimum window sizes and fixed size restrictions.  If @var{ignore}
+equals @code{safe}, this means subwindows can get as small as one line
+and/or two columns.
+@end defun
+
+
 @node Window Parameters
 @section Window Parameters
 @cindex window parameters
 
-This sections describes how window parameters can be used to associate
+This section describes how window parameters can be used to associate
 additional information with windows.
 
 @defun window-parameter window parameter
 This function returns @var{window}'s value for @var{parameter}.  The
-default for @var{window} is the selected window.  If @var{window}
-has no setting for @var{parameter}, this function returns @code{nil}.
+default for @var{window} is the selected window.  If @var{window} has no
+setting for @var{parameter}, this function returns @code{nil}.
 @end defun
 
 @defun window-parameters &optional window
 This function returns all parameters of @var{window} and their values.
-The default for @var{window} is the selected window.  The return value
-is an association list of elements of the form @code{(@var{parameter}
-. @var{value})}.
+The default for @var{window} is the selected window.  The return value,
+if non-@code{nil} is an association list whose elements have the form
+@code{(@var{parameter} . @var{value})}.
 @end defun
 
 @defun set-window-parameter window parameter value
@@ -3594,13 +3758,56 @@ This function sets @var{window}'s value of @var{parameter} to
 is the selected window.
 @end defun
 
-Currently, window parameters are not saved in window configurations and
-consequently not restored by @code{set-window-configuration}.  Hence,
-any change of a parameter introduced via @code{set-window-parameter} can
-be undone only by invoking @code{set-window-parameter} for the same
-parameter again.  Since @code{save-window-excursion} relies on window
-configurations (@pxref{Window Configurations}), window parameters are
-not saved and restored by that special form, either.
+Some functions, notably @code{delete-window},
+@code{delete-other-windows} and @code{split-window} may behave specially
+when their @var{window} argument has a parameter set.  You can override
+such special behavior by binding the following variable to a
+non-@code{nil} value:
+
+@defvar ignore-window-parameters
+If this variable is non-@code{nil}, some standard functions do not
+process window parameters.  The functions currently affected by this are
+@code{split-window}, @code{delete-window}, @code{delete-other-windows}
+and @code{other-window}.
+
+An application can bind this variable to a non-@code{nil} value around
+calls to these functions.  If it does so, the application is fully
+responsible for correctly assigning the parameters of all involved
+windows when exiting that function.
+@end defvar
+
+The following parameters are currently used by the window management
+code.
+
+@table @asis
+@item @code{delete-window}
+This parameter affects the execution of @code{delete-window}
+(@pxref{Deleting Windows}).
+
+@item @code{delete-other-windows}
+This parameter affects the execution of @code{delete-other-windows}
+(@pxref{Deleting Windows}).
+
+@item @code{split-window}
+This parameter affects the execution of @code{split-window}
+(@pxref{Splitting Windows}).
+
+@item @code{other-window}
+This parameter affects the execution of @code{other-window}
+(@pxref{Cyclic Window Ordering}).
+
+@item @code{no-other-window}
+This parameter marks the window as not selectable by @code{other-window}
+(@pxref{Cyclic Window Ordering}).
+@end table
+
+In addition, the parameters @code{window-atom} and @code{window-side}
+are reserved and should not be used by applications.  The
+@code{quit-restore} parameter tells how to proceed with a window when
+the buffer it shows is no more needed.  This parameter is installed by
+the buffer display functions (@pxref{Choosing Window}) and consulted by
+the function @code{quit-window} (@pxref{Quitting Windows}).
+
 
 @node Window Hooks
 @section Hooks for Window Scrolling and Changes
diff --git a/doc/man/emacs.1 b/doc/man/emacs.1
index aef5bd402a2..60dfe3806c0 100644
--- a/doc/man/emacs.1
+++ b/doc/man/emacs.1
@@ -1,5 +1,5 @@
 .\" See section COPYING for copyright and redistribution information.
-.TH EMACS 1 "2007 April 13" "GNU Emacs 24.0.50"
+.TH EMACS 1 "2007 April 13" "GNU Emacs 24.0.90"
 .
 .
 .SH NAME
diff --git a/doc/misc/texinfo.tex b/doc/misc/texinfo.tex
index a7f94f96daa..3298298bb9d 100644
--- a/doc/misc/texinfo.tex
+++ b/doc/misc/texinfo.tex
@@ -3,7 +3,7 @@
 % Load plain if necessary, i.e., if running under initex.
 \expandafter\ifx\csname fmtname\endcsname\relax\input plain\fi
 %
-\def\texinfoversion{2011-08-14.17}
+\def\texinfoversion{2011-09-23.09}
 %
 % Copyright 1985, 1986, 1988, 1990, 1991, 1992, 1993, 1994, 1995,
 % 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006,
@@ -3955,13 +3955,13 @@ end
 %        If so, set to same dimension as multitablelinespace.
 \ifdim\multitableparskip>\multitablelinespace
 \global\multitableparskip=\multitablelinespace
-\global\advance\multitableparskip-7pt %% to keep parskip somewhat smaller
-                                      %% than skip between lines in the table.
+\global\advance\multitableparskip-7pt % to keep parskip somewhat smaller
+                                      % than skip between lines in the table.
 \fi%
 \ifdim\multitableparskip=0pt
 \global\multitableparskip=\multitablelinespace
-\global\advance\multitableparskip-7pt %% to keep parskip somewhat smaller
-                                      %% than skip between lines in the table.
+\global\advance\multitableparskip-7pt % to keep parskip somewhat smaller
+                                      % than skip between lines in the table.
 \fi}
 
 
@@ -7247,9 +7247,15 @@ end
 \def\macroxxx#1{%
   \getargs{#1}% now \macname is the macname and \argl the arglist
   \ifx\argl\empty       % no arguments
-     \paramno=0
+     \paramno=0\relax
   \else
      \expandafter\parsemargdef \argl;%
+     \if\paramno>256\relax
+       \ifx\eTeXversion\thisisundefined
+         \errhelp = \EMsimple
+         \errmessage{You need eTeX to compile a file with macros with more than 256 arguments}
+       \fi
+     \fi
   \fi
   \if1\csname ismacro.\the\macname\endcsname
      \message{Warning: redefining \the\macname}%
@@ -7299,9 +7305,17 @@ end
 \def\getmacname#1 #2\relax{\macname={#1}}
 \def\getmacargs#1{\def\argl{#1}}
 
+% For macro processing make @ a letter so that we can make Texinfo private macro names.
+\edef\texiatcatcode{\the\catcode`\@}
+\catcode `@=11\relax
+
 % Parse the optional {params} list.  Set up \paramno and \paramlist
-% so \defmacro knows what to do.  Define \macarg.blah for each blah
-% in the params list to be ##N where N is the position in that list.
+% so \defmacro knows what to do.  Define \macarg.BLAH for each BLAH
+% in the params list to some hook where the argument si to be expanded.  If
+% there are less than 10 arguments that hook is to be replaced by ##N where N
+% is the position in that list, that is to say the macro arguments are to be
+% defined `a la TeX in the macro body.  
+%
 % That gets used by \mbodybackslash (above).
 %
 % We need to get `macro parameter char #' into several definitions.
@@ -7311,12 +7325,33 @@ end
 %
 % The same technique is used to protect \eatspaces till just before
 % the macro is used.
-
+%
+% If there are 10 or more arguments, a different technique is used, where the
+% hook remains in the body, and when macro is to be expanded the body is
+% processed again to replace the arguments.
+%
+% In that case, the hook is \the\toks N-1, and we simply set \toks N-1 to the
+% argument N value and then \edef  the body (nothing else will expand because of
+% the catcode regime underwhich the body was input).
+%
+% If you compile with TeX (not eTeX), and you have macros with 10 or more
+% arguments, you need that no macro has more than 256 arguments, otherwise an
+% error is produced.
 \def\parsemargdef#1;{%
   \paramno=0\def\paramlist{}%
   \let\hash\relax
   \let\xeatspaces\relax
   \parsemargdefxxx#1,;,%
+  % In case that there are 10 or more arguments we parse again the arguments
+  % list to set new definitions for the \macarg.BLAH macros corresponding to
+  % each BLAH argument. It was anyhow needed to parse already once this list
+  % in order to count the arguments, and as macros with at most 9 arguments
+  % are by far more frequent than macro with 10 or more arguments, defining
+  % twice the \macarg.BLAH macros does not cost too much processing power.
+  \ifnum\paramno<10\relax\else
+    \paramno0\relax
+    \parsemmanyargdef@@#1,;,% 10 or more arguments
+  \fi
 }
 \def\parsemargdefxxx#1,{%
   \if#1;\let\next=\relax
@@ -7327,16 +7362,205 @@ end
     \edef\paramlist{\paramlist\hash\the\paramno,}%
   \fi\next}
 
+\def\parsemmanyargdef@@#1,{%
+  \if#1;\let\next=\relax
+  \else 
+    \let\next=\parsemmanyargdef@@
+    \edef\tempb{\eatspaces{#1}}%
+    \expandafter\def\expandafter\tempa
+       \expandafter{\csname macarg.\tempb\endcsname}%
+    % Note that we need some extra \noexpand\noexpand, this is because we
+    % don't want \the  to be expanded in the \parsermacbody  as it uses an
+    % \xdef .
+    \expandafter\edef\tempa
+      {\noexpand\noexpand\noexpand\the\toks\the\paramno}%
+    \advance\paramno by 1\relax
+  \fi\next}
+
 % These two commands read recursive and nonrecursive macro bodies.
 % (They're different since rec and nonrec macros end differently.)
 %
+
+\catcode `\@\texiatcatcode
 \long\def\parsemacbody#1@end macro%
 {\xdef\temp{\eatcr{#1}}\endgroup\defmacro}%
 \long\def\parsermacbody#1@end rmacro%
 {\xdef\temp{\eatcr{#1}}\endgroup\defmacro}%
+\catcode `\@=11\relax
+
+\let\endargs@\relax
+\let\nil@\relax
+\def\nilm@{\nil@}%
+\long\def\nillm@{\nil@}%
+
+% This macro is expanded during the Texinfo macro expansion, not during its
+% definition.  It gets all the arguments values and assigns them to macros
+% macarg.ARGNAME
+%
+% #1 is the macro name
+% #2 is the list of argument names
+% #3 is the list of argument values
+\def\getargvals@#1#2#3{%
+  \def\macargdeflist@{}%
+  \def\saveparamlist@{#2}% Need to keep a copy for parameter expansion.
+  \def\paramlist{#2,\nil@}%
+  \def\macroname{#1}%
+  \begingroup
+  \macroargctxt
+  \def\argvaluelist{#3,\nil@}%
+  \def\@tempa{#3}%
+  \ifx\@tempa\empty
+    \setemptyargvalues@
+  \else
+    \getargvals@@
+  \fi
+}
 
-% This defines the macro itself. There are six cases: recursive and
-% nonrecursive macros of zero, one, and many arguments.
+% 
+\def\getargvals@@{%
+  \ifx\paramlist\nilm@
+      % Some sanity check needed here that \argvaluelist is also empty.
+      \ifx\argvaluelist\nillm@
+      \else
+        \errhelp = \EMsimple
+        \errmessage{Too many arguments in macro `\macroname'!}%
+      \fi
+      \let\next\macargexpandinbody@
+  \else
+    \ifx\argvaluelist\nillm@
+       % No more arguments values passed to macro.  Set remaining named-arg
+       % macros to empty.
+       \let\next\setemptyargvalues@
+    \else
+      % pop current arg name into \@tempb
+      \def\@tempa##1{\pop@{\@tempb}{\paramlist}##1\endargs@}%
+      \expandafter\@tempa\expandafter{\paramlist}%
+       % pop current argument value into \@tempc
+      \def\@tempa##1{\longpop@{\@tempc}{\argvaluelist}##1\endargs@}%
+      \expandafter\@tempa\expandafter{\argvaluelist}%
+       % Here \@tempb is the current arg name and \@tempc is the current arg value.
+       % First place the new argument macro definition into \@tempd
+       \expandafter\macname\expandafter{\@tempc}%
+       \expandafter\let\csname macarg.\@tempb\endcsname\relax
+       \expandafter\def\expandafter\@tempe\expandafter{%
+         \csname macarg.\@tempb\endcsname}%
+       \edef\@tempd{\long\def\@tempe{\the\macname}}%
+       \push@\@tempd\macargdeflist@
+       \let\next\getargvals@@
+    \fi
+  \fi
+  \next
+}
+
+\def\push@#1#2{%
+  \expandafter\expandafter\expandafter\def
+  \expandafter\expandafter\expandafter#2%
+  \expandafter\expandafter\expandafter{%
+  \expandafter#1#2}%
+}
+
+% Replace arguments by their values in the macro body, and place the result
+% in macro \@tempa
+\def\macvalstoargs@{%
+  %  To do this we use the property that token registers that are \the'ed
+  % within an \edef  expand only once. So we are going to place all argument
+  % values into respective token registers.
+  %
+  % First we save the token context, and initialize argument numbering.
+  \begingroup
+    \paramno0\relax
+    % Then, for each argument number #N, we place the corresponding argument
+    % value into a new token list register \toks#N
+    \expandafter\putargsintokens@\saveparamlist@,;,%
+    % Then, we expand the body so that argument are replaced by their
+    % values. The trick for values not to be expanded themselves is that they
+    % are within tokens and that tokens expand only once in an \edef .
+    \edef\@tempc{\csname mac.\macroname .body\endcsname}%
+    % Now we restore the token stack pointer to free the token list registers
+    % which we have used, but we make sure that expanded body is saved after
+    % group.
+    \expandafter
+  \endgroup
+  \expandafter\def\expandafter\@tempa\expandafter{\@tempc}%
+  }
+
+\def\macargexpandinbody@{% 
+  %% Define the named-macro outside of this group and then close this group. 
+  \expandafter
+  \endgroup
+  \macargdeflist@
+  % First the replace in body the macro arguments by their values, the result
+  % is in \@tempa .
+  \macvalstoargs@
+  % Then we point at the \norecurse or \gobble (for recursive) macro value
+  % with \@tempb .
+  \expandafter\let\expandafter\@tempb\csname mac.\macroname .recurse\endcsname
+  % Depending on whether it is recursive or not, we need some tailing
+  % \egroup .
+  \ifx\@tempb\gobble
+     \let\@tempc\relax
+  \else
+     \let\@tempc\egroup
+  \fi
+  % And now we do the real job:
+  \edef\@tempd{\noexpand\@tempb{\macroname}\noexpand\scanmacro{\@tempa}\@tempc}%
+  \@tempd
+}
+
+\def\putargsintokens@#1,{%
+  \if#1;\let\next\relax
+  \else
+    \let\next\putargsintokens@
+    % First we allocate the new token list register, and give it a temporary
+    % alias \@tempb .
+    \toksdef\@tempb\the\paramno
+    % Then we place the argument value into that token list register.
+    \expandafter\let\expandafter\@tempa\csname macarg.#1\endcsname
+    \expandafter\@tempb\expandafter{\@tempa}%
+    \advance\paramno by 1\relax
+  \fi
+  \next
+}
+
+% Save the token stack pointer into macro #1
+\def\texisavetoksstackpoint#1{\edef#1{\the\@cclvi}}
+% Restore the token stack pointer from number in macro #1
+\def\texirestoretoksstackpoint#1{\expandafter\mathchardef\expandafter\@cclvi#1\relax}
+% newtoks that can be used non \outer .
+\def\texinonouternewtoks{\alloc@ 5\toks \toksdef \@cclvi}
+
+% Tailing missing arguments are set to empty
+\def\setemptyargvalues@{%
+  \ifx\paramlist\nilm@
+    \let\next\macargexpandinbody@
+  \else
+    \expandafter\setemptyargvaluesparser@\paramlist\endargs@
+    \let\next\setemptyargvalues@
+  \fi
+  \next
+}
+
+\def\setemptyargvaluesparser@#1,#2\endargs@{%
+  \expandafter\def\expandafter\@tempa\expandafter{%
+    \expandafter\def\csname macarg.#1\endcsname{}}%
+  \push@\@tempa\macargdeflist@
+  \def\paramlist{#2}%
+}
+
+% #1 is the element target macro
+% #2 is the list macro
+% #3,#4\endargs@ is the list value
+\def\pop@#1#2#3,#4\endargs@{%
+   \def#1{#3}%
+   \def#2{#4}%
+}
+\long\def\longpop@#1#2#3,#4\endargs@{%
+   \long\def#1{#3}%
+   \long\def#2{#4}%
+}
+
+% This defines a Texinfo @macro. There are eight cases: recursive and
+% nonrecursive macros of zero, one, up to nine, and many arguments.
 % Much magic with \expandafter here.
 % \xdef is used so that macro definitions will survive the file
 % they're defined in; @include reads the file inside a group.
@@ -7355,17 +7579,25 @@ end
          \expandafter\noexpand\csname\the\macname xxx\endcsname}%
       \expandafter\xdef\csname\the\macname xxx\endcsname##1{%
          \egroup\noexpand\scanmacro{\temp}}%
-    \else % many
-      \expandafter\xdef\csname\the\macname\endcsname{%
-         \bgroup\noexpand\macroargctxt
-         \noexpand\csname\the\macname xx\endcsname}%
-      \expandafter\xdef\csname\the\macname xx\endcsname##1{%
-          \expandafter\noexpand\csname\the\macname xxx\endcsname ##1,}%
-      \expandafter\expandafter
-      \expandafter\xdef
-      \expandafter\expandafter
-        \csname\the\macname xxx\endcsname
-          \paramlist{\egroup\noexpand\scanmacro{\temp}}%
+    \else
+      \ifnum\paramno<10\relax % at most 9
+        \expandafter\xdef\csname\the\macname\endcsname{%
+           \bgroup\noexpand\macroargctxt
+           \noexpand\csname\the\macname xx\endcsname}%
+        \expandafter\xdef\csname\the\macname xx\endcsname##1{%
+            \expandafter\noexpand\csname\the\macname xxx\endcsname ##1,}%
+        \expandafter\expandafter
+        \expandafter\xdef
+        \expandafter\expandafter
+          \csname\the\macname xxx\endcsname
+            \paramlist{\egroup\noexpand\scanmacro{\temp}}%
+      \else % 10 or more
+        \expandafter\xdef\csname\the\macname\endcsname{%
+          \noexpand\getargvals@{\the\macname}{\argl}%
+        }%    
+        \global\expandafter\let\csname mac.\the\macname .body\endcsname\temp
+        \global\expandafter\let\csname mac.\the\macname .recurse\endcsname\gobble
+      \fi
     \fi
   \else
     \ifcase\paramno
@@ -7382,23 +7614,33 @@ end
         \egroup
         \noexpand\norecurse{\the\macname}%
         \noexpand\scanmacro{\temp}\egroup}%
-    \else % many
-      \expandafter\xdef\csname\the\macname\endcsname{%
-         \bgroup\noexpand\macroargctxt
-         \expandafter\noexpand\csname\the\macname xx\endcsname}%
-      \expandafter\xdef\csname\the\macname xx\endcsname##1{%
-          \expandafter\noexpand\csname\the\macname xxx\endcsname ##1,}%
-      \expandafter\expandafter
-      \expandafter\xdef
-      \expandafter\expandafter
-      \csname\the\macname xxx\endcsname
-      \paramlist{%
-          \egroup
-          \noexpand\norecurse{\the\macname}%
-          \noexpand\scanmacro{\temp}\egroup}%
+    \else % at most 9
+      \ifnum\paramno<10\relax
+        \expandafter\xdef\csname\the\macname\endcsname{%
+           \bgroup\noexpand\macroargctxt
+           \expandafter\noexpand\csname\the\macname xx\endcsname}%
+        \expandafter\xdef\csname\the\macname xx\endcsname##1{%
+            \expandafter\noexpand\csname\the\macname xxx\endcsname ##1,}%
+        \expandafter\expandafter
+        \expandafter\xdef
+        \expandafter\expandafter
+        \csname\the\macname xxx\endcsname
+        \paramlist{%
+            \egroup
+            \noexpand\norecurse{\the\macname}%
+            \noexpand\scanmacro{\temp}\egroup}%
+      \else % 10 or more:
+        \expandafter\xdef\csname\the\macname\endcsname{%
+          \noexpand\getargvals@{\the\macname}{\argl}%
+        }%
+        \global\expandafter\let\csname mac.\the\macname .body\endcsname\temp
+        \global\expandafter\let\csname mac.\the\macname .recurse\endcsname\norecurse
+      \fi
     \fi
   \fi}
 
+\catcode `\@\texiatcatcode\relax
+
 \def\norecurse#1{\bgroup\cslet{#1}{macsave.#1}}
 
 % \braceorline decides whether the next nonwhitespace character is a