⟦827afc557⟧

TextFile

@setfilename ../info/buffers
@node Buffers, Windows, Backups and Auto Saving, Top
@chapter Buffers

  A @dfn{buffer} is a Lisp object containing characters.  Buffers are used
to hold the contents of files when they are visited, but buffers need
not have an associated file.  While several buffers may exist at one
time, exactly one buffer is designated the @dfn{current buffer}.  Most
editing commands act on the contents of the current buffer.  Each
buffer, including the current buffer, may or may not be displayed in a
window.
@cindex buffer display

@menu
* Buffer Basics::       
* Buffer Names::        
* Buffer File Name::    
* Buffer Contents::     
* Buffer Modification:: 
* Modification Time::   
* Read Only Buffers::   
* The Buffer List::     
* Creating Buffers::    
* Killing Buffers::     
* Changing Buffers::    
@end menu

@node Buffer Basics, Buffer Names, Buffers, Buffers
@comment  node-name,  next,  previous,  up
@section Buffer Basics

  The contents of a buffer may be viewed as an extendable
string; insertions and deletions may occur in any part of the buffer.

  A Lisp buffer object has information about one specific buffer.  Some
of this information is directly accessible to the programmer through
variables; other information is only accessible through functions that
modify it or return it.  (For example, the width of a tab character is
directly accessible through a variable, while the value of point is
accessible only through a primitive function.)

  Buffer-specific information that is directly accessible is stored in
@dfn{buffer-local} variables.  These buffer-local bindings exactly
parallel the global value cell of a symbol, if any, but they are
``seen'' by the evaluator before the actual global value cell.  This
means you can set buffer-local variables, such as
@code{fill-column} or @code{comment-column}, to different values for
each buffer.  For more information about buffer-local variables and
functions that relate to them, @pxref{Buffer Local Variables}.

  For functions and variables that relate to saving the contents of
buffers to files, @pxref{Writing to Files}.  For functions and variables
that relate to the display of buffers in windows, @pxref{Windows}.

@defun bufferp object
  This function returns @code{t} if @var{object} is a buffer,
@code{nil} otherwise.
@end defun

@defun current-buffer
  This function returns the current buffer.  There is always one and only one
buffer designated the current buffer.  Many editing commands act on the
current buffer.  It need not be displayed in a window.

@example
(current-buffer)
     @result{} #<buffer buffers.texinfo>
@end example
@end defun

@node Buffer Names, Buffer File Name, Buffer Basics , Buffers
@section Buffer Names
@cindex buffer names

  Each buffer has a unique name.  The buffer name may be used in place
of the buffer object in many functions that operate on buffers.  Buffers
that are generally ephemeral and uninteresting to the user have names
starting with a space; this prevents the buffer from being listed
by the @code{list-buffers} or @code{buffer-menu} command.

@cindex buffer name error
  Many of the following functions accept either a buffer or a buffer
name (a string) as an argument.  Any argument called
@var{buffer-or-name} is assumed to be one or the other, and it is an
error if it is not.  Any argument called @var{buffer} must be an
actual buffer, not a string.

@defun buffer-name &optional buffer
  This function returns the name of @var{buffer} as a string.  If
@var{buffer} is not supplied, it defaults to the current buffer.  If
the result of @code{buffer-name} is @code{nil}, then @var{buffer} has
been killed.

@example
(buffer-name)
     @result{} "buffers.texinfo"

(setq foo (get-buffer "temp"))
     @result{} #<buffer temp>
(kill-buffer foo)
     @result{} nil
(buffer-name foo)
     @result{} nil
foo
     @result{} #<killed buffer>
@end example
@end defun

@deffn Command rename-buffer newname
  This function renames the current buffer to @var{newname}.
It is an error if @var{newname} is not a string, or if there is
already a buffer with that name.  It returns @code{nil}.

  You can use this command to rename the @samp{*shell*} buffer to some
other name, which makes it possible for you to create a second shell
buffer inside of Emacs.
@end deffn

