Fix last change in lispref.

[gnu-emacs] / doc / lispref / buffers.texi

diff --git a/doc/lispref/buffers.texi b/doc/lispref/buffers.texi
index 072ffeb43214f48a03b20aecf41c92b3e45027cb..1293a03082cd0e0f9bb3f0107b9f606dd87445a2 100644 (file)
--- a/doc/lispref/buffers.texi
+++ b/doc/lispref/buffers.texi
@@ -1,7 +1,7 @@
 @c -*-texinfo-*-
 @c This is part of the GNU Emacs Lisp Reference Manual.
 @c -*-texinfo-*-
 @c This is part of the GNU Emacs Lisp Reference Manual.

-@c Copyright (C) 1990-1995, 1998-1999, 2001-2012
-@c   Free Software Foundation, Inc.
+@c Copyright (C) 1990-1995, 1998-1999, 2001-2014 Free Software
+@c Foundation, Inc.

 @c See the file elisp.texi for copying conditions.
 @node Buffers
 @chapter Buffers
 @c See the file elisp.texi for copying conditions.
 @node Buffers
 @chapter Buffers


@@ -25,7 +25,7 @@ not be displayed in any windows.
 * Modification Time::   Determining whether the visited file was changed
                          "behind Emacs's back".
 * Read Only Buffers::   Modifying text is not allowed in a read-only buffer.
 * Modification Time::   Determining whether the visited file was changed
                          "behind Emacs's back".
 * Read Only Buffers::   Modifying text is not allowed in a read-only buffer.

-* The Buffer List::     How to look at all the existing buffers.
+* Buffer List::         How to look at all the existing buffers.

 * Creating Buffers::    Functions that create buffers.
 * Killing Buffers::     Buffers exist until explicitly killed.
 * Indirect Buffers::    An indirect buffer shares text with some other buffer.
 * Creating Buffers::    Functions that create buffers.
 * Killing Buffers::     Buffers exist until explicitly killed.
 * Indirect Buffers::    An indirect buffer shares text with some other buffer.


@@ -488,8 +488,9 @@ Normally, this function asks the user for confirmation if there
 already is a buffer visiting @var{filename}.  If @var{no-query} is
 non-@code{nil}, that prevents asking this question.  If there already
 is a buffer visiting @var{filename}, and the user confirms or
 already is a buffer visiting @var{filename}.  If @var{no-query} is
 non-@code{nil}, that prevents asking this question.  If there already
 is a buffer visiting @var{filename}, and the user confirms or

-@var{query} is non-@code{nil}, this function makes the new buffer name
-unique by appending a number inside of @samp{<@dots{}>} to @var{filename}.
+@var{no-query} is non-@code{nil}, this function makes the new
+buffer name unique by appending a number inside of @samp{<@dots{}>} to
+@var{filename}.

 
 If @var{along-with-file} is non-@code{nil}, that means to assume that
 the former visited file has been renamed to @var{filename}.  In this
 
 If @var{along-with-file} is non-@code{nil}, that means to assume that
 the former visited file has been renamed to @var{filename}.  In this


@@ -631,12 +632,12 @@ exceptional places where the usual test to avoid overwriting a changed
 file should not be done.
 @end defun
 
 file should not be done.
 @end defun
 

-@c Emacs 19 feature

 @defun visited-file-modtime
 This function returns the current buffer's recorded last file
 @defun visited-file-modtime
 This function returns the current buffer's recorded last file

-modification time, as a list of the form @code{(@var{high} @var{low})}.
-(This is the same format that @code{file-attributes} uses to return
-time values; see @ref{File Attributes}.)
+modification time, as a list of the form @code{(@var{high} @var{low}
+@var{microsec} @var{picosec})}.  (This is the same format that
+@code{file-attributes} uses to return time values; @pxref{File
+Attributes}.)

 
 If the buffer has no recorded last modification time, this function
 returns zero.  This case occurs, for instance, if the buffer is not
 
 If the buffer has no recorded last modification time, this function
 returns zero.  This case occurs, for instance, if the buffer is not


@@ -646,17 +647,9 @@ visiting a file or if the time has been explicitly cleared by
 too.  For instance, in a Dired buffer listing a directory, it returns
 the last modification time of that directory, as recorded by Dired.
 
 too.  For instance, in a Dired buffer listing a directory, it returns
 the last modification time of that directory, as recorded by Dired.
 

-For a new buffer visiting a not yet existing file, @var{high} is
-@minus{}1 and @var{low} is 65535, that is,
-@ifnottex
-@w{2**16 - 1.}
-@end ifnottex
-@tex
-@math{2^{16}-1}.
-@end tex
+If the buffer is not visiting a file, this function returns -1.

 @end defun
 
 @end defun
 

