X-Git-Url: http://git.hcoop.net/bpt/emacs.git/blobdiff_plain/7e570fbf3ef8ccd31df2651f5d2775c5697d5950..299ccd03f94008a1580a0dbbfd56c32484dd20f8:/doc/lispref/buffers.texi diff --git a/doc/lispref/buffers.texi b/doc/lispref/buffers.texi index 6ad329f3a3..1293a03082 100644 --- 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 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 @@ -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. -* 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. @@ -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 -@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 @@ -631,12 +632,12 @@ exceptional places where the usual test to avoid overwriting a changed 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 -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 @@ -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. -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 -@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} @@ -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 -@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 @@ -740,31 +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 -@deffn Command toggle-read-only &optional arg message -This command toggles whether the current buffer is read-only, by -setting the variable @code{buffer-read-only}. If @var{arg} is -non-@code{nil}, it should be a raw prefix argument; the command then -makes the buffer read-only if the numeric value of that prefix -argument is positive, and makes the buffer writable otherwise. -@xref{Prefix Command Arguments}. - -If called interactively, or if called from Lisp with @var{message} is -non-@code{nil}, the command prints a message reporting the buffer's -new read-only status. - -When making the buffer read-only, this command also enables View mode +@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 making the buffer writable, it disables View mode if View mode -was enabled. - -Lisp programs should only call @code{toggle-read-only} if they really -intend to do the same thing as the user command, including possibly -enabling or disabling View mode. Note also that this command works by -setting @code{buffer-read-only}, so even if you make the buffer -writable, characters with non-@code{nil} @code{read-only} text -properties will remain read-only. To temporarily ignore all read-only -states, bind @code{inhibit-read-only}, as described above. +When disabling Read Only mode, it disables View mode if View mode was +enabled. @end deffn @defun barf-if-buffer-read-only @@ -773,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 -@node The Buffer List +@node Buffer List @section The Buffer List @cindex buffer list @@ -892,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. -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 @@ -902,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 -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}. @@ -924,6 +910,13 @@ buffer returned by @code{last-buffer} (see above), in the selected 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 @@ -1070,7 +1063,7 @@ Buffer foo.changed modified; kill anyway? (yes or no) @kbd{yes} @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 @@ -1243,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 -