[Emacs-diffs] /srv/bzr/emacs/trunk r105915: Document display-buffer-alist and related variables in Lisp manual.

[Chong Yidong]

------------------------------------------------------------
revno: 105915
committer: Chong Yidong <address@hidden>
branch nick: trunk
timestamp: Sat 2011-09-24 23:32:51 -0400
message:
  Document display-buffer-alist and related variables in Lisp manual.
  
  * doc/lispref/windows.texi (Display Action Functions)
  (Choosing Window Options): New nodes.
modified:
  doc/lispref/ChangeLog
  doc/lispref/elisp.texi
  doc/lispref/vol1.texi
  doc/lispref/vol2.texi
  doc/lispref/windows.texi

=== modified file 'doc/lispref/ChangeLog'
--- a/doc/lispref/ChangeLog     2011-09-24 22:49:32 +0000
+++ b/doc/lispref/ChangeLog     2011-09-25 03:32:51 +0000
@@ -1,3 +1,8 @@
+2011-09-25  Chong Yidong  <address@hidden>
+
+       * windows.texi (Display Action Functions)
+       (Choosing Window Options): New nodes.
+
 2011-09-24  Chong Yidong  <address@hidden>
 
        * windows.texi (Window History): New node.  Move text here from

=== modified file 'doc/lispref/elisp.texi'
--- a/doc/lispref/elisp.texi    2011-09-24 22:49:32 +0000
+++ b/doc/lispref/elisp.texi    2011-09-25 03:32:51 +0000
@@ -937,6 +937,8 @@
 * Buffers and Windows::     Each window displays the contents of a buffer.
 * 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.

=== modified file 'doc/lispref/vol1.texi'
--- a/doc/lispref/vol1.texi     2011-09-24 22:49:32 +0000
+++ b/doc/lispref/vol1.texi     2011-09-25 03:32:51 +0000
@@ -955,6 +955,8 @@
 * Buffers and Windows::     Each window displays the contents of a buffer.
 * 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.

=== modified file 'doc/lispref/vol2.texi'
--- a/doc/lispref/vol2.texi     2011-09-24 22:49:32 +0000
+++ b/doc/lispref/vol2.texi     2011-09-25 03:32:51 +0000
@@ -954,6 +954,8 @@
 * Buffers and Windows::     Each window displays the contents of a buffer.
 * 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.

=== modified file 'doc/lispref/windows.texi'
--- a/doc/lispref/windows.texi  2011-09-24 22:49:32 +0000
+++ b/doc/lispref/windows.texi  2011-09-25 03:32:51 +0000
@@ -24,6 +24,8 @@
 * Buffers and Windows::     Each window displays the contents of a buffer.
 * 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.
@@ -2094,11 +2096,12 @@
 specified buffer in some window.
 
   Do @emph{not} use these functions to make a buffer temporarily
-current so that a Lisp program can access or modify it; they have
-side-effects that may surprise the user, such as changing window
-histories (@pxref{Window History}).  Instead, use
+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
address@hidden (@pxref{Current Buffer}).
address@hidden  @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,
@@ -2203,24 +2206,25 @@
 Buffers}).
 
 @cindex display action
address@hidden action function, for display-buffer
address@hidden 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,
-while @var{alist} is an association list.  In this section, we will
-refer to such functions as @dfn{action functions}, and such alists as
address@hidden alists}.
+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 should accept two arguments: the buffer to
-display and an action alist.  It should attempt to display the buffer
-in some window, picking or creating a window based on some internal
-criteria (as well as, optionally, the action alist).  If successful,
-it should return the window; otherwise, it should return @code{nil}.
+  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}.
address@hidden Action Functions}, for a list of predefined action
+functions.
 
   @code{display-buffer} works by combining display actions from
-several sources (including some user-customizable options), and
-calling the action functions in turn, until one of the action
-functions manages to display the buffer and returns a address@hidden
+several sources, and calling the action functions in turn, until one
+of them manages to display the buffer and returns a address@hidden
 value.
 
 @deffn Command display-buffer buffer-or-name &optional action frame
@@ -2248,9 +2252,7 @@
 The user option @code{display-buffer-base-action}.
 
 @item
-The variable @code{display-buffer-fallback-action}.  This is
address@hidden by default, and specifies the fallback behavior if no
-other display actions are given.
+The constant @code{display-buffer-fallback-action}.
 @end itemize
 
 @noindent
@@ -2266,9 +2268,59 @@
 
 The optional argument @var{frame}, if address@hidden, 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}:
+It is equivalent to adding an element @code{(reusable-frames
+. @var{frame})} to the action alist of @var{action}.  @xref{Display
+Action Functions}.
address@hidden deffn
+
address@hidden 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)}.
address@hidden defvar
+
address@hidden 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
address@hidden matches a regular expression in this alist, then
address@hidden uses the corresponding display action.
address@hidden defopt
+
address@hidden 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
address@hidden
address@hidden defopt
+
address@hidden Constant display-buffer-fallback-action
+This display action specifies the fallback behavior for
address@hidden if no other display actions are given.
address@hidden defvr
+
address@hidden Display Action Functions
address@hidden Action Functions for @code{display-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.
+
address@hidden 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
address@hidden has a non-nil @code{inhibit-same-window} entry.
address@hidden defun
+
address@hidden display-buffer-reuse-window buffer alist
+This function tries to ``display'' @var{buffer} by finding a window
+that is already displaying it.
+
+If @var{alist} has a address@hidden @code{inhibit-same-window} entry,
+the selected window is not eligible for reuse.
+
+If @var{alist} contains a @code{reusable-frames} entry, its value
+determines which frames to search for a reusable window:
 
 @itemize @bullet
 @item
@@ -2284,9 +2336,36 @@
 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.
address@hidden 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
address@hidden is address@hidden, it searches all frames on the
+current terminal.  @xref{Choosing Window Options}.
address@hidden defun
+
address@hidden display-buffer-pop-up-frame buffer alist
+This function creates a new frame, and displays the buffer in that
+frame's window.
address@hidden defun
+
address@hidden 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}).
address@hidden defun
+
address@hidden display-buffer-use-some-window buffer alist
+This function tries to display @var{buffer} by choosing an existing
+buffer and displaying the buffer in that window.  It can fail if all
+windows are dedicated to another buffer (@pxref{Dedicated Windows}).
address@hidden defun
+
address@hidden Choosing Window Options
address@hidden 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 address@hidden, @code{display-buffer} searches