-@c Emacs 19 feature

 @defun set-visited-file-modtime &optional time
 This function updates the buffer's record of the last modification time
 of the visited file, to the value specified by @var{time} if @var{time}
 @defun set-visited-file-modtime &optional time
 This function updates the buffer's record of the last modification time
 of the visited file, to the value specified by @var{time} if @var{time}


@@ -664,9 +657,8 @@ is not @code{nil}, and otherwise to the last modification time of the
 visited file.
 
 If @var{time} is neither @code{nil} nor zero, it should have the form
 visited file.
 
 If @var{time} is neither @code{nil} nor zero, it should have the form

-@code{(@var{high} . @var{low})} or @code{(@var{high} @var{low})}, in
-either case containing two integers, each of which holds 16 bits of the
-time.
+@code{(@var{high} @var{low} @var{microsec} @var{picosec})},
+the format used by @code{current-time} (@pxref{Time of Day}).

 
 This function is useful if the buffer was not read from the file
 normally, or if the file itself has been changed for some known benign
 
 This function is useful if the buffer was not read from the file
 normally, or if the file itself has been changed for some known benign


@@ -730,11 +722,9 @@ The buffer is read-only if this variable is non-@code{nil}.
 @defvar inhibit-read-only
 If this variable is non-@code{nil}, then read-only buffers and,
 depending on the actual value, some or all read-only characters may be
 @defvar inhibit-read-only
 If this variable is non-@code{nil}, then read-only buffers and,
 depending on the actual value, some or all read-only characters may be

-modified.  Read-only characters in a buffer are those that have
-non-@code{nil} @code{read-only} properties (either text properties or
-overlay properties).  @xref{Special Properties}, for more information
-about text properties.  @xref{Overlays}, for more information about
-overlays and their properties.
+modified.  Read-only characters in a buffer are those that have a
+non-@code{nil} @code{read-only} text property.  @xref{Special
+Properties}, for more information about text properties.

 
 If @code{inhibit-read-only} is @code{t}, all @code{read-only} character
 properties have no effect.  If @code{inhibit-read-only} is a list, then
 
 If @code{inhibit-read-only} is @code{t}, all @code{read-only} character
 properties have no effect.  If @code{inhibit-read-only} is a list, then


@@ -742,18 +732,25 @@ properties have no effect.  If @code{inhibit-read-only} is a list, then
 of the list (comparison is done with @code{eq}).
 @end defvar
 
 of the list (comparison is done with @code{eq}).
 @end defvar
 

-@deffn Command toggle-read-only &optional arg
-This command toggles whether the current buffer is read-only.  It is
-intended for interactive use; do not use it in programs (it may have
-side-effects, such as enabling View mode, and does not affect
-read-only text properties).  To change the read-only state of a buffer in
-a program, explicitly set @code{buffer-read-only} to the proper value.
-To temporarily ignore a read-only state, bind @code{inhibit-read-only}.
-
-If @var{arg} is non-@code{nil}, it should be a raw prefix argument.
-@code{toggle-read-only} sets @code{buffer-read-only} to @code{t} if
-the numeric value of that prefix argument is positive and to
-@code{nil} otherwise.  @xref{Prefix Command Arguments}.
+@deffn Command read-only-mode &optional arg
+This is the mode command for Read Only minor mode, a buffer-local
+minor mode.  When the mode is enabled, @code{buffer-read-only} is
+non-@code{nil} in the buffer; when disabled, @code{buffer-read-only}
+is @code{nil} in the buffer.  The calling convention is the same as
+for other minor mode commands (@pxref{Minor Mode Conventions}).
+
+This minor mode mainly serves as a wrapper for
+@code{buffer-read-only}; unlike most minor modes, there is no separate
+@code{read-only-mode} variable.  Even when Read Only mode is disabled,
+characters with non-@code{nil} @code{read-only} text properties remain
+read-only.  To temporarily ignore all read-only states, bind
+@code{inhibit-read-only}, as described above.
+
+When enabling Read Only mode, this mode command also enables View mode
+if the option @code{view-read-only} is non-@code{nil}.  @xref{Misc
+Buffer,,Miscellaneous Buffer Operations, emacs, The GNU Emacs Manual}.
+When disabling Read Only mode, it disables View mode if View mode was
+enabled.

 @end deffn
 
 @defun barf-if-buffer-read-only
 @end deffn
 
 @defun barf-if-buffer-read-only


