Commits

Kenichi Handa  committed 196662c Merge

merge trunk

  • Participants
  • Parent commits 6e6ab2b, 217c4bb

Comments (0)

Files changed (128)

+2011-09-26  Paul Eggert  <eggert@cs.ucla.edu>
+
+	Merge from gnulib, improving some licensing wording.
+	This clarifies and fixes some licensing issues raised by Glenn Morris
+	<http://lists.gnu.org/archive/html/bug-gnulib/2011-09/msg00397.html>.
+	It also merges the latest version of texinfo.tex and has some
+	MSVC-related changes that don't affect Emacs.
+	* Makefile.in (GNULIB_TOOL_FLAGS): Avoid msvc-inval, msvc-nothrow,
+	pathmax, and raise, since these are needed only to address
+	MSVC-related issues that Emacs doesn't have.
+	* doc/misc/texinfo.tex, lib/dup2.c, lib/gnulib.mk, lib/signal.in.h:
+	* lib/sigprocmask.c, lib/stat.c, lib/stdio.in.h, lib/sys_stat.in.h:
+	* lib/unistd.in.h, m4/dup2.m4, m4/getloadavg.m4, m4/gl-comp.m4:
+	* m4/include_next.m4, m4/signal_h.m4, m4/signalblocking.m4:
+	* m4/stdint.m4, m4/stdio_h.m4, m4/sys_stat_h.m4, m4/time_h.m4:
+	* m4/unistd_h.m4: Merge from gnulib.
+
+2011-09-26  Andreas Schwab  <schwab@linux-m68k.org>
+
+	* configure.in: Initialize HAVE_LIBXML2.
+
+2011-09-26  Glenn Morris  <rgm@gnu.org>
+
+	* make-dist: Add lib/makefile.w32-in.
+
+2011-09-24  Glenn Morris  <rgm@gnu.org>
+
+	* configure.in (CRT_DIR): Fix netbsd/openbsd handling.
+
 2011-09-19  Lars Magne Ingebrigtsen  <larsi@gnus.org>
 
 	* .dir-locals.el: Change the debbugs regexp to allow having the
   mktime pthread_sigmask readlink \
   socklen stdarg stdio strftime strtoimax strtoumax symlink sys_stat
 GNULIB_TOOL_FLAGS = \
- --avoid=threadlib \
+ --avoid=msvc-inval --avoid=msvc-nothrow --avoid=pathmax \
+ --avoid=raise --avoid=threadlib \
  --conditional-dependencies --import --no-changelog --no-vc-files \
  --makefile-name=gnulib.mk
 sync-from-gnulib: $(gnulib_srcdir)
 See the end of the file for license conditions.
 
 
-This directory tree holds version 24.0.50 of GNU Emacs, the extensible,
+This directory tree holds version 24.0.90 of GNU Emacs, the extensible,
 customizable, self-documenting real-time display editor.
 
 The file INSTALL in this directory says how to build and install GNU

File admin/ChangeLog