@defun get-buffer buffer-or-name
  This function returns the buffer @var{buffer-or-name}.  If
@var{buffer-or-name} is a string and there is no buffer of that name,
@code{nil} is returned.

  The argument passed to @code{get-buffer} is almost always the name of
a buffer.  Although @var{buffer-or-name} may be a buffer, this would not
be very useful.

@example
(setq b (get-buffer "lewis"))
     @result{} #<buffer lewis>
(get-buffer b)
     @result{} #<buffer lewis>
(get-buffer "Frazzle-nots")
     @result{} nil
@end example
@end defun

@node Buffer File Name, Buffer Contents, Buffer Names, Buffers
@section Buffer File Name

@cindex visited file
  The @dfn{buffer file name} is the name of the file that is visited in
that buffer.  When a buffer is not visiting a file, its buffer file name
is @code{nil}.

  For functions and variables that relate to saving the contents of
buffers to files, @pxref{Writing to Files}.  

@defun buffer-file-name &optional buffer
  This function returns the absolute file name of the file that the
buffer is visiting.  If @var{buffer} is not supplied, it defaults to the
current buffer.  If the buffer is not visiting any file, this returns
@code{nil}.

@example
(buffer-file-name (other-buffer))
     @result{} "/usr/user/lewis/manual/files.texinfo"
@end example
@end defun

@defvar buffer-file-name
  This buffer-local variable contains the name of the file being
visited in the current buffer, or @code{nil} if it is not visiting a file.

@example
buffer-file-name
@result{} "/usr/user/lewis/manual/buffers.texinfo"
@end example
@end defvar

@defun get-file-buffer filename
  This function returns the buffer visiting file @var{filename}.  If
there is no such buffer, it returns @var{nil}.  @var{filename} must
be a string.

@example
(get-file-buffer "buffers.texinfo")
@result{} #<buffer buffers.texinfo>
@end example

  In unusual circumstances, there can be more than one buffer visiting
the same file name.  In such cases, this function returns the first
such buffer in the buffer list.
@end defun

@deffn Command set-visited-file-name filename
  This function changes the name of the file visited in current buffer
to @var{filename}.  The @emph{next time} the buffer is saved it will go
in the newly specified file.  If the buffer had no visited file, this
can give it one.

  If @var{filename} is @code{nil} or is the empty string, that stands for
``no visited file''.  In this case, the buffer will not have a visited
file when this function returns, whether or not it had one previously.
Also see @code{clear-visited-file-modtime} and
@code{verify-visited-file-modtime} in @ref{Buffer Modification}.

  When @code{set-visited-file-name} is called interactively, Emacs
prompts for @var{filename} in the minibuffer.
@end deffn

@node Buffer Contents, Buffer Modification, Buffer File Name, Buffers
@section Buffer Contents

@cindex buffer contents
  The following functions return information about the buffer contents,
including their limits.  @xref{Text}, for functions that modify the
contents, and @ref{Searching and Matching}, for functions that search
the contents.

@defun buffer-substring start end
@cindex args-out-of-range error
  This function returns a string containing a copy of the text of the
region defined by positions @var{start} and @var{end} in the current
buffer.  If the arguments are not between the values returned by
@code{(point-min)} and @code{(point-max)}, Emacs signals an
@code{args-out-of-range} error

@group
@example
---------- Buffer: foo ----------
This is the contents of buffer foo

---------- Buffer: foo ----------

(buffer-substring 1 10)
@result{} "This is t"
(buffer-substring (point-max) 10)
@result{} "he contents of buffer foo
"
@end example
@end group
@end defun

@defun buffer-size
  This function returns the total number of characters in the current
buffer.  This number is one less than the number @code{point-max}
returns in the absence of a clipping restriction (@pxref{Clipping
Restrictions}).

@example
(buffer-size)
     @result{} 35
(point-max)
     @result{} 36
@end example
@end defun

@defvar buffer-saved-size
  The value of this buffer-local variable is the length of the current
buffer when it was last read in, saved or auto-saved.
@end defvar