@@ -762,7 +759,7 @@ buffer is read-only.  @xref{Using Interactive}, for another way to
 signal an error if the current buffer is read-only.
 @end defun
 
 signal an error if the current buffer is read-only.
 @end defun
 

-@node The Buffer List
+@node Buffer List

 @section The Buffer List
 @cindex buffer list
 
 @section The Buffer List
 @cindex buffer list
 


@@ -881,7 +878,7 @@ This buffer therefore becomes the least desirable candidate for
 @code{other-buffer} to return.  The argument can be either a buffer
 itself or the name of one.
 
 @code{other-buffer} to return.  The argument can be either a buffer
 itself or the name of one.
 

-This functions operates on each frame's @code{buffer-list} parameter as
+This function operates on each frame's @code{buffer-list} parameter as

 well as the fundamental buffer list; therefore, the buffer that you bury
 will come last in the value of @code{(buffer-list @var{frame})} and in
 the value of @code{(buffer-list)}.  In addition, it also puts the buffer
 well as the fundamental buffer list; therefore, the buffer that you bury
 will come last in the value of @code{(buffer-list @var{frame})} and in
 the value of @code{(buffer-list)}.  In addition, it also puts the buffer


@@ -891,15 +888,15 @@ History}) provided it is shown in that window.
 If @var{buffer-or-name} is @code{nil} or omitted, this means to bury the
 current buffer.  In addition, if the current buffer is displayed in the
 selected window, this makes sure that the window is either deleted or
 If @var{buffer-or-name} is @code{nil} or omitted, this means to bury the
 current buffer.  In addition, if the current buffer is displayed in the
 selected window, this makes sure that the window is either deleted or

-another buffer is shown in it.  More precisely, if the window is
-dedicated (@pxref{Dedicated Windows}) and there are other windows on its
-frame, the window is deleted.  If the window is both dedicated and the
-only window on its frame's terminal, the function specified by
-@code{frame-auto-hide-function} (@pxref{Quitting Windows}) will deal
-with the window.  If the window is not dedicated to its buffer, it calls
-@code{switch-to-prev-buffer} (@pxref{Window History}) to show another
-buffer in that window.  If @var{buffer-or-name} is displayed in some
-other window, it remains displayed there.
+another buffer is shown in it.  More precisely, if the selected window
+is dedicated (@pxref{Dedicated Windows}) and there are other windows on
+its frame, the window is deleted.  If it is the only window on its frame
+and that frame is not the only frame on its terminal, the frame is
+``dismissed'' by calling the function specified by
+@code{frame-auto-hide-function} (@pxref{Quitting Windows}).  Otherwise,
+it calls @code{switch-to-prev-buffer} (@pxref{Window History}) to show
+another buffer in that window.  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}.
 
 To replace a buffer in all the windows that display it, use
 @code{replace-buffer-in-windows}, @xref{Buffers and Windows}.


@@ -913,6 +910,13 @@ buffer returned by @code{last-buffer} (see above), in the selected
 window.
 @end deffn
 
 window.
 @end deffn
 

+@defvar buffer-list-update-hook
+This is a normal hook run whenever the buffer list changes.  Functions
+(implicitly) running this hook are @code{get-buffer-create}
+(@pxref{Creating Buffers}), @code{rename-buffer} (@pxref{Buffer Names}),
+@code{kill-buffer} (@pxref{Killing Buffers}), @code{bury-buffer} (see
+above) and @code{select-window} (@pxref{Selecting Windows}).
+@end defvar

 
 @node Creating Buffers
 @section Creating Buffers
 
 @node Creating Buffers
 @section Creating Buffers


@@ -1059,7 +1063,7 @@ Buffer foo.changed modified; kill anyway? (yes or no) @kbd{yes}
 @end deffn
 
 @defvar kill-buffer-query-functions
 @end deffn
 
 @defvar kill-buffer-query-functions

-After confirming unsaved changes, @code{kill-buffer} calls the functions
+Before confirming unsaved changes, @code{kill-buffer} calls the functions

 in the list @code{kill-buffer-query-functions}, in order of appearance,
 with no arguments.  The buffer being killed is the current buffer when
 they are called.  The idea of this feature is that these functions will
 in the list @code{kill-buffer-query-functions}, in order of appearance,
 with no arguments.  The buffer being killed is the current buffer when
 they are called.  The idea of this feature is that these functions will


@@ -1232,4 +1236,3 @@ This function returns the current gap position in the current buffer.
 @defun gap-size
 This function returns the current gap size of the current buffer.
 @end defun
 @defun gap-size
 This function returns the current gap size of the current buffer.
 @end defun

-