+2011-09-26  Chong Yidong  <cyd@stupidchicken.com>
+
+	* admin.el (set-version): Fix regexps for config.nt and
+	sed2v2.inp.
+
 2011-09-06  Paul Eggert  <eggert@cs.ucla.edu>
 
 	Merge from gnulib (Bug#9169).

File admin/admin.el

 				(submatch (1+ (in "0-9."))))))
   (set-version-in-file root "nt/config.nt" version
 		       (rx (and bol "#" (0+ blank) "define" (1+ blank)
-				"VERSION" (1+ blank)
+				"VERSION" (1+ blank) "\""
 				(submatch (1+ (in "0-9."))))))
   (set-version-in-file root "msdos/sed2v2.inp" version
 		       (rx (and bol "/^#undef " (1+ not-newline)
-				"define VERSION" (1+ space)
+				"define VERSION" (1+ space) "\""
 				(submatch (1+ (in "0-9."))))))
   (set-version-in-file root "nt/makefile.w32-in" version
 		       (rx (and "VERSION" (0+ space) "=" (0+ space)

File admin/make-tarball.txt

     number of the old Emacs to __, do the same with the new log and do
     M-x ediff.  Especially check that Info files aren't built.
 
-10.  cd EMACS_ROOT_DIR; cvs tag TAG
+10.  cd EMACS_ROOT_DIR; bzr tag TAG
     TAG is EMACS_PRETEST_XX_YY_ZZZ for a pretest, EMACS_XX_YY for a
     release.
 
-    Shortly before the release, cut the branch with the following commands:
-
-    cvs rtag EMACS_`NUMBER'_BASE
-    cvs rtag -b EMACS_`NUMBER'_RC -r EMACS_`NUMBER'_BASE
-
-    where `NUMBER' is the major version number of the release.  This
-    makes it easier to see what changes have been applied to the
-    branch with:
-
-    cvs diff -r EMACS_`NUMBER'_BASE -r EMACS_`NUMBER'_RC
-
-    or merge changes back to the trunk with "cvs update -j", if
-    necessary.
-
-    After doing this, increase the version number on the trunk as per
-    step 4.
-
-    Also, open a Savannah support request asking for commits to the
-    new branch to be sent to the emacs-diffs mailing list (by default,
-    the list normally only gets commits to the trunk).
+    Shortly before the release, cut the version branch also, and open
+    a Savannah support request asking for commits to the new branch to
+    be sent to the emacs-diffs mailing list (by default, the list
+    normally only gets commits to the trunk).
 
 11. Now you should upload the files to the GNU ftp server.  In order to
     do that, you must be registered as an Emacs maintainer and have your
     GPG key acknowledged by the ftp people.  Mail <ftp-upload@gnu.org>
-    for instructions.  Once you are there, for each file FILE to be
-    released, create a detached GPG binary signature and a clearsigned
-    directive file like this:
+    for instructions.
+
+    You can use the gnupload script to upload each FILE, like this:
+     gnupload --to alpha.gnu.org:emacs/pretest FILE (for a pretest)
+     gnupload --to ftp.gnu.org:emacs FILE           (for a release)
+
+    Instead of using gnupload, for each FILE, create a detached GPG
+    binary signature and a clearsigned directive file like this:
      gpg -b FILE
      echo directory: emacs/pretest > FILE.directive      (for a pretest)
      echo directory: emacs > FILE.directive              (for a release)

File autogen/configure

 #! /bin/sh
 # Guess values for system-dependent variables and create Makefiles.
-# Generated by GNU Autoconf 2.65 for emacs 24.0.50.
+# Generated by GNU Autoconf 2.65 for emacs 24.0.90.
 #
 #
 # Copyright (C) 1992, 1993, 1994, 1995, 1996, 1998, 1999, 2000, 2001,
 # Identity of this package.
 PACKAGE_NAME='emacs'
 PACKAGE_TARNAME='emacs'
-PACKAGE_VERSION='24.0.50'
-PACKAGE_STRING='emacs 24.0.50'
+PACKAGE_VERSION='24.0.90'
+PACKAGE_STRING='emacs 24.0.90'
 PACKAGE_BUGREPORT=''
 PACKAGE_URL=''
 
   # Omit some internal or obsolete options to make the list less imposing.
   # This message is too long to be a string in the A/UX 3.1 sh.
   cat <<_ACEOF
-\`configure' configures emacs 24.0.50 to adapt to many kinds of systems.
+\`configure' configures emacs 24.0.90 to adapt to many kinds of systems.
 
 Usage: $0 [OPTION]... [VAR=VALUE]...
 
 
 if test -n "$ac_init_help"; then
   case $ac_init_help in
-     short | recursive ) echo "Configuration of emacs 24.0.50:";;
+     short | recursive ) echo "Configuration of emacs 24.0.90:";;
    esac
   cat <<\_ACEOF
 
 test -n "$ac_init_help" && exit $ac_status
 if $ac_init_version; then
   cat <<\_ACEOF
-emacs configure 24.0.50
+emacs configure 24.0.90
 generated by GNU Autoconf 2.65
 
 Copyright (C) 2009 Free Software Foundation, Inc.
 This file contains any messages produced by compilers while
 running configure, to aid debugging if configure makes a mistake.
 
-It was created by emacs $as_me 24.0.50, which was
+It was created by emacs $as_me 24.0.90, which was
 generated by GNU Autoconf 2.65.  Invocation command line was
 
   $ $0 $@
 
 # Define the identity of the package.
  PACKAGE='emacs'
- VERSION='24.0.50'
+ VERSION='24.0.90'
 
 
 cat >>confdefs.h <<_ACEOF
     LIB_STANDARD=-lc
     START_FILES='pre-crt0.o $(CRT_DIR)/crt0.o'
     ;;
-  netbsd | openbsd )
-    if test -f $CRT_DIR/crti.o; then
-	LIB_STANDARD='-lgcc -lc -lgcc $(CRT_DIR)/crtend.o $(CRT_DIR)/crtn.o'
-        START_FILES='pre-crt0.o $(CRT_DIR)/crt0.o $(CRT_DIR)/crti.o $(CRT_DIR)/crtbegin.o'
-    else
-	LIB_STANDARD='-lgcc -lc -lgcc $(CRT_DIR)/crtend.o'
-	START_FILES='pre-crt0.o $(CRT_DIR)/crt0.o $(CRT_DIR)/crtbegin.o'
-    fi
+    netbsd | openbsd )
+    LIB_STANDARD='-lgcc -lc -lgcc $(CRT_DIR)/crtend.o'
+    START_FILES='pre-crt0.o $(CRT_DIR)/crt0.o $(CRT_DIR)/crtbegin.o'
     ;;
 esac
 
 
 
 
+case $opsys in
+  netbsd | openbsd )
+    if test -f $CRT_DIR/crti.o; then
+
+        test -f $CRT_DIR/crtn.o || \
+          as_fn_error "Required file not found: crtn.o" "$LINENO" 5
+
+        LIB_STANDARD='-lgcc -lc -lgcc $(CRT_DIR)/crtend.o $(CRT_DIR)/crtn.o'
+        START_FILES='pre-crt0.o $(CRT_DIR)/crt0.o $(CRT_DIR)/crti.o $(CRT_DIR)/crtbegin.o'
+    fi
+    ;;
+esac
+
 
 
 
 # report actual input values of CONFIG_FILES etc. instead of their
 # values after options handling.
 ac_log="
-This file was extended by emacs $as_me 24.0.50, which was
+This file was extended by emacs $as_me 24.0.90, which was
 generated by GNU Autoconf 2.65.  Invocation command line was
 
   CONFIG_FILES    = $CONFIG_FILES
 cat >>$CONFIG_STATUS <<_ACEOF || ac_write_fail=1
 ac_cs_config="`$as_echo "$ac_configure_args" | sed 's/^ //; s/[\\""\`\$]/\\\\&/g'`"
 ac_cs_version="\\
-emacs config.status 24.0.50
+emacs config.status 24.0.90
 configured by $0, generated by GNU Autoconf 2.65,
   with options \\"\$ac_cs_config\\"
 

File configure.in

 dnl  along with GNU Emacs.  If not, see <http://www.gnu.org/licenses/>.
 
 AC_PREREQ(2.65)
-AC_INIT(emacs, 24.0.50)
+AC_INIT(emacs, 24.0.90)
 AC_CONFIG_HEADER(src/config.h:src/config.in)
 AC_CONFIG_SRCDIR(src/lisp.h)
 AC_CONFIG_AUX_DIR(build-aux)
 LIB_STANDARD=
 START_FILES=
 
+dnl NB do not use CRT_DIR unquoted here, since it might not be set yet.
 case $opsys in
   cygwin )
     LIB_MATH=
     LIB_STANDARD=-lc
     START_FILES='pre-crt0.o $(CRT_DIR)/crt0.o'
     ;;
+  dnl NB this may be adjusted below.
   netbsd | openbsd )
-    if test -f $CRT_DIR/crti.o; then
-	LIB_STANDARD='-lgcc -lc -lgcc $(CRT_DIR)/crtend.o $(CRT_DIR)/crtn.o'
-        START_FILES='pre-crt0.o $(CRT_DIR)/crt0.o $(CRT_DIR)/crti.o $(CRT_DIR)/crtbegin.o'
-    else
-	LIB_STANDARD='-lgcc -lc -lgcc $(CRT_DIR)/crtend.o'
-	START_FILES='pre-crt0.o $(CRT_DIR)/crt0.o $(CRT_DIR)/crtbegin.o'
-    fi
+    LIB_STANDARD='-lgcc -lc -lgcc $(CRT_DIR)/crtend.o'
+    START_FILES='pre-crt0.o $(CRT_DIR)/crt0.o $(CRT_DIR)/crtbegin.o'
     ;;
 esac
 
 
 AC_SUBST(CRT_DIR)
 
+case $opsys in
+  netbsd | openbsd )
+    if test -f $CRT_DIR/crti.o; then
+
+        test -f $CRT_DIR/crtn.o || \
+          AC_MSG_ERROR([Required file not found: crtn.o])
+
+        LIB_STANDARD='-lgcc -lc -lgcc $(CRT_DIR)/crtend.o $(CRT_DIR)/crtn.o'
+        START_FILES='pre-crt0.o $(CRT_DIR)/crt0.o $(CRT_DIR)/crti.o $(CRT_DIR)/crtbegin.o'
+    fi
+    ;;
+esac
+
 
 dnl This function definition taken from Gnome 2.0
 dnl PKG_CHECK_MODULES(GSTUFF, gtk+-2.0 >= 1.3 glib = 1.3.4, action-if, action-not)
 AC_SUBST(LIBXSM)
 
 ### Use libxml (-lxml2) if available
+HAVE_LIBXML2=no
 if test "${with_xml2}" != "no"; then
   ### I'm not sure what the version number should be, so I just guessed.
   PKG_CHECK_MODULES(LIBXML2, libxml-2.0 > 2.6.17, HAVE_LIBXML2=yes, HAVE_LIBXML2=no)

File doc/emacs/ChangeLog

+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.

File doc/emacs/buffers.texi

 @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
 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.
 
 @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

File doc/emacs/emacs.texi

 * 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

File doc/emacs/emacsver.texi

 @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

File doc/emacs/frames.texi

 
 @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,
 
 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

File doc/emacs/windows.texi

 * 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
 
 
 @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
 
   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
 

File doc/lispref/ChangeLog

+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
+	Windows and Frames in windows.texi.
+	* windows.texi (Windows): Restructure.
+	(Basic Windows): Rewrite.  Explain live and internal windows and
+	normalization functions.
+	(Windows and Frames): Move section here from frames.texi.
+	Describe subwindows, window combinations, window tree, and
+	corresponding functions including window-list here.
+	(Window Sizes): Rename section from Size of Window and move it
+	up in chapter.  Describe total and body sizes and the
+	corresponding functions.  Explain new semantics of
+	window-min-height/-width.
+	(Resizing Windows): Move section up in chapter.  Describe new
+	resize functions.
+	(Splitting Windows): Describe new behavior of split-window,
+	split-window-above-each-other and split-window-side-by-side.
+	Provide examples.  Describe window-nest and window-splits
+	options.
+	(Deleting Windows): Minor rewrite.
+	(Selecting Windows): Minor rewrite.  Describe
+	frame-selected-window and set-frame-selected-window here.
+	(Cyclic Window Ordering): Minor rewrite.  Describe
+	window-list-1.
+	(Buffers and Windows): Rewrite.  Explain a window's previous and
+	next buffers and the corresponding functions.
+	(Window Tree): Merge into Windows and Frames section.
+	* elisp.texi (Top): Update node listings for frames and windows
+	sections.
+
+2011-09-21  Stefan Monnier  <monnier@iro.umontreal.ca>
+
+	* display.texi (Face Functions): `face-list' returns faces (bug#9564).
+
 2011-09-19  Lars Magne Ingebrigtsen  <larsi@gnus.org>
 
 	* errors.texi (Standard Errors): Remove apparent placeholder text

File doc/lispref/buffers.texi

 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
 @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
 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

File doc/lispref/display.texi

 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
 @end defun
 
 @defun face-list
-This function returns a list of all defined face names.
+This function returns a list of all defined faces.
 @end defun
 
 @defun copy-face old-face new-name &optional frame new-frame

File doc/lispref/elisp.texi

 @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
 Windows
 
 * Basic Windows::           Basic information on using windows.
+* Windows and Frames::      Relating windows to the frame they appear on.
+* Window Sizes::            Accessing a window's size.
+* Resizing Windows::        Changing the sizes of windows.
 * Splitting Windows::       Splitting one window into two windows.
 * Deleting Windows::        Deleting a window gives its space to other 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.
+* 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.
 * Textual Scrolling::       Moving text up and down through the window.
 * Vertical Scrolling::      Moving the contents up and down on the window.
 * Horizontal Scrolling::    Moving the contents sideways on the window.
-* Size of Window::          Accessing the size of a window.
-* Resizing Windows::        Changing the size of a window.
 * Coordinates and Windows:: Converting coordinates to windows.
-* Window Tree::             The layout and sizes of all windows in a frame.
 * Window Configurations::   Saving and restoring the state of the screen.
 * Window Parameters::       Associating additional information with windows.
 * Window Hooks::            Hooks for scrolling, window size changes,
 * Frame Titles::            Automatic updating of frame titles.
 * Deleting Frames::         Frames last until explicitly deleted.
 * Finding All Frames::      How to examine all existing frames.
-* Frames and Windows::      A frame contains windows;
-                              display of text always works through windows.
 * Minibuffers and Frames::  How a frame finds the minibuffer to use.
 * Input Focus::             Specifying the selected frame.
 * Visibility of Frames::    Frames may be visible or invisible, or icons.

File doc/lispref/files.texi

 @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
 
 @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}.

File doc/lispref/frames.texi

 * Frame Titles::                Automatic updating of frame titles.
 * Deleting Frames::             Frames last until explicitly deleted.
 * Finding All Frames::          How to examine all existing frames.
-* Frames and Windows::          A frame contains windows;
-                                  display of text always works through windows.
 * Minibuffers and Frames::      How a frame finds the minibuffer to use.
 * Input Focus::                 Specifying the selected frame.
 * Visibility of Frames::        Frames may be visible or invisible, or icons.
   See also @code{next-window} and @code{previous-window}, in @ref{Cyclic
 Window Ordering}.
 
-@node Frames and Windows
-@section Frames and Windows
-
-  Each window is part of one and only one frame; you can get that frame
-with @code{window-frame}.
-
-@defun window-frame window
-This function returns the frame that @var{window} is on.
-@end defun
-
-  All the non-minibuffer windows in a frame are arranged in a cyclic
-order.  The order runs from the frame's top window, which is at the
-upper left corner, down and to the right, until it reaches the window at
-the lower right corner (always the minibuffer window, if the frame has
-one), and then it moves back to the top.  @xref{Cyclic Window Ordering}.
-
-@defun frame-first-window &optional frame
-This returns the topmost, leftmost window of frame @var{frame}.
-If omitted or @code{nil}, @var{frame} defaults to the selected frame.
-@end defun
-
-At any time, exactly one window on any frame is @dfn{selected within the
-frame}.  The significance of this designation is that selecting the
-frame also selects this window.  Conversely, selecting a window for
-Emacs with @code{select-window} also makes that window selected within
-its frame.  @xref{Selecting Windows}.
-
-@defun frame-selected-window  &optional frame
-This function returns the window on @var{frame} that is selected
-within @var{frame}.  If omitted or @code{nil}, @var{frame} defaults to
-the selected frame.
-@end defun
-
-@defun set-frame-selected-window frame window &optional norecord
-This sets the selected window of frame @var{frame} to @var{window}.
-If @var{frame} is @code{nil}, it operates on the selected frame.  If
-@var{frame} is the selected frame, this makes @var{window} the
-selected window.  This function returns @var{window}.
-
-Optional argument @var{norecord} non-@code{nil} means to neither change
-the order of recently selected windows nor the buffer list (@pxref{The
-Buffer List}).
-@end defun
-
-  Another function that (usually) returns one of the windows in a given
-frame is @code{minibuffer-window}.  @xref{Definition of minibuffer-window}.
-
 @node Minibuffers and Frames
 @section Minibuffers and Frames
 

File doc/lispref/vol1.texi

 * 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.

File doc/lispref/vol2.texi

 * 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.

File doc/lispref/windows.texi

 @node Windows, Frames, Buffers, Top
 @chapter Windows
 
-  This chapter describes most of the functions and variables related to
-Emacs windows.  @xref{Frames and Windows}, for how windows relate to
-frames.  @xref{Display}, for information on how text is displayed in
-windows.
+This chapter describes the functions and variables related to Emacs
+windows.  @xref{Frames}, for how windows are assigned an area of screen
+available for Emacs to use.  @xref{Display}, for information on how text
+is displayed in windows.
 
 @menu
 * Basic Windows::           Basic information on using windows.
+* Windows and Frames::      Relating windows to the frame they appear on.
+* Window Sizes::            Accessing a window's size.
+* Resizing Windows::        Changing the sizes of windows.
 * Splitting Windows::       Splitting one window into two windows.
 * Deleting Windows::        Deleting a window gives its space to other 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.
 * Textual Scrolling::       Moving text up and down through the window.
 * Vertical Scrolling::      Moving the contents up and down on the window.
 * Horizontal Scrolling::    Moving the contents sideways on the window.
-* Size of Window::          Accessing the size of a window.
-* Resizing Windows::        Changing the size of a window.
 * Coordinates and Windows:: Converting coordinates to windows.
-* Window Tree::             The layout and sizes of all windows in a frame.
 * Window Configurations::   Saving and restoring the state of the screen.
 * Window Parameters::       Associating additional information with windows.
 * Window Hooks::            Hooks for scrolling, window size changes,
                               or window configuration changes.
 @end menu
 
+
 @node Basic Windows
 @section Basic Concepts of Emacs Windows
 @cindex window
-@cindex selected window
-
-  A @dfn{window} in Emacs is the physical area of the screen in which a
-buffer is displayed.  The term is also used to refer to a Lisp object that
-represents that screen area in Emacs Lisp.  It should be
-clear from the context which is meant.
-
-  Emacs groups windows into frames; see @ref{Frames}.  A frame
-represents an area of screen available for Emacs to use.  Each frame
-always contains at least one window, but you can subdivide it
-vertically or horizontally into multiple, nonoverlapping Emacs
-windows.
-
-  In each frame, at any time, one and only one window is designated as
-@dfn{selected within the frame}.  The frame's cursor appears in that
-window, but the other windows have ``non-selected'' cursors, normally
-less visible.  (@xref{Cursor Parameters}, for customizing this.)  At
-any time, one frame is the selected frame; and the window selected
-within that frame is @dfn{the selected window}.  The selected window's
-buffer is usually the current buffer (except when @code{set-buffer} has
-been used); see @ref{Current Buffer}.
-
-  For practical purposes, a window exists only while it is displayed in
-a frame.  Once removed from the frame, the window is effectively deleted
-and should not be used, @emph{even though there may still be references
-to it} from other Lisp objects; see @ref{Deleting Windows}.  Restoring a
-saved window configuration is the only way for a window no longer on the
-screen to come back to life; see @ref{Window Configurations}.
+
+A @dfn{window} in Emacs is the physical area of the screen in which a
+buffer is displayed, see @ref{Buffers}.  The term is also used to refer
+to a Lisp object that represents that screen area in Emacs Lisp.  It
+should be clear from the context which is meant.
 
 @cindex multiple windows
-  Users create multiple windows so they can look at several buffers at
-once.  Lisp libraries use multiple windows for a variety of reasons, but
-most often to display related information.  In Rmail, for example, you
-can move through a summary buffer in one window while the other window
-shows messages one at a time as they are reached.
-
+  Emacs groups windows into frames; see @ref{Frames}.  Each frame always
+contains at least one window, but you can subdivide it into multiple,
+non-overlapping Emacs windows.  Users create multiple windows so they
+can look at several buffers at once.  Lisp libraries use multiple
+windows for a variety of reasons, but most often to display related
+information.  In Rmail, for example, you can move through a summary
+buffer in one window while the other window shows messages one at a time
+as they are reached.
+
+@cindex terminal screen
+@cindex screen of terminal
   The meaning of ``window'' in Emacs is similar to what it means in the
 context of general-purpose window systems such as X, but not identical.
 The X Window System places X windows on the screen; Emacs uses one or
-more X windows as frames, and subdivides them into
-Emacs windows.  When you use Emacs on a character-only terminal, Emacs
-treats the whole terminal screen as one frame.
-
-@cindex terminal screen
-@cindex screen of terminal
+more X windows as frames, and subdivides them into Emacs windows.  When
+you use Emacs on a character-only terminal, Emacs treats the whole
+terminal screen as one frame.
+
 @cindex tiled windows
   Most window systems support arbitrarily located overlapping windows.
 In contrast, Emacs windows are @dfn{tiled}; they never overlap, and
 them (@pxref{Resizing Windows}), not all conceivable tilings of windows
 on an Emacs frame are actually possible.
 
+  For practical purposes, a window exists only while it is displayed in
+a frame.  Once removed from the frame, the window is effectively deleted
+and should not be used, even though the Lisp object representing it
+might be still referenced from other Lisp objects; see @ref{Deleting
+Windows}.  Restoring a saved window configuration is the only way for a
+window no longer on the screen to come back to life; see @ref{Window
+Configurations}.
+
 @defun windowp object
-This function returns @code{t} if @var{object} is a window.
+This function returns @code{t} if @var{object} is a window, @code{nil}
+otherwise.  It can return @code{t} if @var{object} denotes a window that
+has been deleted.
 @end defun
 
+@cindex live windows
+@cindex internal windows
+   For historical reasons a window is considered @dfn{live} if and only
+if it currently displays a buffer; see @ref{Buffers and Windows}.  In
+order to show multiple windows within one and the same frame, Emacs
+organizes them in form of a tree called window tree; see @ref{Windows
+and Frames}.  The internal nodes of a window tree are called internal
+windows and are not considered live.  The leaf nodes of a window tree
+constitute the windows displaying buffers and only they will be called
+live here.
+
+@defun window-live-p object
+This function returns @code{t} if @var{object} is a live window and
+@code{nil} otherwise.  A live window is a window that displays a buffer.
+@end defun
+
+@defun window-any-p object
+This function returns @code{t} if @var{object} denotes a live or an
+internal window and @code{nil} otherwise.  In particular, this function
+returns @code{nil} if @var{object} is a window that has been
+deleted.
+@end defun
+
+@cindex selected window
+In each frame, at any time, one and only one window is designated as
+@dfn{selected within the frame}.  Also, at any time, one frame is the
+selected frame (@pxref{Input Focus}).  The window selected within the
+selected frame is the @dfn{selected window}.
+
+   The selected window is always a live window.  Its buffer is usually
+the current buffer (except when @code{set-buffer} has been used); see
+@ref{Current Buffer}.
+
+@defun selected-window
+This function returns the selected window.  This is the window in which
+the cursor for selected windows (@pxref{Cursor Parameters}) appears and
+to which many commands apply.
+@end defun
+
+The window handling functions can be roughly grouped into functions
+operating on live windows only and functions that accept any window as
+argument.  Many of these functions accept as argument the value
+@code{nil} to specify the selected window.  The two functions below can
+be used to ``normalize'' arguments specifying windows in a uniform
+manner.
+
+@defun window-normalize-any-window window
+This function returns the normalized value for @var{window} which can be
+any window that has not been deleted.  More precisely, if @var{window}
+is @code{nil}, it returns the selected window.  If @var{window} denotes
+a live or internal window, it returns that window.  Otherwise, this
+function signals an error.
+@end defun
+
+@defun window-normalize-live-window window
+This functions returns the normalized value for a live window
+@var{window}.  More precisely, if @var{window} is @code{nil}, it returns
+the selected window.  If @var{window} is a live window, it returns that
+window.  Otherwise, this function signals an error.
+@end defun
+
+
+@node Windows and Frames
+@section Windows and Frames
+
+Each window is part of one and only one frame (@pxref{Frames}); you can
+get that frame with the function described next.
+
+@defun window-frame window
+This function returns the frame that @var{window} is on.  The argument
+@var{window} can be any window and defaults to the selected one.
+@end defun
+
+The following function returns a list of all live windows on a specific
+frame.
+
+@defun window-list &optional frame minibuf window
+This function returns a list of @var{frame}'s live windows, starting
+with @var{window}.  The optional argument @var{frame} has to denote a
+live frame and defaults to the selected frame.  The optional argument
+@var{window} has to denote a live window on the frame specified by
+@var{frame} and defaults to the selected one.
+
+The argument @var{minibuf} specifies if the minibuffer window shall be
+included in the return value.  If @var{minibuf} is @code{t}, the result
+always includes the minibuffer window.  If @var{minibuf} is @code{nil}
+or omitted, that includes the minibuffer window only if it is active.
+If @var{minibuf} is neither @code{nil} nor @code{t}, the result never
+includes the minibuffer window.
+@end defun
+
+@cindex window tree
+Windows within one and the same frame are organized in form of a tree
+called @dfn{window tree}.  The leaf nodes of a window tree constitute
+the windows visible to the user.  These are the windows associated with
+buffers and are usually called live windows.  The internal nodes of a
+window tree are needed for finding, traversing and displaying the live
+windows.
+
+   A minibuffer window (@pxref{Minibuffer Windows}) is not considered
+part of its frame's window tree unless the frame is a minibuffer-only
+frame.  Most functions covered in this section accept, however, the
+minibuffer window as argument.  Also, the minibuffer window is listed by
+the function @code{window-tree} described at the end of this section.
+
+   A window tree is rooted at the root window of its frame.
+
+@defun frame-root-window &optional frame-or-window
+This function returns the root window of @var{frame-or-window}.  The
+argument @var{frame-or-window} has to denote either a window or a frame
+and defaults to the selected frame.  If @var{frame-or-window} denotes a
+window, the return value is the root window of that window's frame.
+This function always returns a window; a live window if the frame
+specified by @var{frame-or-window} contains no other live windows and an
+internal window otherwise.
+@end defun
+
+@cindex subwindow
+All other windows of a frame with the exception of the minibuffer window
+are subwindows of the frame's root window.  A window is considered a
+@dfn{subwindow} of another window if it occupies a part of that other
+window's screen area.
+
+The functions described next allow to access the members of a window
+tree and take an arbitrary window as argument.
+
+@cindex parent window
+@defun window-parent &optional window
+Return @var{window}'s parent in the window tree.  The optional argument
+@var{window} can denote an arbitrary window and defaults to the selected
+one.  The return value is @code{nil} if @var{window} is a minibuffer
+window or the root window of its frame and an internal window otherwise.
+@end defun
+
+@cindex child window
+   Parent windows do not appear on the screen.  The screen area of a
+parent window is the rectangular part of the window's frame occupied by
+the window's @dfn{child windows}, that is, the set of windows having
+that window as their parent.  Each parent window has at least two child
+windows, so there are no ``Matryoshka'' windows.  Minibuffer windows do
+not have child windows.
+
+@cindex window combination
+@cindex vertical combination
+@cindex horizontal combination
+The children of any parent window form either a vertical or a horizontal
+combination of windows.  A @dfn{vertical combination} is a set of
+windows arranged one above each other.  A @dfn{horizontal combination}
+is a set of windows arranged side by side.  Consider the frame shown
+below (for simplicity we assume that the frame does not contain a
+minibuffer window):
+
+@smallexample
+@group
+     ______________________________________
+    | ______  ____________________________ |
+    ||      || __________________________ ||
+    ||      ||| ___________  ___________ |||
+    ||      ||||           ||           ||||
+    ||      ||||           ||           ||||
+    ||      ||||_____W6____||_____W7____||||
+    ||      |||____________W4____________|||
+    ||      || __________________________ ||
+    ||      |||                          |||
+    ||      |||____________W5____________|||
+    ||__W2__||_____________W3_____________ |
+    |__________________W1__________________|
+
+@end group
+@end smallexample
+
+The root window of the frame is @code{W1}---a horizontal combination of
+the live window @code{W2} and the internal window @code{W3}.  Hence
+@code{(window-parent W1)} is @code{nil} while @code{(window-parent W2)}
+and @code{(window-parent W3)} are both @code{W1}.
+
+   The internal window @code{W3} is a vertical combination of @code{W4}
+and the live window @code{W5}.  The internal window @code{W4} is a
+horizontal combination of the live windows @code{W6} and @code{W7}.  The
+windows you can actually see on the screen are @code{W2}, @code{W5},
+@code{W6} and @code{W7}.
+
+   For any parent window, the first child window can be retrieved by the
+functions given next.
+
+@defun window-top-child &optional window
+This function returns @var{window}'s first vertical child window.  The
+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 horizontal combination.  In the
+example above @code{(window-top-child W3)} is @code{W4} while
+@code{(window-top-child W4)} is @code{nil}.
+@end defun
+
+@defun window-left-child &optional window
+This function returns @var{window}'s first horizontal child window.  The
+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-left-child W3)} is @code{nil}.
+@end defun
+
+@defun window-child window
+This function return @var{window}'s first child window.  The return
+value is @code{nil} if @var{window} is a live window.  In the example
+above @code{(window-child W3)} is @code{W4} while @code{(window-child
+W4)} is @code{W6}.
+@end defun
+
+The following function is useful to determine whether a window is part
+of a vertical or horizontal combination.
+
+@defun window-iso-combined-p &optional window horizontal
+This function returns non-@code{nil} if and only if @var{window} is
+vertically combined.  The argument @var{window} can specify any window
+and defaults to the selected one.  The actual return value is the first
+vertical child of window.
+
+If the optional argument @var{horizontal} is non-@code{nil}, this means
+to return non-@code{nil} if and only if @var{window} is horizontally
+combined.  In this case, the return value is the first horizontal child
+of window.
+@end defun
+
+@cindex sibling window
+For any window that is part of a combination, the other windows in that
+combination are called the window's @dfn{siblings}.  The only windows
+that do not have siblings are root windows of frames and minibuffer
+windows.  A window's siblings can be retrieved with the following two
+functions.
+
+@defun window-next-sibling &optional window
+This function returns @var{window}'s next sibling.  The optional
+argument @var{window} can be an arbitrary window and defaults to the
+selected window.  It returns @code{nil} if @var{window} is the last
+child of its parent.  In our example @code{(window-next-sibling W2)} is
+@code{W3} while @code{(window-next-sibling W3)} is @code{nil}.
+@end defun
+
+@defun window-prev-sibling &optional window
+This function returns @var{window}'s previous sibling.  The optional
+argument @var{window} can be an arbitrary window and defaults to the
+selected window.  It returns @code{nil} if @var{window} is the first
+child of its parent. In our example @code{(window-prev-sibling W3)} is
+@code{W2} and @code{(window-prev-sibling W2)} is @code{nil}.
+@end defun
+
+The functions @code{window-next-sibling} and @code{window-prev-sibling}
+should not be confused with the functions @code{next-window} and
+@code{previous-window} which respectively return the next and previous
+window in the cyclic ordering of windows, see @ref{Cyclic Window
+Ordering}.
+
+   In order to find the first live window on a frame, the following
+function can be used.
+
+@defun frame-first-window &optional frame-or-window
+This function returns the live window at the upper left corner of the
+frame specified by @var{frame-or-window}.  The argument
+@var{frame-or-window} must denote a window or a live frame and defaults
+to the selected frame.  If @var{frame-or-window} specifies a window,
+this function returns the first window on that window's frame.  Under
+the assumption that the frame from our canonical example is selected
+@code{(frame-first-window)} returns @code{W2}.
+@end defun
+
+You can get the window tree of a frame with the following function.
+
+@cindex window tree
+@defun window-tree &optional frame
+This function returns the window tree for frame @var{frame}.  The
+optional argument @var{frame} must be a live frame and defaults to the
+selected one.
+
+The return value is a list of the form @code{(@var{root} @var{mini})},
+where @var{root} represents the window tree of the frame's
+root window, and @var{mini} is the frame's minibuffer window.
+
+If the root window is live, @var{root} specifies the root window and
+nothing else.  Otherwise, @var{root} is a list @code{(@var{dir}
+@var{edges} @var{w1} @var{w2} ...)} where @var{dir} is @code{nil} for a
+horizontal combination, and @code{t} for a vertical combination,
+@var{edges} gives the size and position of the combination, and the
+remaining elements are the child windows.  Each child window may again
+be a live window or a list representing a window combination, and so on.
+The @var{edges} element is a list @code{(@var{left}@var{ top}@var{
+right}@var{ bottom})} similar to the value returned by
+@code{window-edges}, see @ref{Coordinates and Windows}.
+@end defun
+
+
+@node Window Sizes
+@section Window Sizes
+@cindex window size
+@cindex size of window
+
+Emacs windows are rectangular.  The structure of a live window can be
+roughly sketched as follows:
+
+@smallexample
+@group
+         _________________________________________ 
+      ^ |______________ Header Line_______________| 
+      | |LS|LF|LM|                       |RM|RF|RS| ^
+      | |  |  |  |                       |  |  |  | |
+ Window |  |  |  |       Text Area       |  |  |  | Window
+ Total  |  |  |  |     (Window Body)     |  |  |  | Body
+ Height |  |  |  |                       |  |  |  | Height
+      | |  |  |  |<- Window Body Width ->|  |  |  | |
+      | |__|__|__|_______________________|__|__|__| v
+      v |_______________ Mode Line _______________|
+
+         <----------- Window Total Width -------->
+
+@end group
+@end smallexample
+
+@cindex window body
+@cindex body of a window
+The text area constitutes the body of the window.  In its most simple
+form, a window consists of its body alone.  LS and RS stand for the left
+and right scroll bar (@pxref{Scroll Bars}) respectively.  Only one of
+them can be present at any time.  LF and RF denote the left and right
+fringe, see @ref{Fringes}.  LM and RM, finally, stand for the left and
+right display margin, see @ref{Display Margins}.  The header line, if
+present, is located above theses areas, the mode line below, see
+@ref{Mode Line Format}.
+
+@cindex window height
+@cindex total window height
+@cindex height of a window
+@cindex total height of a window
+The @dfn{total height of a window} is specified as the total number of
+lines occupied by the window.  Any mode or header line is included in a
+window's total height.  For an internal window, the total height is
+calculated recursively from the total heights of its child windows.
+
+@cindex window width
+@cindex total window width
+@cindex width of a window
+@cindex total width of a window
+The @dfn{total width of a window} denotes the total number of columns of
+the window.  Any scroll bar and the column of @samp{|} characters that
+separate the window from its right sibling are included in a window's
+total width.  On a window-system, fringes and display margins are
+included in a window's total width too.  For an internal window, the
+total width is calculated recursively from the total widths of its child
+windows.
+
+@cindex total size of a window
+@cindex total window size
+The following function is the standard interface for getting the total
+size of any window:
+
+@defun window-total-size &optional window &optional horizontal
+This function returns the total number of lines of @var{window}.  The
+argument @var{window} can denote any window and defaults to the selected
+one.  If @var{window} is live, the return value includes any header or
+mode lines of @var{window}.  If @var{window} is internal, the return
+value is the sum of the total heights of @var{window}'s child windows
+provided these are vertically combined and the height of @var{window}'s
+first child if they are horizontally combined.
+
+   If the optional argument @var{horizontal} is non-@code{nil}, this
+function returns the total number of columns of @var{window}.  If
+@var{window} is live, the return value includes any vertical divider
+column or scroll bars of @var{window}.  On a window-system, the return
+value includes the space occupied by any margins and fringes of
+@var{window} too.  If @var{window} is internal, the return value is the
+sum of the total widths of @var{window}'s child windows provided these
+are horizontally combined and the width of @var{window}'s first child
+otherwise.
+@end defun
+
+Alternatively, the following two functions can be used to retrieve
+either the total height or the total width of a window:
+
+@defun window-total-height &optional window
+This function returns the total number of lines of @var{window}.
+@var{window} can be any window and defaults to the selected one.  The
+return value includes @var{window}'s mode line and header line, if any.
+If @var{window} is internal the return value is the sum of heights of
+@var{window}'s child windows for a vertical combination and the height
+of @var{window}'s first child otherwise.
+@end defun
+
+@defun window-total-width &optional window
+This function returns the total number of columns of @var{window}.
+@var{window} can be any window and defaults to the selected one.  The
+return value includes any vertical dividers or scrollbars of
+@var{window}.  On a window-system the return value also includes the
+space occupied by any margins and fringes of @var{window}.  If
+@var{window} is internal, the return value is the sum of the widths of
+@var{window}'s child windows for a horizontal combination and the width
+of @var{window}'s first child otherwise.
+@end defun
+
+The total height of any window is usually less than the height of the
+window's frame, because the latter may also include the minibuffer
+window.  Depending on the toolkit in use, the frame height can also
+include the menu bar and the tool bar (@pxref{Size and Position}).
+Therefore, in general it is not straightforward to compare window and
+frame heights.  The following function is useful to determine whether
+there are no other windows above or below a specified window.
+
+@cindex full-height window
+@defun window-full-height-p &optional window
+This function returns non-@code{nil} if there is no other window above
+or below @var{window} on the containing frame.  More precisely, this
+function returns @code{t} if and only if the total height of
+@var{window} equals the total height of the root window (@pxref{Windows
+and Frames}) of @var{window}'s frame.  The @var{window} argument may
+denote any window and defaults to the selected one.
+@end defun
+
+@cindex full-width window
+The following function can be used to determine whether there are no
+other windows on the left or right of a specified window.
+
+@defun window-full-width-p &optional window
+This function returns non-@code{nil} if there are no other windows on
+the left or right of @var{window}; @code{nil} otherwise.  More
+precisely, this function returns @code{t} if and only if the total width
+of @var{window} equals the total width of the root window
+(@pxref{Windows and Frames}) of @var{window}'s frame.  The @var{window}
+argument may denote any window and defaults to the selected one.
+@end defun
+
+@cindex top line of window
+@cindex left column of window
+  The windows of a frame are unambiguously characterized by the
+combination of their top line and left column within that frame.
+
+@defun window-top-line &optional window
+This function returns the top line of @var{window}.  The argument
+@var{window} can denote any window and defaults to the selected one.
+@end defun
+
+@defun window-left-column &optional window
+This function returns the left column of @var{window}.  The argument
+@var{window} can denote any window and defaults to the selected one.
+@end defun
+
+For a frame displaying one window only, that window's top line and left
+column are both zero.  When a frame displays a window @var{WB} below a
+window @var{WA}, the top line of @var{WB} can be calculated by adding
+the total height of @var{WA} to the top line of @var{WA}.  When a frame
+displays a window @var{WR} on the right of a window @var{WL}, the left
+column of @var{WR} can be calculated by adding the total width of
+@var{WL} to the left column of @var{WL}.
+
+@cindex window body height
+@cindex body height of a window
+The @dfn{body height of a window} is specified as the total number of
+lines occupied by the window's text area.  Mode or header lines are not
+included in a window's body height.
+
+@cindex window body width
+@cindex body width of a window
+The @dfn{body width of a window} denotes the total number of columns
+occupied by the window's text area.  Scroll bars or columns of @samp{|}
+characters that separate side-by-side windows are not included in a
+window's body width.
+
+@cindex body size of a window
+@cindex window body size
+The following functions retrieve height and width of the body of a live
+window:
+
+@defun window-body-size &optional window horizontal
+This function returns the number of lines of @var{window}'s text area.
+@var{window} must be a live window and defaults to the selected one.
+The return value does not count any mode or header line of @var{window}.
+
+Optional argument @var{horizontal} non-@code{nil} means to return the
+number of columns of @var{window}'s text area.  In this case the return
+value does not include any vertical divider or scroll bar owned by
+@var{window}.  On a window-system the return value does not include the
+number of columns used for @var{window}'s fringes or display margins
+either.
+@end defun
+
+@defun window-body-height &optional window
+This function returns the number of lines of @var{window}'s body.
+@var{window} must be a live window and defaults to the selected one.
+
+The return value does not include @var{window}'s mode line and header
+line, if any.  If a line at the bottom of the window is only partially
+visible, that line is included in the return value.  If you do not
+want to include a partially visible bottom line in the return value,
+use @code{window-text-height} instead.
+@end defun
+
+@defun window-body-width &optional window
+This function returns the number of columns of @var{window}'s body.
+@var{window} must be a live window and defaults to the selected one.
+
+The return value does not include any vertical dividers or scroll bars
+owned by @var{window}.  On a window-system the return value does not
+include the number of columns used for @var{window}'s fringes or
+display margins either.
+@end defun
+
+The following functions have been used in earlier versions of Emacs.
+They are still supported but due to the confusing nomenclature they
+should not be used any more in future code.
+
+@defun window-height &optional window
+This function is an alias for `window-total-height', see above.
+@end defun
+
+@defun window-width &optional window
+This function is an alias for `window-body-width', see above.
+@end defun
+
+@cindex minimum window size
+  The following two options constrain the sizes of windows to a minimum
+height and width.  Their values are honored when windows are split
+(@pxref{Splitting Windows}) or resized (@pxref{Resizing Windows}).  Any
+request to make a window smaller than specified here will usually result
+in an error.
+
+@defopt window-min-height
+The value of this variable specifies how short a window may be.  The
+value is measured in line units and has to account for any header or
+mode line.  The default value for this option is @code{4}.  Values less
+than @code{1} are ignored.
+@end defopt
+
+@defopt window-min-width
+The value of this variable specifies how narrow a window may be.  The
+value is measured in characters and includes any margins, fringes,
+scroll bar and vertical divider column.  The default value for this
+option is @code{10}.  A value less than @code{2} is ignored.
+@end defopt
+
+Applications should not rebind these variables.  To shrink a specific
+window to a height or width less than the one specified here, they
+should rather invoke @code{window-resize} (@pxref{Resizing Windows})
+with a non-@code{nil} @var{ignore} argument.  The function
+@code{split-window} (@pxref{Splitting Windows}) can make a window
+smaller than specified here by calling it with a non-@code{nil}
+@var{size} argument.  Interactively, the values specified here cannot be
+overridden.
+
+   Earlier versions of Emacs could delete a window when its size dropped
+below @code{window-min-height} or @code{window-min-width}.  As a rule,
+the current version of Emacs does no more delete windows by side-effect.
+The only exception to this rule are requests to resize a frame which may
+implicitly delete windows when they do not fit on the frame any more,
+see @ref{Size and Position}.
+
+   The size of a window can be fixed which means that it cannot be split
+(@pxref{Splitting Windows}) or resized (@pxref{Resizing Windows}).
+
+@cindex fixed-size window
+@defvar window-size-fixed
+If this variable is non-@code{nil}, in a given buffer, then the size of
+any window displaying that buffer remains fixed unless you either
+explicitly change it or Emacs has no other choice.
+
+If the value is @code{height}, then only the window's height is fixed;
+if the value is @code{width}, then only the window's width is fixed.
+Any other non-@code{nil} value fixes both the width and the height.
+
+This variable automatically becomes buffer-local when set.
+@end defvar
+
+Commands supposed to explicitly change the size of windows such as
+@code{enlarge-window} (@pxref{Resizing Windows}) get an error if they
+had to change a window size which is fixed.  Other functions like
+@code{window-resize} (@pxref{Resizing Windows}) have an optional
+@var{ignore} argument which allows to change the size of fixed-size
+windows.
+
+   Deleting a window or changing a frame's size may change the size of a
+fixed-size window, if there is no other alternative.
+
+   The height of a vertical combination of windows cannot be changed
+when the height of all these windows is fixed.  Its width cannot be
+changed if the width of at least one of these windows is fixed.
+Similarly, the width of a horizontal combination of windows cannot be
+changed when the width of all these windows is fixed.  Its height cannot
+be changed if the height of at least one of these windows is fixed.
+
+   The next function allows to check whether the size of an arbitrary           
+window is fixed.
+
+@defun window-size-fixed-p &optional window horizontal
+This function returns non-@code{nil} if @var{window}'s height is fixed.
+The argument @var{window} can be an arbitrary window and defaults to the
+selected one.  Optional argument @var{horizontal} non-@code{nil} means
+return non-@code{nil} if @var{window}'s width is fixed.
+
+If this function returns @code{nil}, this does not necessarily mean that
+@var{window} can be resized in the desired direction.  The function
+@code{window-resizable} (@pxref{Resizing Windows}) can tell that.
+@end defun
+
+
+@node Resizing Windows
+@section Resizing Windows
+@cindex window resizing
+@cindex resize window
+@cindex changing window size
+@cindex window size, changing
+
+Emacs does not permit overlapping windows or gaps between windows, so
+changing the size of a window always affects at least one other window.
+When a frame contains just one window, that window can be resized only
+by resizing the window's frame.  The functions described below are
+therefore meaningful only in the context of a frame containing at least
+two windows.  The size of the corresponding frame never changes when
+invoking a function described in this section.
+
+   The routines changing window sizes always operate in one dimension at
+a time.  This means that windows can be resized only either vertically
+or horizontally.  If a window shall be resized in both dimensions, it
+must be resized in one dimension first and in the other dimension
+afterwards.  If the second resize operation fails, the frame might end
+up in an unsatisfactory state.  To avoid such states, it might be useful
+to save the current window configuration (@pxref{Window Configurations})
+before attempting the first resize operation and restore the saved
+configuration in case the second resize operation fails.
+
+   Functions that resize windows are supposed to obey restrictions
+imposed by window minimum sizes and fixed-size windows, see @ref{Window
+Sizes}.  In order to determine whether resizing a specific window is
+possible in the first place, the following function can be used:
+
+@defun window-resizable window delta &optional horizontal ignore side noup nodown
+This function returns @var{delta} if the size of @var{window} can be
+changed vertically by @var{delta} lines.  Optional argument
+@var{horizontal} non-@code{nil} means to return @var{delta} if
+@var{window} can be resized horizontally by @var{delta} columns.  A
+return value of zero means that @var{window} is not resizable.
+
+If @var{delta} is a positive number, this means that @var{window} shall
+be enlarged by @var{delta} lines or columns.  If @var{window} cannot be
+enlarged by @var{delta} lines or columns, this function returns the
+maximum value in the range from 0 to @var{delta} by which @var{window}
+can be enlarged.
+
+If @var{delta} is a negative number, this means that @var{window} shall
+be shrunk by -@var{delta} lines or columns.  If @var{window} cannot be
+shrunk by -@var{delta} lines or columns, this function returns the
+minimum value in the range from @var{delta} to 0 that can be used for
+shrinking @var{window}.
+
+Optional argument @var{ignore} non-@code{nil} means ignore any
+restrictions imposed by the variables @code{window-min-height} or
+@code{window-min-width} and @code{window-size-fixed}.  In this case the
+minimum height of a window is specified as the minimum number of lines
+that allow viewing any header or mode line and at least one line of the
+text area of window.  The minimum width of a window includes any
+fringes, margins and the scroll bar as well as two text columns.
+
+If @var{ignore} denotes a window, this means to ignore restrictions for
+that window only.  If @var{ignore} equals the constant @code{safe}, this
+means a live window may get as small as one line or two columns.
+
+Optional argument @var{noup} non-@code{nil} means don't go up in the
+window tree but try to steal or distribute the space needed for the
+resize operation among the other windows within @var{window}'s
+combination.  Optional argument @var{nodown} non-@code{nil} means don't
+check whether @var{window} itself and its subwindows can be resized.
+@end defun
+
+The function @code{window-resizable} does not change any window sizes.
+The following function does:
+
+@defun window-resize window delta &optional horizontal ignore
+This function resizes @var{window} vertically by @var{delta} lines.  The
+argument @var{window} can denote an arbitrary window and defaults to the
+selected one.  An attempt to resize the root window of a frame will
+raise an error.
+