@defun buffer-end flag
  This function returns @code{(point-min)} if @var{flag} is less than
@code{1}, @code{(point-max)} otherwise.
@end defun

@defun point-min
  This function returns the minimum accessible value of the point in the
current buffer.  This is @code{1}, unless a clipping restriction is in
effect, in which case it is the position of the start of the clipping
restriction.  (@xref{Clipping Restrictions}.)
@end defun

@defun point-max
  This function returns the maximum accessible value of the point in the
current buffer.  This is @code{(1+ (buffer-size))}, unless a clipping
restriction is in effect, in which case it is the position of the
end of the clipping restriction.  (@xref{Clipping Restrictions}).
@end defun

@defun buffer-string
  This function returns the contents of the current buffer as a string.

@example
(buffer-string)
     @result{} "This is the contents of buffer foo
"
@end example
@end defun

@node Buffer Modification, Modification Time, Buffer Contents, Buffers
@section Buffer Modification
@cindex buffer modification

  Emacs keeps a flag called the @dfn{modified flag} for each buffer, to
record whether you have changed the text of the buffer.  This flag is
set to @code{t} whenever you alter the contents, and cleared to
@code{nil} when you save the buffer.  Thus, the flag indicates whether
there are unsaved changes.  The flag value is normally indicated in the
mode line (@pxref{Major Line Information}), and controls saving
(@pxref{Saving Buffers}) and auto-saving (@pxref{Auto Saving}).

  Lisp programs also set the flag explicitly.  The Lisp function
@code{set-visited-file-name} sets the flag to @code{t}; even if the text
is unchanged since some other file was visited in the buffer, the text
does not match the new visited file.

@defun buffer-modified-p &optional buffer
  This function returns @code{t} if the buffer has been modified
since it was last read in from a file or saved, @code{nil}
otherwise.  If @var{buffer} is not supplied, the current buffer
is tested.
@end defun

@defun set-buffer-modified-p flag
  This function marks the current buffer as modified if @var{flag}
is @code{t} (or any non-@code{nil} value).  It marks the buffer as unmodified
if the flag is @code{nil}.

  Another effect of calling this function is to cause redisplay
of the mode line for the current buffer, unconditionally.
@end defun

@deffn Command not-modified
  Mark current buffer as unmodified, not needing to be saved.  Don't
use this function in programs!
@end deffn

  For functions that modify buffers, @pxref{Text}.

@node Modification Time, Read Only Buffers, Buffer Modification, Buffers
@comment  node-name,  next,  previous,  up
@section Comparison of Modification Time
@cindex comparison of modification time
@cindex modification time, comparison of 

  If you visit a file and make changes in the buffer, and meanwhile the
file itself is changed on disk, saving the buffer would overwrite the
changes in the file.  Occasionally, if the file was changed
inadvertently, this may be what you want.  Most of the time, it would
lose valuable information.  Emacs therefore checks the file's
modification time using the functions described below before saving the
file.

@defun verify-visited-file-modtime buffer
  This function compares Emacs's record of the modification time for the
file that the buffer is visiting and compares it to the actual
modification time of the file as recorded by the operating system.  The
two will be the same unless some other process has written the file since
Emacs visited or saved it.

  The function returns @code{t} if the last actual modification time and
Emacs's recorded modification time are the same, @code{nil} otherwise.
@end defun

@defun clear-visited-file-modtime
  This function clears out the record of the last modification time of
the file being visited by the current buffer.  This means that the next
attempt to save this buffer will certainly not complain of a discrepancy
among file modification times.

  This is used in @code{set-visited-file-name} and other exceptional
places where the usual test to avoid overwriting a changed file is
undesirable.
@end defun

@defun ask-user-about-supersession-threat fn
  Ask a user who is about to modify an obsolete buffer what to do.  An
@dfn{obsolete buffer} is one for which the associated file on disk is
newer than the last save-time of the buffer.  This means some other
program probably altered the file.

  This function is called automatically by Emacs on the proper
occasions.  You can redefine this function to do what you prefer.

