X-Git-Url: http://git.hcoop.net/bpt/emacs.git/blobdiff_plain/2311d8e5a62b8b6dd7dde45b4b8059d443e2abac..299ccd03f94008a1580a0dbbfd56c32484dd20f8:/doc/lispref/buffers.texi diff --git a/doc/lispref/buffers.texi b/doc/lispref/buffers.texi index 844b6423a5..1293a03082 100644 --- a/doc/lispref/buffers.texi +++ b/doc/lispref/buffers.texi @@ -1,9 +1,9 @@ @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, Windows, Backups and Auto-Saving, Top +@node Buffers @chapter Buffers @cindex buffer @@ -23,9 +23,9 @@ not be displayed in any windows. * Buffer File Name:: The buffer file name indicates which file is visited. * Buffer Modification:: A buffer is @dfn{modified} if it needs to be saved. * Modification Time:: Determining whether the visited file was changed - ``behind Emacs's back''. + "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. @@ -34,7 +34,6 @@ not be displayed in any windows. @end menu @node Buffer Basics -@comment node-name, next, previous, up @section Buffer Basics @ifnottex @@ -481,7 +480,7 @@ correspond to the new file name, unless the new name is already in use. If @var{filename} is @code{nil} or the empty string, that stands for -``no visited file.'' In this case, @code{set-visited-file-name} marks +``no visited file''. In this case, @code{set-visited-file-name} marks the buffer as having no visited file, without changing the buffer's modified flag. @@ -489,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 @@ -588,7 +588,6 @@ current buffer is used. @end defun @node Modification Time -@comment node-name, next, previous, up @section Buffer Modification Time @cindex comparing file modification time @cindex modification time of buffer @@ -633,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 @@ -648,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} @@ -666,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 @@ -732,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 -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 @@ -744,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 -@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 @@ -764,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 @@ -883,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 @@ -893,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}. @@ -915,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 @@ -1061,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 @@ -1234,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 -