@cindex file-supersession error
  Depending on the user's answer, the function may return normally, in
which case the modification of the buffer proceeds, or it may signal a
@code{file-supersession} error (with data @code{(@var{fn})}), in which
case the proposed buffer modification is not allowed.  
@end defun

@node Read Only Buffers, The Buffer List, Modification Time, Buffers
@section Read Only Buffers

  A buffer may be designated as @dfn{read-only}.  This means that the
buffer's contents may not be modified, although you may change your view
of the contents by scrolling, narrowing, or widening.

@defvar buffer-read-only
  This buffer-local variable specifies whether the buffer is
read-only.  If it is @code{nil}, then the buffer is not read-only,
otherwise it is.
@end defvar

@deffn Command toggle-read-only
  This command changes whether the current buffer is read-only,
regardless of whether it is visiting a file.  Don't use this command
in programs!
@end deffn

@defun barf-if-buffer-read-only
@cindex buffer-read-only error
  This function signals a @code{buffer-read-only} error if the current
buffer is read-only.  @xref{Interactive Call}, for another way to
signal an error if the current buffer is read-only.
@end defun

  Read-only buffers are used in two kinds of situations.

@itemize @bullet
@item
A buffer visiting a file is made read-only if the file is
write-protected.

Here, the purpose is to show the user that editing the buffer is
probably futile.  If the user wants to make changes anyway, he or she
can use @code{toggle-read-only}.

@item
Modes such as Dired and Rmail make buffers read-only when altering the
contents with the usual editing commands is probably a mistake.

The special commands of the mode in question bind
@code{buffer-read-only} to @code{nil} (with @code{let}) around the
places where they change the text.
@end itemize

@node The Buffer List, Creating Buffers, Read Only Buffers, Buffers
@section The Buffer List

  The @dfn{buffer list} is a list of all buffers that have not been
killed.  The order of the buffers in the list is based primarily on how
recently each buffer has been displayed in the selected window.  Several
functions, including @code{other-buffer}, depend on this order.

@defun buffer-list
  This function returns a list of all buffers, including those whose names
begin with a space.

@example
(buffer-list)
     @result{} (#<buffer buffers.texinfo> #<buffer  *Minibuf-1*>
    #<buffer buffer.c>  #<buffer *Help*> #<buffer TAGS>)

;; @r{Notice the name of the minibuffer begins with a space!}

(mapcar (function buffer-name) (buffer-list))
@result{} ("buffers.texinfo" " *Minibuf-1*" "buffer.c" "*Help*" "TAGS")
@end example
@end defun

@deffn Command list-buffers &optional files-only
  This function displays a listing of the names of existing buffers.  It
clears the buffer @code{*Buffer List*}, then inserts the listing into that
buffer and displays it in a window.

  All buffers that have names starting with spaces are omitted from
the display.

  If @var{files-only} is non-@code{nil}, then the list shows only buffers
that are visiting files.

  In the listing, the current buffer has a dot in the first column.
If the column labeled @samp{M} contains a @samp{*}, then that buffer has
been modified.  If the column labeled @samp{R} contains a @samp{%}, then
that buffer is @code{read-only}.

  @code{list-buffers} returns @code{nil}.

  The buffers are listed in the order which they appear in the buffer
list.  This is the order in which they are chosen as the default buffer
by such functions as @code{other-buffer}.

@example
(list-buffers)
     @result{} nil

---------- Buffer: *Buffer List* ----------
 MR Buffer         Size  Mode           File
 -- ------         ----  ----           ----
.*  buffers.texinfo  17870 Texinfo      /lewis/buffers.texinfo
    buffer.c       43204 C              /lewis/buffer.c
 *  *Help*         131   Fundamental
    TAGS           190930 Fundamental   /lewis/TAGS
 *% *Buffer List*  0     Buffer Menu
---------- Buffer: *Buffer List* ----------

(list-buffers t)
     @result{} nil

---------- Buffer: *Buffer List* ----------
 MR Buffer         Size  Mode           File
 -- ------         ----  ----           ----
.*  buffers.texinfo  17870 Texinfo      /lewis/buffers.texinfo
    buffer.c       43204 C              /lewis/buffer.c
  % TAGS           190930 Fundamental   /lewis/TAGS
---------- Buffer: *Buffer List* ----------
@end example
@end deffn

@deffn Command bury-buffer &optional buffer-or-name
  This function puts @var{buffer-or-name} at the end of the buffer
list without changing the order of any of the other buffers on the
list.  There it is the least desirable candidate for
@code{other-buffer} to return, and appears last in the list displayed
by @code{list-buffers}.

  If @var{buffer-or-name} is not supplied, it defaults to the current
buffer.

  If @var{buffer-or-name} is the current buffer, then the current buffer
is replaced in the selected window by the buffer selected by
@code{other-buffer}.  If the current buffer is displayed in a window
other than the selected one, it remains there.

  When called interactively, this function buries the current buffer.
@end deffn

@defun other-buffer &optional buffer-or-name
@cindex *scratch*
  This function returns the most recently current buffer other than
@var{buffer-or-name}.  If @var{buffer-or-name} is not supplied (or if it
is not a buffer), then @code{other-buffer} returns the first buffer on the
buffer list that is not visible in any window.  If no other buffer
exists, the buffer @samp{*scratch*} is returned.
@end defun

@node Creating Buffers, Killing Buffers, The Buffer List, Buffers
@section Creating Buffers

  The following two functions create buffers: @code{get-buffer-create}
may create a buffer if it finds no existing buffer;
@code{generate-new-buffer} always creates a new buffer, and gives it a
unique name.

  Two other functions that create buffers are
@code{with-output-to-temp-buffer} (@pxref{Temporary Displays}) and
@code{create-file-buffer} (@pxref{Visiting Files}).

@defun get-buffer-create name
  This function returns a buffer named @var{name}.  If such a buffer
already exists, it is returned.  If such a buffer does not exist,
one is created and returned.  The buffer does not become the current
buffer---this function does not change which buffer is current.

  It is an error if @var{name} is not a string.

@example
(get-buffer-create "foo")
     @result{} #<buffer foo>
@end example
@end defun

@defun generate-new-buffer name
  This function returns a newly created, empty buffer.  If there is no
buffer named @var{name}, then that is the name of the new buffer.  If
there is a buffer with that name, then suffixes of the form
@samp{<@var{n}>} are tried, where @var{n} is an integer starting with
2, until a new name is created.

  It is an error if @var{name} is not a string.

@example
(generate-new-buffer "bar")
     @result{} #<buffer bar>
(generate-new-buffer "bar")
     @result{} #<buffer bar<2>>
(generate-new-buffer "bar")
     @result{} #<buffer bar<3>>
@end example
@end defun

@node Killing Buffers, Changing Buffers, Creating Buffers, Buffers
@section Killing Buffers

  There are two functions for killing buffers.  One is for killing a
specified buffer; it is used in both in code and interactively.  The
other is used interactivley and is for going through the list of
displayed buffers and killing particular ones.

  The @code{buffer-name} of a killed buffer is @code{nil}.  You can use
this feature when testing whether a buffer has been killed.

@example
(defun killed-buffer-p (buffer-or-name)
  "Return t if buffer is killed."
  (not (buffer-name buffer-or-name)))
@end example

@deffn Command kill-buffer buffer-or-name
  This function kills the buffer @var{buffer-or-name}, freeing all of
its memory for use as space for other buffers.  (In version 18, the
memory is not returned to the operating system.)  The function returns
@code{nil}.

  A buffer which has been killed is marked specially so that you
cannot make it current or display it.  Its name is forgotten, and
@code{buffer-name} will return @code{nil} for it.  Killed buffers
retain their identity, however; two distinct buffers, when killed,
remain distinct according to @code{eq}.

  If the buffer is visiting a file when @code{kill-buffer} is called and
the buffer has not been saved since it was last modified, the user is
asked if he or she @emph{really} wants to kill the buffer.  This is done
even if @code{kill-buffer} is not called interactively.  To prevent this
request for confirmation, clear the modified flag before calling
@code{kill-buffer}.

@example
(kill-buffer "foo.unchanged")
     @result{} nil
(kill-buffer "foo.changed")

---------- Buffer: Minibuffer ----------
Buffer foo.changed modified; kill anyway? (yes or no) @b{yes}
---------- Buffer: Minibuffer ----------

     @result{} nil
@end example
@end deffn

@ignore
@deffn Command kill-some-buffers
  This command asks you which buffers you want to kill.  When this
command is called, Emacs goes through the list of displayed buffers;
and for each buffer, Emacs prints a line in the echo area, indicating
whether the buffer has been modified, and asking whether to kill it
(using @code{yes-or-no-p}).  If you answer is @samp{yes}, the buffer
is killed immediately.

  You are asked @emph{twice} whether to kill a buffer that has been
modified and is visiting a file.

  This function is for interactive use.  It does not ask about buffers
whose names begin with a space, such as minibuffers.
@end deffn
@end ignore

@node Changing Buffers,  , Killing Buffers, Buffers
@section Changing Buffers
@cindex selecting a buffer
@cindex switching to a buffer
@cindex changing to another buffer

  There are two major ways to change buffers: one way is to make it
@dfn{current}, the other way is to @dfn{switch} to the buffer.

  The current buffer is the one in which editing takes place; but it
is not necessarily displayed on the screen.  You may not be able to
see the current buffer.  Programs work on the current buffer---a
computer program does not have eyes and does not look at the buffer on
the screen.

  Switching to a buffer, on the other hand, not only makes the buffer the
current buffer, which is the one in which editing takes place; it also
displays the buffer in the selected window so you can see it.  Humans
must switch to a buffer they wish to work on since they have to see what
they are doing.

  Thus, directing Emacs's attention to a buffer does just one thing:
make it the current buffer; switching to a buffer does two things: make
it the current buffer, and display it on the screen.

  @code{switch-to-buffer} is a switch command; it changes the current
buffer (the one in which editing takes place) and displays it in the
selected window (the one with the cursor in it).

  @code{set-buffer} changes the current buffer, but leaves the buffer
that was displayed in the selected window still displayed.

  Note that when it comes time to get more keyboard input, or when
keyboard input is provided, the buffer displayed in the selected
window becomes the current buffer, regardless of previous calls to
@code{set-buffer}.  This prevents confusion: the buffer you see, when
Emacs reads a command, is the one to which your next command will apply.
@xref{Command Loop}.

  However, Lisp programs should not rely on this.  Always use
@code{set-buffer} within a @code{save-excursion} that will restore the
current buffer when your program is done.  (@xref{Excursions}.)
Otherwise, if your program is used as a subroutine, the caller will get
a surprise!  Here is an example: the code for the command
@code{append-to-buffer} (with the documentation string abridged):

@example
(defun append-to-buffer (buffer start end)
  "Append to specified buffer the text of the region.
  (interactive "BAppend to buffer: \nr")
  (let ((oldbuf (current-buffer)))
    (save-excursion
      (set-buffer (get-buffer-create buffer))
      (insert-buffer-substring oldbuf start end))))
@end example

@noindent
In this function, a local variable is bound to the current buffer, and
then @code{save-excursion} function records the values of point, mark,
and the original buffer.  Next, the @code{set-buffer} function makes a
new buffer current.  @code{insert-buffer-substring} then copies the
string from the original buffer to the current buffer.  Because the
current buffer is not displayed in the selected window, you normally
cannot see the insertion.  To see it, you have to switch to the other
buffer.

@defun set-buffer buffer-or-name
  This function makes @var{buffer-or-name} the current buffer in which
editing takes place.  However, it does not display the buffer in the
currently selected window or in any other window.  This means that the
user cannot necessarily see the buffer, but Lisp programs can work on
it.

   This function returns the buffer identified by @var{buffer-or-name}.
It is an error if @var{buffer-or-name} does not identify an existing
buffer.

  The @code{set-buffer} function is usually written within a
@code{save-excursion}, so that the original buffer will be restored
when the program is done.
@end defun

@deffn Command switch-to-buffer buffer-or-name &optional norecord
  This command makes @var{buffer-or-name} the current buffer
(the buffer in which editing takes place).  The command also displays the
buffer in the selected window, which is the window with the cursor in
it.  This means that a human can see the buffer and commands will
apply to it.  The return value is @code{nil}.

  If @var{buffer-or-name} does not identify an existing buffer, then
a new buffer by that name is created.

  If @var{norecord} is non-@code{nil}, then this buffer is not put on the
front of the list of recently chosen buffers.  This affects the value of
@code{other-buffer}.  (@xref{The Buffer List}.)

  The @code{switch-to-buffer} function is often used interactively,
as the binding of @kbd{C-x b}.  It is also used frequently in programs.

(Contrast @code{switch-to-buffer} with @code{set-buffer}, which makes
@var{buffer-or-name} the current buffer, but does not display it in the
selected window.)
@end deffn

@deffn Command switch-to-buffer-other-window buffer-or-name
  This function makes @var{buffer-or-name} be the current buffer in
another window, where editing may be done.  The other window becomes
the selected window, with the cursor there.  If there is only one
window, then it is split---even if that window is already displaying
@var{buffer-or-name}.
@end deffn

@defun pop-to-buffer buffer-or-name &optional other-window
  This function makes @var{buffer-or-name} be the current buffer (where
editing is done) in some window that is preferably different from the
selected window.  The ``popped-to'' window becomes the selected window,
with the cursor in it.  If the variable @code{pop-up-windows} is
non-@code{nil}, windows may be split to create a new window that is
different from the original window.  (@xref{Splitting Windows}, for a
description of @code{pop-up-windows}.

  If @var{other-window} is non-@code{nil}, @code{pop-to-buffer} finds
or creates another window even if @var{buffer-or-name} is already
visible in the selected window.  Thus @var{buffer-or-name} could be
displayed in two windows.  On the other hand, if @var{buffer-or-name}
is the current buffer and @var{other-window} is @code{nil}, Emacs will
stay with the same buffer in the same window.

  If @var{buffer-or-name} is a string that does not name an existing
buffer, a buffer by that name is created.
@end defun

@defun display-buffer buffer-or-name &optional not-this-window
@cindex splitting windows
  This function makes @var{buffer-or-name} appear in some window, like
@code{pop-to-buffer}, but it does not select that window and does not
make the buffer current.  The selected window is unaltered by this
function.

  If @var{not-this-window} is non-@code{nil} and @var{buffer-or-name} is
shown already in the selected window, then the buffer is displayed in
a second window as well.  Otherwise, if @var{buffer-or-name} is
already shown in any window, that is good enough, so this function
does nothing.

  If the variable @code{pop-up-windows} is non-@code{nil}, windows can
be split to display the buffer.  If there are multiple windows,
@code{display-buffer} will split the largest window if it has more than
the number of lines specified by the variable
@code{split-height-threshold}.  (@xref{Splitting Windows}, for a
description of the two variables.)

  @code{display-buffer} returns the window displaying @var{buffer-or-name}.
@end defun

@defopt pop-up-windows
  This global variable determines if @code{display-buffer} may make new
windows.  If it is @code{t} and there is only one window on the screen, then
that window is split.  If it is @code{nil}, then @code{display-buffer}
does not split the single window, but rather replaces its buffer.
@end defopt

@defopt split-height-threshold
  This global variable determines when @code{display-buffer} may split a
window, assuming that there are multiple windows.  @code{display-buffer}
splits the largest window if it has at least this many lines.

  If there is only one window, it splits regardless of this value,
provided @code{pop-up-windows} is non-@code{nil}.
@end defopt
DataMuseum.dk

DKUUG/EUUG Conference tapes

⟦827afc557⟧ TextFile

Derivation

TextFile
