X-Git-Url: http://git.chise.org/gitweb/?a=blobdiff_plain;f=info%2Flispref.info-25;h=02833772944e0d000e8d554c071560fc1cba9e88;hb=b5f26301ee1ad7dbc9ad1c22e5b8564b5161d9ad;hp=7329de7b778ca44a03480900c024892be8f13eb5;hpb=7d6edaefa00e7b7e102354283824a4f6a721b71a;p=chise%2Fxemacs-chise.git diff --git a/info/lispref.info-25 b/info/lispref.info-25 index 7329de7..0283377 100644 --- a/info/lispref.info-25 +++ b/info/lispref.info-25 @@ -1,4 +1,4 @@ -This is ../info/lispref.info, produced by makeinfo version 4.0 from +This is ../info/lispref.info, produced by makeinfo version 4.0b from lispref/lispref.texi. INFO-DIR-SECTION XEmacs Editor @@ -50,1165 +50,1098 @@ may be included in a translation approved by the Free Software Foundation instead of in the original English.  -File: lispref.info, Node: The Buffer List, Next: Creating Buffers, Prev: Read Only Buffers, Up: Buffers +File: lispref.info, Node: Rename or Copy, Next: Numbered Backups, Prev: Making Backups, Up: Backup Files -The Buffer List -=============== +Backup by Renaming or by Copying? +--------------------------------- - The "buffer list" is a list of all live buffers. Creating a buffer -adds it to this list, and killing a buffer deletes it. The order of -the buffers in the list is based primarily on how recently each buffer -has been displayed in the selected window. Buffers move to the front -of the list when they are selected and to the end when they are buried. -Several functions, notably `other-buffer', use this ordering. A -buffer list displayed for the user also follows this order. + There are two ways that XEmacs can make a backup file: - Every frame has its own order for the buffer list. Switching to a -new buffer inside of a particular frame changes the buffer list order -for that frame, but does not affect the buffer list order of any other -frames. In addition, there is a global, non-frame buffer list order -that is independent of the buffer list orders for any particular frame. + * XEmacs can rename the original file so that it becomes a backup + file, and then write the buffer being saved into a new file. + After this procedure, any other names (i.e., hard links) of the + original file now refer to the backup file. The new file is owned + by the user doing the editing, and its group is the default for + new files written by the user in that directory. - Note that the different buffer lists all contain the same elements. -It is only the order of those elements that is different. + * XEmacs can copy the original file into a backup file, and then + overwrite the original file with new contents. After this + procedure, any other names (i.e., hard links) of the original file + still refer to the current version of the file. The file's owner + and group will be unchanged. - - Function: buffer-list &optional frame - This function returns a list of all buffers, including those whose - names begin with a space. The elements are actual buffers, not - their names. The order of the list is specific to FRAME, which - defaults to the current frame. If FRAME is `t', the global, - non-frame ordering is returned instead. + The first method, renaming, is the default. - (buffer-list) - => (# - # # - # #) - - ;; Note that the name of the minibuffer - ;; begins with a space! - (mapcar (function buffer-name) (buffer-list)) - => ("buffers.texi" " *Minibuf-1*" - "buffer.c" "*Help*" "TAGS") + The variable `backup-by-copying', if non-`nil', says to use the +second method, which is to copy the original file and overwrite it with +the new buffer contents. The variable `file-precious-flag', if +non-`nil', also has this effect (as a sideline of its main +significance). *Note Saving Buffers::. - Buffers appear earlier in the list if they were current more - recently. + - Variable: backup-by-copying + If this variable is non-`nil', XEmacs always makes backup files by + copying. - This list is a copy of a list used inside XEmacs; modifying it has - no effect on the buffers. + The following two variables, when non-`nil', cause the second method +to be used in certain special cases. They have no effect on the +treatment of files that don't fall into the special cases. - - Function: other-buffer &optional buffer-or-name frame visible-ok - This function returns the first buffer in the buffer list other - than BUFFER-OR-NAME, in FRAME's ordering for the buffer list. - (FRAME defaults to the current frame. If FRAME is `t', then the - global, non-frame ordering is used.) Usually this is the buffer - most recently shown in the selected window, aside from - BUFFER-OR-NAME. Buffers are moved to the front of the list when - they are selected and to the end when they are buried. Buffers - whose names start with a space are not considered. + - Variable: backup-by-copying-when-linked + If this variable is non-`nil', XEmacs makes backups by copying for + files with multiple names (hard links). - If BUFFER-OR-NAME is not supplied (or if it is not a buffer), then - `other-buffer' returns the first buffer on the buffer list that is - not visible in any window in a visible frame. + This variable is significant only if `backup-by-copying' is `nil', + since copying is always used when that variable is non-`nil'. - If the selected frame has a non-`nil' `buffer-predicate' property, - then `other-buffer' uses that predicate to decide which buffers to - consider. It calls the predicate once for each buffer, and if the - value is `nil', that buffer is ignored. *Note X Frame - Properties::. + - Variable: backup-by-copying-when-mismatch + If this variable is non-`nil', XEmacs makes backups by copying in + cases where renaming would change either the owner or the group of + the file. - If VISIBLE-OK is `nil', `other-buffer' avoids returning a buffer - visible in any window on any visible frame, except as a last - resort. If VISIBLE-OK is non-`nil', then it does not matter - whether a buffer is displayed somewhere or not. + The value has no effect when renaming would not alter the owner or + group of the file; that is, for files which are owned by the user + and whose group matches the default for a new file created there + by the user. - If no suitable buffer exists, the buffer `*scratch*' is returned - (and created, if necessary). + This variable is significant only if `backup-by-copying' is `nil', + since copying is always used when that variable is non-`nil'. - Note that in FSF Emacs 19, there is no FRAME argument, and - VISIBLE-OK is the second argument instead of the third. FSF Emacs - 19. + +File: lispref.info, Node: Numbered Backups, Next: Backup Names, Prev: Rename or Copy, Up: Backup Files - - Command: list-buffers &optional files-only - This function displays a listing of the names of existing buffers. - It clears the buffer `*Buffer List*', then inserts the listing - into that buffer and displays it in a window. `list-buffers' is - intended for interactive use, and is described fully in `The XEmacs - Reference Manual'. It returns `nil'. +Making and Deleting Numbered Backup Files +----------------------------------------- - - Command: bury-buffer &optional buffer-or-name - This function puts BUFFER-OR-NAME at the end of the buffer list - without changing the order of any of the other buffers on the list. - This buffer therefore becomes the least desirable candidate for - `other-buffer' to return. + If a file's name is `foo', the names of its numbered backup versions +are `foo.~V~', for various integers V, like this: `foo.~1~', `foo.~2~', +`foo.~3~', ..., `foo.~259~', and so on. - If BUFFER-OR-NAME is `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 - `other-buffer') in the selected window. But if the buffer is - displayed in some other window, it remains displayed there. + - User Option: version-control + This variable controls whether to make a single non-numbered backup + file or multiple numbered backups. - If you wish to replace a buffer in all the windows that display - it, use `replace-buffer-in-windows'. *Note Buffers and Windows::. + `nil' + Make numbered backups if the visited file already has + numbered backups; otherwise, do not. + + `never' + Do not make numbered backups. + + ANYTHING ELSE + Make numbered backups. + + The use of numbered backups ultimately leads to a large number of +backup versions, which must then be deleted. XEmacs can do this +automatically or it can ask the user whether to delete them. + + - User Option: kept-new-versions + The value of this variable is the number of newest versions to keep + when a new numbered backup is made. The newly made backup is + included in the count. The default value is 2. + + - User Option: kept-old-versions + The value of this variable is the number of oldest versions to keep + when a new numbered backup is made. The default value is 2. + + If there are backups numbered 1, 2, 3, 5, and 7, and both of these +variables have the value 2, then the backups numbered 1 and 2 are kept +as old versions and those numbered 5 and 7 are kept as new versions; +backup version 3 is excess. The function `find-backup-file-name' +(*note Backup Names::) is responsible for determining which backup +versions to delete, but does not delete them itself. + + - User Option: delete-old-versions + If this variable is non-`nil', then saving a file deletes excess + backup versions silently. Otherwise, it asks the user whether to + delete them. + + - User Option: dired-kept-versions + This variable specifies how many of the newest backup versions to + keep in the Dired command `.' (`dired-clean-directory'). That's + the same thing `kept-new-versions' specifies when you make a new + backup file. The default value is 2.  -File: lispref.info, Node: Creating Buffers, Next: Killing Buffers, Prev: The Buffer List, Up: Buffers - -Creating Buffers -================ - - This section describes the two primitives for creating buffers. -`get-buffer-create' creates a buffer if it finds no existing buffer -with the specified name; `generate-new-buffer' always creates a new -buffer and gives it a unique name. +File: lispref.info, Node: Backup Names, Prev: Numbered Backups, Up: Backup Files - Other functions you can use to create buffers include -`with-output-to-temp-buffer' (*note Temporary Displays::) and -`create-file-buffer' (*note Visiting Files::). Starting a subprocess -can also create a buffer (*note Processes::). +Naming Backup Files +------------------- - - Function: get-buffer-create name - This function returns a buffer named NAME. It returns an existing - buffer with that name, if one exists; otherwise, it creates a new - buffer. The buffer does not become the current buffer--this - function does not change which buffer is current. + The functions in this section are documented mainly because you can +customize the naming conventions for backup files by redefining them. +If you change one, you probably need to change the rest. - An error is signaled if NAME is not a string. + - Function: backup-file-name-p filename + This function returns a non-`nil' value if FILENAME is a possible + name for a backup file. A file with the name FILENAME need not + exist; the function just checks the name. - (get-buffer-create "foo") - => # + (backup-file-name-p "foo") + => nil + (backup-file-name-p "foo~") + => 3 - The major mode for the new buffer is set to Fundamental mode. The - variable `default-major-mode' is handled at a higher level. *Note - Auto Major Mode::. + The standard definition of this function is as follows: - - Function: generate-new-buffer name - This function returns a newly created, empty buffer, but does not - make it current. If there is no buffer named NAME, then that is - the name of the new buffer. If that name is in use, this function - adds suffixes of the form `' to NAME, where N is an integer. - It tries successive integers starting with 2 until it finds an - available name. + (defun backup-file-name-p (file) + "Return non-nil if FILE is a backup file \ + name (numeric or not)..." + (string-match "~$" file)) - An error is signaled if NAME is not a string. + Thus, the function returns a non-`nil' value if the file name ends + with a `~'. (We use a backslash to split the documentation + string's first line into two lines in the text, but produce just + one line in the string itself.) - (generate-new-buffer "bar") - => # - (generate-new-buffer "bar") - => #> - (generate-new-buffer "bar") - => #> + This simple expression is placed in a separate function to make it + easy to redefine for customization. - The major mode for the new buffer is set to Fundamental mode. The - variable `default-major-mode' is handled at a higher level. *Note - Auto Major Mode::. + - Function: make-backup-file-name filename + This function returns a string that is the name to use for a + non-numbered backup file for file FILENAME. On Unix, this is just + FILENAME with a tilde appended. - See the related function `generate-new-buffer-name' in *Note - Buffer Names::. + The standard definition of this function is as follows: - -File: lispref.info, Node: Killing Buffers, Next: Indirect Buffers, Prev: Creating Buffers, Up: Buffers + (defun make-backup-file-name (file) + "Create the non-numeric backup file name for FILE. + ..." + (concat file "~")) -Killing Buffers -=============== + You can change the backup-file naming convention by redefining this + function. The following example redefines `make-backup-file-name' + to prepend a `.' in addition to appending a tilde: - "Killing a buffer" makes its name unknown to XEmacs and makes its -text space available for other use. - - The buffer object for the buffer that has been killed remains in -existence as long as anything refers to it, but it is specially marked -so that you cannot make it current or display it. Killed buffers retain -their identity, however; two distinct buffers, when killed, remain -distinct according to `eq'. - - If you kill a buffer that is current or displayed in a window, XEmacs -automatically selects or displays some other buffer instead. This means -that killing a buffer can in general change the current buffer. -Therefore, when you kill a buffer, you should also take the precautions -associated with changing the current buffer (unless you happen to know -that the buffer being killed isn't current). *Note Current Buffer::. - - If you kill a buffer that is the base buffer of one or more indirect -buffers, the indirect buffers are automatically killed as well. - - The `buffer-name' of a killed buffer is `nil'. To test whether a -buffer has been killed, you can either use this feature or the function -`buffer-live-p'. - - - Function: buffer-live-p buffer - This function returns `nil' if BUFFER is deleted, and `t' - otherwise. - - - Command: kill-buffer buffer-or-name - This function kills the buffer BUFFER-OR-NAME, freeing all its - memory for use as space for other buffers. (Emacs version 18 and - older was unable to return the memory to the operating system.) - It returns `nil'. - - Any processes that have this buffer as the `process-buffer' are - sent the `SIGHUP' signal, which normally causes them to terminate. - (The basic meaning of `SIGHUP' is that a dialup line has been - disconnected.) *Note Deleting Processes::. - - If the buffer is visiting a file and contains unsaved changes, - `kill-buffer' asks the user to confirm before the buffer is killed. - It does this even if not called interactively. To prevent the - request for confirmation, clear the modified flag before calling - `kill-buffer'. *Note Buffer Modification::. - - Killing a buffer that is already dead has no effect. - - (kill-buffer "foo.unchanged") - => nil - (kill-buffer "foo.changed") - - ---------- Buffer: Minibuffer ---------- - Buffer foo.changed modified; kill anyway? (yes or no) yes - ---------- Buffer: Minibuffer ---------- + (defun make-backup-file-name (filename) + (concat "." filename "~")) - => nil - - - Variable: kill-buffer-query-functions - After confirming unsaved changes, `kill-buffer' calls the functions - in the list `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 is that these functions ask for - confirmation from the user for various nonstandard reasons. If - any of them returns `nil', `kill-buffer' spares the buffer's life. - - - Variable: kill-buffer-hook - This is a normal hook run by `kill-buffer' after asking all the - questions it is going to ask, just before actually killing the - buffer. The buffer to be killed is current when the hook - functions run. *Note Hooks::. - - - Variable: buffer-offer-save - This variable, if non-`nil' in a particular buffer, tells - `save-buffers-kill-emacs' and `save-some-buffers' to offer to save - that buffer, just as they offer to save file-visiting buffers. The - variable `buffer-offer-save' automatically becomes buffer-local - when set for any reason. *Note Buffer-Local Variables::. - - -File: lispref.info, Node: Indirect Buffers, Prev: Killing Buffers, Up: Buffers - -Indirect Buffers -================ + (make-backup-file-name "backups.texi") + => ".backups.texi~" - An "indirect buffer" shares the text of some other buffer, which is -called the "base buffer" of the indirect buffer. In some ways it is -the analogue, for buffers, of a symbolic link among files. The base -buffer may not itself be an indirect buffer. One base buffer may have -several "indirect children". + - Function: find-backup-file-name filename + This function computes the file name for a new backup file for + FILENAME. It may also propose certain existing backup files for + deletion. `find-backup-file-name' returns a list whose CAR is the + name for the new backup file and whose CDR is a list of backup + files whose deletion is proposed. - The text of the indirect buffer is always identical to the text of -its base buffer; changes made by editing either one are visible -immediately in the other. + Two variables, `kept-old-versions' and `kept-new-versions', + determine which backup versions should be kept. This function + keeps those versions by excluding them from the CDR of the value. + *Note Numbered Backups::. - But in all other respects, the indirect buffer and its base buffer -are completely separate. They have different names, different values of -point and mark, different narrowing, different markers and extents -(though inserting or deleting text in either buffer relocates the -markers and extents for both), different major modes, and different -local variables. Unlike in FSF Emacs, XEmacs indirect buffers do not -automatically share text properties among themselves and their base -buffer. + In this example, the value says that `~rms/foo.~5~' is the name to + use for the new backup file, and `~rms/foo.~3~' is an "excess" + version that the caller should consider deleting now. - An indirect buffer cannot visit a file, but its base buffer can. If -you try to save the indirect buffer, that actually works by saving the -base buffer. + (find-backup-file-name "~rms/foo") + => ("~rms/foo.~5~" "~rms/foo.~3~") - Killing an indirect buffer has no effect on its base buffer. Killing -the base buffer kills all its indirect children. + - Function: file-newest-backup filename + This function returns the name of the most recent backup file for + FILENAME, or `nil' if that file has no backup files. - - Command: make-indirect-buffer base-buffer name - This creates an indirect buffer named NAME whose base buffer is - BASE-BUFFER. The argument BASE-BUFFER may be a buffer or a string. + Some file comparison commands use this function so that they can + automatically compare a file with its most recent backup. - If BASE-BUFFER is an indirect buffer, its base buffer is used as - the base for the new buffer. - - (make-indirect-buffer "*scratch*" "indirect") - => # - - - Function: buffer-base-buffer &optional buffer - This function returns the base buffer of BUFFER. If BUFFER is not - indirect, the value is `nil'. Otherwise, the value is another - buffer, which is never an indirect buffer. If BUFFER is not - supplied, it defaults to the current buffer. + +File: lispref.info, Node: Auto-Saving, Next: Reverting, Prev: Backup Files, Up: Backups and Auto-Saving + +Auto-Saving +=========== + + XEmacs periodically saves all files that you are visiting; this is +called "auto-saving". Auto-saving prevents you from losing more than a +limited amount of work if the system crashes. By default, auto-saves +happen every 300 keystrokes, or after around 30 seconds of idle time. +*Note Auto-Save: (xemacs)Auto-Save, for information on auto-save for +users. Here we describe the functions used to implement auto-saving +and the variables that control them. + + - Variable: buffer-auto-save-file-name + This buffer-local variable is the name of the file used for + auto-saving the current buffer. It is `nil' if the buffer should + not be auto-saved. + + buffer-auto-save-file-name + => "/xcssun/users/rms/lewis/#files.texi#" + + - Command: auto-save-mode arg + When used interactively without an argument, this command is a + toggle switch: it turns on auto-saving of the current buffer if it + is off, and vice-versa. With an argument ARG, the command turns + auto-saving on if the value of ARG is `t', a nonempty list, or a + positive integer. Otherwise, it turns auto-saving off. + + - Function: auto-save-file-name-p filename + This function returns a non-`nil' value if FILENAME is a string + that could be the name of an auto-save file. It works based on + knowledge of the naming convention for auto-save files: a name that + begins and ends with hash marks (`#') is a possible auto-save file + name. The argument FILENAME should not contain a directory part. + + (make-auto-save-file-name) + => "/xcssun/users/rms/lewis/#files.texi#" + (auto-save-file-name-p "#files.texi#") + => 0 + (auto-save-file-name-p "files.texi") + => nil - (buffer-base-buffer (get-buffer "indirect")) - => # + The standard definition of this function is as follows: + + (defun auto-save-file-name-p (filename) + "Return non-nil if FILENAME can be yielded by..." + (string-match "^#.*#$" filename)) + + This function exists so that you can customize it if you wish to + change the naming convention for auto-save files. If you redefine + it, be sure to redefine the function `make-auto-save-file-name' + correspondingly. + + - Function: make-auto-save-file-name &optional filename + This function returns the file name to use for auto-saving the + current buffer. This is just the file name with hash marks (`#') + appended and prepended to it. This function does not look at the + variable `auto-save-visited-file-name' (described below); you + should check that before calling this function. + + (make-auto-save-file-name) + => "/xcssun/users/rms/lewis/#backup.texi#" + + The standard definition of this function is as follows: + + (defun make-auto-save-file-name () + "Return file name to use for auto-saves \ + of current buffer. + ..." + (if buffer-file-name + (concat + (file-name-directory buffer-file-name) + "#" + (file-name-nondirectory buffer-file-name) + "#") + (expand-file-name + (concat "#%" (buffer-name) "#")))) + + This exists as a separate function so that you can redefine it to + customize the naming convention for auto-save files. Be sure to + change `auto-save-file-name-p' in a corresponding way. + + - Variable: auto-save-visited-file-name + If this variable is non-`nil', XEmacs auto-saves buffers in the + files they are visiting. That is, the auto-save is done in the + same file that you are editing. Normally, this variable is `nil', + so auto-save files have distinct names that are created by + `make-auto-save-file-name'. + + When you change the value of this variable, the value does not take + effect until the next time auto-save mode is reenabled in any given + buffer. If auto-save mode is already enabled, auto-saves continue + to go in the same file name until `auto-save-mode' is called again. + + - Function: recent-auto-save-p + This function returns `t' if the current buffer has been + auto-saved since the last time it was read in or saved. + + - Function: set-buffer-auto-saved + This function marks the current buffer as auto-saved. The buffer + will not be auto-saved again until the buffer text is changed + again. The function returns `nil'. + + - User Option: auto-save-interval + The value of this variable is the number of characters that XEmacs + reads from the keyboard between auto-saves. Each time this many + more characters are read, auto-saving is done for all buffers in + which it is enabled. + + - User Option: auto-save-timeout + The value of this variable is the number of seconds of idle time + that should cause auto-saving. Each time the user pauses for this + long, XEmacs auto-saves any buffers that need it. (Actually, the + specified timeout is multiplied by a factor depending on the size + of the current buffer.) + + - Variable: auto-save-hook + This normal hook is run whenever an auto-save is about to happen. + + - User Option: auto-save-default + If this variable is non-`nil', buffers that are visiting files + have auto-saving enabled by default. Otherwise, they do not. + + - Command: do-auto-save &optional no-message current-only + This function auto-saves all buffers that need to be auto-saved. + It saves all buffers for which auto-saving is enabled and that + have been changed since the previous auto-save. + + Normally, if any buffers are auto-saved, a message that says + `Auto-saving...' is displayed in the echo area while auto-saving is + going on. However, if NO-MESSAGE is non-`nil', the message is + inhibited. + + If CURRENT-ONLY is non-`nil', only the current buffer is + auto-saved. + + - Function: delete-auto-save-file-if-necessary + This function deletes the current buffer's auto-save file if + `delete-auto-save-files' is non-`nil'. It is called every time a + buffer is saved. + + - Variable: delete-auto-save-files + This variable is used by the function + `delete-auto-save-file-if-necessary'. If it is non-`nil', Emacs + deletes auto-save files when a true save is done (in the visited + file). This saves disk space and unclutters your directory. + + - Function: rename-auto-save-file + This function adjusts the current buffer's auto-save file name if + the visited file name has changed. It also renames an existing + auto-save file. If the visited file name has not changed, this + function does nothing. + + - Variable: buffer-saved-size + The value of this buffer-local variable is the length of the + current buffer as of the last time it was read in, saved, or + auto-saved. This is used to detect a substantial decrease in + size, and turn off auto-saving in response. + + If it is -1, that means auto-saving is temporarily shut off in this + buffer due to a substantial deletion. Explicitly saving the buffer + stores a positive value in this variable, thus reenabling + auto-saving. Turning auto-save mode off or on also alters this + variable. + + - Variable: auto-save-list-file-name + This variable (if non-`nil') specifies a file for recording the + names of all the auto-save files. Each time XEmacs does + auto-saving, it writes two lines into this file for each buffer + that has auto-saving enabled. The first line gives the name of + the visited file (it's empty if the buffer has none), and the + second gives the name of the auto-save file. + + If XEmacs exits normally, it deletes this file. If XEmacs + crashes, you can look in the file to find all the auto-save files + that might contain work that was otherwise lost. The + `recover-session' command uses these files. + + The default name for this file is in your home directory and + starts with `.saves-'. It also contains the XEmacs process ID and + the host name. - - Function: buffer-indirect-children &optional buffer - This function returns a list of all indirect buffers whose base - buffer is BUFFER. If BUFFER is indirect, the return value will - always be nil; see `make-indirect-buffer'. If BUFFER is not - supplied, it defaults to the current buffer. + +File: lispref.info, Node: Reverting, Prev: Auto-Saving, Up: Backups and Auto-Saving + +Reverting +========= + + If you have made extensive changes to a file and then change your +mind about them, you can get rid of them by reading in the previous +version of the file with the `revert-buffer' command. *Note Reverting +a Buffer: (xemacs)Reverting. + + - Command: revert-buffer &optional check-auto-save noconfirm + preserve-modes + This command replaces the buffer text with the text of the visited + file on disk. This action undoes all changes since the file was + visited or saved. + + If the argument CHECK-AUTO-SAVE is non-`nil', and the latest + auto-save file is more recent than the visited file, + `revert-buffer' asks the user whether to use that instead. + Otherwise, it always uses the text of the visited file itself. + Interactively, CHECK-AUTO-SAVE is set if there is a numeric prefix + argument. + + Normally, `revert-buffer' asks for confirmation before it changes + the buffer; but if the argument NOCONFIRM is non-`nil', + `revert-buffer' does not ask for confirmation. + + Optional third argument PRESERVE-MODES non-`nil' means don't alter + the files modes. Normally we reinitialize them using + `normal-mode'. + + Reverting tries to preserve marker positions in the buffer by + using the replacement feature of `insert-file-contents'. If the + buffer contents and the file contents are identical before the + revert operation, reverting preserves all the markers. If they + are not identical, reverting does change the buffer; then it + preserves the markers in the unchanged text (if any) at the + beginning and end of the buffer. Preserving any additional + markers would be problematical. + + You can customize how `revert-buffer' does its work by setting these +variables--typically, as buffer-local variables. + + - Variable: revert-buffer-function + The value of this variable is the function to use to revert this + buffer. If non-`nil', it is called as a function with no + arguments to do the work of reverting. If the value is `nil', + reverting works the usual way. + + Modes such as Dired mode, in which the text being edited does not + consist of a file's contents but can be regenerated in some other + fashion, give this variable a buffer-local value that is a + function to regenerate the contents. + + - Variable: revert-buffer-insert-file-contents-function + The value of this variable, if non-`nil', is the function to use to + insert the updated contents when reverting this buffer. The + function receives two arguments: first the file name to use; + second, `t' if the user has asked to read the auto-save file. + + - Variable: before-revert-hook + This normal hook is run by `revert-buffer' before actually + inserting the modified contents--but only if + `revert-buffer-function' is `nil'. + + Font Lock mode uses this hook to record that the buffer contents + are no longer fontified. + + - Variable: after-revert-hook + This normal hook is run by `revert-buffer' after actually inserting + the modified contents--but only if `revert-buffer-function' is + `nil'. - (buffer-indirect-children (get-buffer "*scratch*")) - => (#) + Font Lock mode uses this hook to recompute the fonts for the + updated buffer contents.  -File: lispref.info, Node: Windows, Next: Frames, Prev: Buffers, Up: Top +File: lispref.info, Node: Buffers, Next: Windows, Prev: Backups and Auto-Saving, Up: Top -Windows +Buffers ******* - This chapter describes most of the functions and variables related to -Emacs windows. See *Note Display::, for information on how text is -displayed in windows. + A "buffer" is a Lisp object containing text to be edited. Buffers +are used to hold the contents of files that are being visited; there may +also be buffers that are not visiting files. While several buffers may +exist at one time, exactly one buffer is designated the "current +buffer" at any time. Most editing commands act on the contents of the +current buffer. Each buffer, including the current buffer, may or may +not be displayed in any window. * Menu: -* Basic Windows:: Basic information on using 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-lever functions for displaying a buffer - and choosing a window for it. -* Choosing Window:: How to choose a window for displaying a buffer. -* Window Point:: Each window has its own location of point. -* Window Start:: The display-start position controls which text - is on-screen in the window. -* Vertical Scrolling:: Moving text up and down in the window. -* Horizontal Scrolling:: Moving text sideways on the window. -* Size of Window:: Accessing the size of a window. -* Position of Window:: Accessing the position of a window. -* Resizing Windows:: Changing the size of a window. -* Window Configurations:: Saving and restoring the state of the screen. +* Buffer Basics:: What is a buffer? +* Current Buffer:: Designating a buffer as current + so primitives will access its contents. +* Buffer Names:: Accessing and changing buffer names. +* Buffer File Name:: The buffer file name indicates which file is visited. +* Buffer Modification:: A buffer is "modified" if it needs to be saved. +* Modification Time:: Determining whether the visited file was changed + ``behind XEmacs'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. +* Creating Buffers:: Functions that create buffers. +* Killing Buffers:: Buffers exist until explicitly killed. +* Indirect Buffers:: An indirect buffer shares text with some other buffer.  -File: lispref.info, Node: Basic Windows, Next: Splitting Windows, Up: Windows - -Basic Concepts of Emacs Windows -=============================== +File: lispref.info, Node: Buffer Basics, Next: Current Buffer, Up: Buffers + +Buffer Basics +============= + + A "buffer" is a Lisp object containing text to be edited. Buffers +are used to hold the contents of files that are being visited; there may +also be buffers that are not visiting files. While several buffers may +exist at one time, exactly one buffer is designated the "current +buffer" at any time. Most editing commands act on the contents of the +current buffer. Each buffer, including the current buffer, may or may +not be displayed in any windows. + + Buffers in Emacs editing are objects that have distinct names and +hold text that can be edited. Buffers appear to Lisp programs as a +special data type. You can think of the contents of a buffer as an +extendible string; insertions and deletions may occur in any part of +the buffer. *Note Text::. + + A Lisp buffer object contains numerous pieces of information. Some +of this information is directly accessible to the programmer through +variables, while other information is accessible only through +special-purpose functions. For example, the visited file name 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 +"buffer-local" variable bindings, which are variable values that are +effective only in a particular buffer. This feature allows each buffer +to override the values of certain variables. Most major modes override +variables such as `fill-column' or `comment-column' in this way. For +more information about buffer-local variables and functions related to +them, see *Note Buffer-Local Variables::. + + For functions and variables related to visiting files in buffers, see +*Note Visiting Files:: and *Note Saving Buffers::. For functions and +variables related to the display of buffers in windows, see *Note +Buffers and Windows::. + + - Function: bufferp object + This function returns `t' if OBJECT is a buffer, `nil' otherwise. - A "window" in XEmacs 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 XEmacs Lisp. It should be clear -from the context which is meant. - - XEmacs groups windows into frames. A frame represents an area of -screen available for XEmacs 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 -"selected within the frame". The frame's cursor appears in that -window. At ant time, one frame is the selected frame; and the window -selected within that frame is "the selected window". The selected -window's buffer is usually the current buffer (except when `set-buffer' -has been used). *Note 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, _even though there may still be references to -it_ from other Lisp objects. Restoring a saved window configuration is -the only way for a window no longer on the screen to come back to life. -(*Note Deleting Windows::.) - - Each window has the following attributes: - - * containing frame - - * window height - - * window width - - * window edges with respect to the frame or screen - - * the buffer it displays - - * position within the buffer at the upper left of the window - - * amount of horizontal scrolling, in columns - - * point - - * the mark - - * how recently the window was selected + +File: lispref.info, Node: Current Buffer, Next: Buffer Names, Prev: Buffer Basics, Up: Buffers + +The Current Buffer +================== + + There are, in general, many buffers in an Emacs session. At any +time, one of them is designated as the "current buffer". This is the +buffer in which most editing takes place, because most of the primitives +for examining or changing text in a buffer operate implicitly on the +current buffer (*note Text::). Normally the buffer that is displayed on +the screen in the selected window is the current buffer, but this is not +always so: a Lisp program can designate any buffer as current +temporarily in order to operate on its contents, without changing what +is displayed on the screen. + + The way to designate a current buffer in a Lisp program is by calling +`set-buffer'. The specified buffer remains current until a new one is +designated. + + When an editing command returns to the editor command loop, the +command loop designates the buffer displayed in the selected window as +current, to prevent confusion: the buffer that the cursor is in when +Emacs reads a command is the buffer that the command will apply to. +(*Note Command Loop::.) Therefore, `set-buffer' is not the way to +switch visibly to a different buffer so that the user can edit it. For +this, you must use the functions described in *Note Displaying +Buffers::. + + However, Lisp functions that change to a different current buffer +should not depend on the command loop to set it back afterwards. +Editing commands written in XEmacs Lisp can be called from other +programs as well as from the command loop. It is convenient for the +caller if the subroutine does not change which buffer is current +(unless, of course, that is the subroutine's purpose). Therefore, you +should normally use `set-buffer' within a `save-excursion' that will +restore the current buffer when your function is done (*note +Excursions::). Here is an example, the code for the command +`append-to-buffer' (with the documentation string abridged): + + (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)))) + +This function binds a local variable to the current buffer, and then +`save-excursion' records the values of point, the mark, and the +original buffer. Next, `set-buffer' makes another buffer current. +Finally, `insert-buffer-substring' copies the string from the original +current buffer to the new current buffer. + + If the buffer appended to happens to be displayed in some window, +the next redisplay will show how its text has changed. Otherwise, you +will not see the change immediately on the screen. The buffer becomes +current temporarily during the execution of the command, but this does +not cause it to be displayed. + + If you make local bindings (with `let' or function arguments) for a +variable that may also have buffer-local bindings, make sure that the +same buffer is current at the beginning and at the end of the local +binding's scope. Otherwise you might bind it in one buffer and unbind +it in another! There are two ways to do this. In simple cases, you may +see that nothing ever changes the current buffer within the scope of the +binding. Otherwise, use `save-excursion' to make sure that the buffer +current at the beginning is current again whenever the variable is +unbound. + + It is not reliable to change the current buffer back with +`set-buffer', because that won't do the job if a quit happens while the +wrong buffer is current. Here is what _not_ to do: + + (let (buffer-read-only + (obuf (current-buffer))) + (set-buffer ...) + ... + (set-buffer obuf)) + +Using `save-excursion', as shown below, handles quitting, errors, and +`throw', as well as ordinary evaluation. + + (let (buffer-read-only) + (save-excursion + (set-buffer ...) + ...)) + + - Function: current-buffer + This function returns the current buffer. + + (current-buffer) + => # + + - Function: set-buffer buffer-or-name + This function makes BUFFER-OR-NAME the current buffer. It does + not display the buffer in the currently selected window or in any + other window, so the user cannot necessarily see the buffer. But + Lisp programs can in any case work on it. + + BUFFER-OR-NAME must be a buffer or the name of an existing + buffer-else an error is signaled. This function returns the buffer + identified by BUFFER-OR-NAME. - 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. + +File: lispref.info, Node: Buffer Names, Next: Buffer File Name, Prev: Current Buffer, Up: Buffers - The meaning of "window" in XEmacs 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; XEmacs uses one or -more X windows as frames, and subdivides them into Emacs windows. When -you use XEmacs on a character-only terminal, XEmacs treats the whole -terminal screen as one frame. +Buffer Names +============ - Most window systems support arbitrarily located overlapping windows. -In contrast, Emacs windows are "tiled"; they never overlap, and -together they fill the whole screen or frame. Because of the way in -which XEmacs creates new windows and resizes them, you can't create -every conceivable tiling of windows on an Emacs frame. *Note Splitting -Windows::, and *Note Size of Window::. + Each buffer has a unique name, which is a string. Many of the +functions that work on buffers accept either a buffer or a buffer name +as an argument. Any argument called BUFFER-OR-NAME is of this sort, +and an error is signaled if it is neither a string nor a buffer. Any +argument called BUFFER must be an actual buffer object, not a name. - *Note Display::, for information on how the contents of the window's -buffer are displayed in the window. + Buffers that are ephemeral and generally uninteresting to the user +have names starting with a space, so that the `list-buffers' and +`buffer-menu' commands don't mention them. A name starting with space +also initially disables recording undo information; see *Note Undo::. - - Function: windowp object - This function returns `t' if OBJECT is a window. + - Function: buffer-name &optional buffer + This function returns the name of BUFFER as a string. If BUFFER + is not supplied, it defaults to the current buffer. - -File: lispref.info, Node: Splitting Windows, Next: Deleting Windows, Prev: Basic Windows, Up: Windows + If `buffer-name' returns `nil', it means that BUFFER has been + killed. *Note Killing Buffers::. -Splitting Windows -================= - - The functions described here are the primitives used to split a -window into two windows. Two higher level functions sometimes split a -window, but not always: `pop-to-buffer' and `display-buffer' (*note -Displaying Buffers::). - - The functions described here do not accept a buffer as an argument. -The two "halves" of the split window initially display the same buffer -previously visible in the window that was split. - - - Function: one-window-p &optional no-mini all-frames - This function returns non-`nil' if there is only one window. The - argument NO-MINI, if non-`nil', means don't count the minibuffer - even if it is active; otherwise, the minibuffer window is - included, if active, in the total number of windows which is - compared against one. - - The argument ALL-FRAME controls which set of windows are counted. - * If it is `nil' or omitted, then count only the selected - frame, plus the minibuffer it uses (which may be on another - frame). - - * If it is `t', then windows on all frames that currently exist - (including invisible and iconified frames) are counted. - - * If it is the symbol `visible', then windows on all visible - frames are counted. - - * If it is the number 0, then windows on all visible and - iconified frames are counted. - - * If it is any other value, then precisely the windows in - WINDOW's frame are counted, excluding the minibuffer in use - if it lies in some other frame. - - - Command: split-window &optional window size horizontal - This function splits WINDOW into two windows. The original window - WINDOW remains the selected window, but occupies only part of its - former screen area. The rest is occupied by a newly created - window which is returned as the value of this function. - - If HORIZONTAL is non-`nil', then WINDOW splits into two side by - side windows. The original window WINDOW keeps the leftmost SIZE - columns, and gives the rest of the columns to the new window. - Otherwise, it splits into windows one above the other, and WINDOW - keeps the upper SIZE lines and gives the rest of the lines to the - new window. The original window is therefore the left-hand or - upper of the two, and the new window is the right-hand or lower. - - If WINDOW is omitted or `nil', then the selected window is split. - If SIZE is omitted or `nil', then WINDOW is divided evenly into - two parts. (If there is an odd line, it is allocated to the new - window.) When `split-window' is called interactively, all its - arguments are `nil'. - - The following example starts with one window on a frame that is 50 - lines high by 80 columns wide; then the window is split. - - (setq w (selected-window)) - => # - (window-edges) ; Edges in order: - => (0 0 80 50) ; left-top-right-bottom + (buffer-name) + => "buffers.texi" - ;; Returns window created - (setq w2 (split-window w 15)) - => # - (window-edges w2) - => (0 15 80 50) ; Bottom window; - ; top is line 15 - (window-edges w) - => (0 0 80 15) ; Top window - - The frame looks like this: - - __________ - | | line 0 - | w | - |__________| - | | line 15 - | w2 | - |__________| - line 50 - column 0 column 80 - - Next, the top window is split horizontally: - - (setq w3 (split-window w 35 t)) - => # - (window-edges w3) - => (35 0 80 15) ; Left edge at column 35 - (window-edges w) - => (0 0 35 15) ; Right edge at column 35 - (window-edges w2) - => (0 15 80 50) ; Bottom window unchanged - - Now, the screen looks like this: - - column 35 - __________ - | | | line 0 - | w | w3 | - |___|______| - | | line 15 - | w2 | - |__________| - line 50 - column 0 column 80 - - Normally, Emacs indicates the border between two side-by-side - windows with a scroll bar (*note Scroll Bars: X Frame Properties.) - or `|' characters. The display table can specify alternative - border characters; see *Note Display Tables::. - - - Command: split-window-vertically &optional size - This function splits the selected window into two windows, one - above the other, leaving the selected window with SIZE lines. - - This function is simply an interface to `split-windows'. Here is - the complete function definition for it: - - (defun split-window-vertically (&optional arg) - "Split current window into two windows, one above the other." - (interactive "P") - (split-window nil (and arg (prefix-numeric-value arg)))) - - - Command: split-window-horizontally &optional size - This function splits the selected window into two windows - side-by-side, leaving the selected window with SIZE columns. - - This function is simply an interface to `split-windows'. Here is - the complete definition for `split-window-horizontally' (except for - part of the documentation string): - - (defun split-window-horizontally (&optional arg) - "Split selected window into two windows, side by side..." - (interactive "P") - (split-window nil (and arg (prefix-numeric-value arg)) t)) - - - Function: one-window-p &optional no-mini all-frames - This function returns non-`nil' if there is only one window. The - argument NO-MINI, if non-`nil', means don't count the minibuffer - even if it is active; otherwise, the minibuffer window is - included, if active, in the total number of windows, which is - compared against one. - - The argument ALL-FRAMES specifies which frames to consider. Here - are the possible values and their meanings: - - `nil' - Count the windows in the selected frame, plus the minibuffer - used by that frame even if it lies in some other frame. + (setq foo (get-buffer "temp")) + => # + (kill-buffer foo) + => nil + (buffer-name foo) + => nil + foo + => # + + - Command: rename-buffer newname &optional unique + This function renames the current buffer to NEWNAME. An error is + signaled if NEWNAME is not a string, or if there is already a + buffer with that name. The function returns `nil'. + + Ordinarily, `rename-buffer' signals an error if NEWNAME is already + in use. However, if UNIQUE is non-`nil', it modifies NEWNAME to + make a name that is not in use. Interactively, you can make + UNIQUE non-`nil' with a numeric prefix argument. + + One application of this command is to rename the `*shell*' buffer + to some other name, thus making it possible to create a second + shell buffer under the name `*shell*'. + + - Function: get-buffer buffer-or-name + This function returns the buffer named BUFFER-OR-NAME. If + BUFFER-OR-NAME is a string and there is no buffer with that name, + the value is `nil'. If BUFFER-OR-NAME is actually a buffer, it is + returned as given. (That is not very useful, so the argument is + usually a name.) For example: + + (setq b (get-buffer "lewis")) + => # + (get-buffer b) + => # + (get-buffer "Frazzle-nots") + => nil - `t' - Count all windows in all existing frames. + See also the function `get-buffer-create' in *Note Creating + Buffers::. - `visible' - Count all windows in all visible frames. + - Function: generate-new-buffer-name starting-name &optional ignore + This function returns a name that would be unique for a new + buffer--but does not create the buffer. It starts with + STARTING-NAME, and produces a name not currently in use for any + buffer by appending a number inside of `<...>'. - 0 - Count all windows in all visible or iconified frames. + If IGNORE is given, it specifies a name that is okay to use (if it + is in the sequence to be tried), even if a buffer with that name + exists. - anything else - Count precisely the windows in the selected frame, and no - others. + See the related function `generate-new-buffer' in *Note Creating + Buffers::.  -File: lispref.info, Node: Deleting Windows, Next: Selecting Windows, Prev: Splitting Windows, Up: Windows +File: lispref.info, Node: Buffer File Name, Next: Buffer Modification, Prev: Buffer Names, Up: Buffers -Deleting Windows +Buffer File Name ================ - A window remains visible on its frame unless you "delete" it by -calling certain functions that delete windows. A deleted window cannot -appear on the screen, but continues to exist as a Lisp object until -there are no references to it. There is no way to cancel the deletion -of a window aside from restoring a saved window configuration (*note -Window Configurations::). Restoring a window configuration also -deletes any windows that aren't part of that configuration. - - When you delete a window, the space it took up is given to one -adjacent sibling. (In Emacs version 18, the space was divided evenly -among all the siblings.) - - - Function: window-live-p window - This function returns `nil' if WINDOW is deleted, and `t' - otherwise. - - *Warning:* Erroneous information or fatal errors may result from - using a deleted window as if it were live. - - - Command: delete-window &optional window - This function removes WINDOW from the display. If WINDOW is - omitted, then the selected window is deleted. An error is signaled - if there is only one window when `delete-window' is called. - - This function returns `nil'. - - When `delete-window' is called interactively, WINDOW defaults to - the selected window. - - - Command: delete-other-windows &optional window - This function makes WINDOW the only window on its frame, by - deleting the other windows in that frame. If WINDOW is omitted or - `nil', then the selected window is used by default. - - The result is `nil'. - - - Command: delete-windows-on buffer &optional frame - This function deletes all windows showing BUFFER. If there are no - windows showing BUFFER, it does nothing. - - `delete-windows-on' operates frame by frame. If a frame has - several windows showing different buffers, then those showing - BUFFER are removed, and the others expand to fill the space. If - all windows in some frame are showing BUFFER (including the case - where there is only one window), then the frame reverts to having a - single window showing another buffer chosen with `other-buffer'. - *Note The Buffer List::. - - The argument FRAME controls which frames to operate on: - - * If it is `nil', operate on the selected frame. - - * If it is `t', operate on all frames. - - * If it is `visible', operate on all visible frames. - - * 0 If it is 0, operate on all visible or iconified frames. - - * If it is a frame, operate on that frame. - - This function always returns `nil'. + The "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 `nil'. Most of the time, the buffer name is the same as the +nondirectory part of the buffer file name, but the buffer file name and +the buffer name are distinct and can be set independently. *Note +Visiting Files::. + + - Function: buffer-file-name &optional buffer + This function returns the absolute file name of the file that + BUFFER is visiting. If BUFFER is not visiting any file, + `buffer-file-name' returns `nil'. If BUFFER is not supplied, it + defaults to the current buffer. + + (buffer-file-name (other-buffer)) + => "/usr/user/lewis/manual/files.texi" + + - Variable: buffer-file-name + This buffer-local variable contains the name of the file being + visited in the current buffer, or `nil' if it is not visiting a + file. It is a permanent local, unaffected by + `kill-local-variables'. + + buffer-file-name + => "/usr/user/lewis/manual/buffers.texi" + + It is risky to change this variable's value without doing various + other things. See the definition of `set-visited-file-name' in + `files.el'; some of the things done there, such as changing the + buffer name, are not strictly necessary, but others are essential + to avoid confusing XEmacs. + + - Variable: buffer-file-truename + This buffer-local variable holds the truename of the file visited + in the current buffer, or `nil' if no file is visited. It is a + permanent local, unaffected by `kill-local-variables'. *Note + Truenames::. + + - Variable: buffer-file-number + This buffer-local variable holds the file number and directory + device number of the file visited in the current buffer, or `nil' + if no file or a nonexistent file is visited. It is a permanent + local, unaffected by `kill-local-variables'. *Note Truenames::. + + The value is normally a list of the form `(FILENUM DEVNUM)'. This + pair of numbers uniquely identifies the file among all files + accessible on the system. See the function `file-attributes', in + *Note File Attributes::, for more information about them. + + - Function: get-file-buffer filename + This function returns the buffer visiting file FILENAME. If there + is no such buffer, it returns `nil'. The argument FILENAME, which + must be a string, is expanded (*note File Name Expansion::), then + compared against the visited file names of all live buffers. + + (get-file-buffer "buffers.texi") + => # + + 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. + + - Command: set-visited-file-name filename + If FILENAME is a non-empty string, this function changes the name + of the file visited in current buffer to FILENAME. (If the buffer + had no visited file, this gives it one.) The _next time_ the + buffer is saved it will go in the newly-specified file. This + command marks the buffer as modified, since it does not (as far as + XEmacs knows) match the contents of FILENAME, even if it matched + the former visited file. + + If FILENAME is `nil' or the empty string, that stands for "no + visited file". In this case, `set-visited-file-name' marks the + buffer as having no visited file. + + When the function `set-visited-file-name' is called interactively, + it prompts for FILENAME in the minibuffer. + + See also `clear-visited-file-modtime' and + `verify-visited-file-modtime' in *Note Buffer Modification::. + + - Variable: list-buffers-directory + This buffer-local variable records a string to display in a buffer + listing in place of the visited file name, for buffers that don't + have a visited file name. Dired buffers use this variable.  -File: lispref.info, Node: Selecting Windows, Next: Cyclic Window Ordering, Prev: Deleting Windows, Up: Windows - -Selecting Windows -================= - - When a window is selected, the buffer in the window becomes the -current buffer, and the cursor will appear in it. - - - Function: selected-window &optional device - This function returns the selected window. This is the window in - which the cursor appears and to which many commands apply. Each - separate device can have its own selected window, which is - remembered as focus changes from device to device. Optional - argument DEVICE specifies which device to return the selected - window for, and defaults to the selected device. - - - Function: select-window window &optional norecord - This function makes WINDOW the selected window. The cursor then - appears in WINDOW (on redisplay). The buffer being displayed in - WINDOW is immediately designated the current buffer. - - If optional argument NORECORD is non-`nil' then the global and - per-frame buffer orderings are not modified, as by the function - `record-buffer'. - - The return value is WINDOW. - - (setq w (next-window)) - (select-window w) - => # - - - Macro: save-selected-window forms... - This macro records the selected window, executes FORMS in - sequence, then restores the earlier selected window. It does not - save or restore anything about the sizes, arrangement or contents - of windows; therefore, if the FORMS change them, the changes are - permanent. +File: lispref.info, Node: Buffer Modification, Next: Modification Time, Prev: Buffer File Name, Up: Buffers - The following functions choose one of the windows on the screen, -offering various criteria for the choice. - - - Function: get-lru-window &optional frame - This function returns the window least recently "used" (that is, - selected). The selected window is always the most recently used - window. - - The selected window can be the least recently used window if it is - the only window. A newly created window becomes the least - recently used window until it is selected. A minibuffer window is - never a candidate. - - The argument FRAME controls which windows are considered. - - * If it is `nil', consider windows on the selected frame. - - * If it is `t', consider windows on all frames. - - * If it is `visible', consider windows on all visible frames. - - * If it is 0, consider windows on all visible or iconified - frames. - - * If it is a frame, consider windows on that frame. - - - Function: get-largest-window &optional frame - This function returns the window with the largest area (height - times width). If there are no side-by-side windows, then this is - the window with the most lines. A minibuffer window is never a - candidate. - - If there are two windows of the same size, then the function - returns the window that is first in the cyclic ordering of windows - (see following section), starting from the selected window. +Buffer Modification +=================== - The argument FRAME controls which set of windows are considered. - See `get-lru-window', above. + XEmacs keeps a flag called the "modified flag" for each buffer, to +record whether you have changed the text of the buffer. This flag is +set to `t' whenever you alter the contents of the buffer, and cleared +to `nil' when you save it. Thus, the flag shows whether there are +unsaved changes. The flag value is normally shown in the modeline +(*note Modeline Variables::), and controls saving (*note Saving +Buffers::) and auto-saving (*note Auto-Saving::). + + Some Lisp programs set the flag explicitly. For example, the +function `set-visited-file-name' sets the flag to `t', because the text +does not match the newly-visited file, even if it is unchanged from the +file formerly visited. + + The functions that modify the contents of buffers are described in +*Note Text::. + + - Function: buffer-modified-p &optional buffer + This function returns `t' if the buffer BUFFER has been modified + since it was last read in from a file or saved, or `nil' + otherwise. If BUFFER is not supplied, the current buffer is + tested. + + - Function: set-buffer-modified-p flag &optional buffer + This function marks BUFFER as modified if FLAG is non-`nil', or as + unmodified if the flag is `nil'. BUFFER defaults to the current + buffer. + + Another effect of calling this function is to cause unconditional + redisplay of the modeline for the current buffer. In fact, the + function `redraw-modeline' works by doing this: + + (set-buffer-modified-p (buffer-modified-p)) + + - Command: not-modified &optional arg + This command marks the current buffer as unmodified, and not + needing to be saved. (If ARG is non-`nil', the buffer is instead + marked as modified.) Don't use this function in programs, since it + prints a message in the echo area; use `set-buffer-modified-p' + (above) instead. + + - Function: buffer-modified-tick &optional buffer + This function returns BUFFER`s modification-count. This is a + counter that increments every time the buffer is modified. If + BUFFER is `nil' (or omitted), the current buffer is used.  -File: lispref.info, Node: Cyclic Window Ordering, Next: Buffers and Windows, Prev: Selecting Windows, Up: Windows - -Cyclic Ordering of Windows -========================== - - When you use the command `C-x o' (`other-window') to select the next -window, it moves through all the windows on the screen in a specific -cyclic order. For any given configuration of windows, this order never -varies. It is called the "cyclic ordering of windows". - - This ordering generally goes from top to bottom, and from left to -right. But it may go down first or go right first, depending on the -order in which the windows were split. - - If the first split was vertical (into windows one above each other), -and then the subwindows were split horizontally, then the ordering is -left to right in the top of the frame, and then left to right in the -next lower part of the frame, and so on. If the first split was -horizontal, the ordering is top to bottom in the left part, and so on. -In general, within each set of siblings at any level in the window tree, -the order is left to right, or top to bottom. - - - Function: next-window &optional window minibuf all-frames - This function returns the window following WINDOW in the cyclic - ordering of windows. This is the window that `C-x o' would select - if typed when WINDOW is selected. If WINDOW is the only window - visible, then this function returns WINDOW. If omitted, WINDOW - defaults to the selected window. - - The value of the argument MINIBUF determines whether the - minibuffer is included in the window order. Normally, when - MINIBUF is `nil', the minibuffer is included if it is currently - active; this is the behavior of `C-x o'. (The minibuffer window - is active while the minibuffer is in use. *Note Minibuffers::.) - - If MINIBUF is `t', then the cyclic ordering includes the - minibuffer window even if it is not active. - - If MINIBUF is neither `t' nor `nil', then the minibuffer window is - not included even if it is active. - - The argument ALL-FRAMES specifies which frames to consider. Here - are the possible values and their meanings: - - `nil' - Consider all the windows in WINDOW's frame, plus the - minibuffer used by that frame even if it lies in some other - frame. - - `t' - Consider all windows in all existing frames. - - `visible' - Consider all windows in all visible frames. (To get useful - results, you must ensure WINDOW is in a visible frame.) - - 0 - Consider all windows in all visible or iconified frames. - - anything else - Consider precisely the windows in WINDOW's frame, and no - others. +File: lispref.info, Node: Modification Time, Next: Read Only Buffers, Prev: Buffer Modification, Up: Buffers - This example assumes there are two windows, both displaying the - buffer `windows.texi': - - (selected-window) - => # - (next-window (selected-window)) - => # - (next-window (next-window (selected-window))) - => # - - - Function: previous-window &optional window minibuf all-frames - This function returns the window preceding WINDOW in the cyclic - ordering of windows. The other arguments specify which windows to - include in the cycle, as in `next-window'. - - - Command: other-window count &optional frame - This function selects the COUNTth following window in the cyclic - order. If count is negative, then it selects the -COUNTth - preceding window. It returns `nil'. - - In an interactive call, COUNT is the numeric prefix argument. - - The argument FRAME controls which set of windows are considered. - * If it is `nil' or omitted, then windows on the selected frame - are considered. - - * If it is a frame, then windows on that frame are considered. - - * If it is `t', then windows on all frames that currently exist - (including invisible and iconified frames) are considered. - - * If it is the symbol `visible', then windows on all visible - frames are considered. - - * If it is the number 0, then windows on all visible and - iconified frames are considered. - - * If it is any other value, then the behavior is undefined. - - - Function: walk-windows proc &optional minibuf all-frames - This function cycles through all windows, calling `proc' once for - each window with the window as its sole argument. +Comparison of Modification Time +=============================== - The optional arguments MINIBUF and ALL-FRAMES specify the set of - windows to include in the scan. See `next-window', above, for - details. + Suppose that you visit a file and make changes in its buffer, and +meanwhile the file itself is changed on disk. At this point, saving the +buffer would overwrite the changes in the file. Occasionally this may +be what you want, but usually it would lose valuable information. +XEmacs therefore checks the file's modification time using the functions +described below before saving the file. + + - Function: verify-visited-file-modtime buffer + This function compares what BUFFER has recorded for the + modification time of its visited file against the actual + modification time of the file as recorded by the operating system. + The two should be the same unless some other process has written + the file since XEmacs visited or saved it. + + The function returns `t' if the last actual modification time and + XEmacs's recorded modification time are the same, `nil' otherwise. + + - Function: clear-visited-file-modtime + This function clears out the record of the last modification time + of the file being visited by the current buffer. As a result, the + next attempt to save this buffer will not complain of a + discrepancy in file modification times. + + This function is called in `set-visited-file-name' and other + exceptional places where the usual test to avoid overwriting a + changed file should not be done. + + - Function: visited-file-modtime + This function returns the buffer's recorded last file modification + time, as a list of the form `(HIGH . LOW)'. (This is the same + format that `file-attributes' uses to return time values; see + *Note File Attributes::.) + + - Function: 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 TIME if TIME + is not `nil', and otherwise to the last modification time of the + visited file. + + If TIME is not `nil', it should have the form `(HIGH . LOW)' or + `(HIGH LOW)', in either case containing two integers, each of + which holds 16 bits of the time. + + 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 reason. + + - Function: ask-user-about-supersession-threat filename + This function is used to ask a user how to proceed after an + attempt to modify an obsolete buffer visiting file FILENAME. An + "obsolete buffer" is an unmodified buffer for which the associated + file on disk is newer than the last save-time of the buffer. This + means some other program has probably altered the file. + + 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 `file-supersession' error with data `(FILENAME)', in which + case the proposed buffer modification is not allowed. + + This function is called automatically by XEmacs on the proper + occasions. It exists so you can customize XEmacs by redefining it. + See the file `userlock.el' for the standard definition. + + See also the file locking mechanism in *Note File Locks::.  -File: lispref.info, Node: Buffers and Windows, Next: Displaying Buffers, Prev: Cyclic Window Ordering, Up: Windows - -Buffers and Windows -=================== - - This section describes low-level functions to examine windows or to -display buffers in windows in a precisely controlled fashion. *Note -Displaying Buffers::, for related functions that find a window to use -and specify a buffer for it. The functions described there are easier -to use than these, but they employ heuristics in choosing or creating a -window; use these functions when you need complete control. +File: lispref.info, Node: Read Only Buffers, Next: The Buffer List, Prev: Modification Time, Up: Buffers - - Function: set-window-buffer window buffer-or-name - This function makes WINDOW display BUFFER-OR-NAME as its contents. - It returns `nil'. - - (set-window-buffer (selected-window) "foo") - => nil +Read-Only Buffers +================= - - Function: window-buffer &optional window - This function returns the buffer that WINDOW is displaying. If - WINDOW is omitted, this function returns the buffer for the - selected window. + If a buffer is "read-only", then you cannot change its contents, +although you may change your view of the contents by scrolling and +narrowing. + + Read-only buffers are used in two kinds of situations: + + * A buffer visiting a write-protected file is normally read-only. + + Here, the purpose is to show the user that editing the buffer with + the aim of saving it in the file may be futile or undesirable. + The user who wants to change the buffer text despite this can do + so after clearing the read-only flag with `C-x C-q'. + + * 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 these modes bind `buffer-read-only' to + `nil' (with `let') or bind `inhibit-read-only' to `t' around the + places where they change the text. + + - Variable: buffer-read-only + This buffer-local variable specifies whether the buffer is + read-only. The buffer is read-only if this variable is non-`nil'. + + - Variable: inhibit-read-only + If this variable is non-`nil', then read-only buffers and read-only + characters may be modified. Read-only characters in a buffer are + those that have non-`nil' `read-only' properties (either text + properties or extent properties). *Note Extent Properties::, for + more information about text properties and extent properties. + + If `inhibit-read-only' is `t', all `read-only' character + properties have no effect. If `inhibit-read-only' is a list, then + `read-only' character properties have no effect if they are members + of the list (comparison is done with `eq'). + + - Command: toggle-read-only &optional arg + This command changes whether the current buffer is read-only. + Interactively, if a prefix arg ARG is supplied, set the current + buffer read only if and only if ARG is positive. + + This command is intended for interactive use only; don't use it in + programs. At any given point in a program, you should know + whether you want the read-only flag on or off; so you can set + `buffer-read-only' explicitly to the proper value, `t' or `nil'. + + - Function: barf-if-buffer-read-only &optional buffer start end + This function signals a `buffer-read-only' error if BUFFER is + read-only. BUFFER defaults to the current buffer. *Note + Interactive Call::, for another way to signal an error if the + current buffer is read-only. + + If optional argument START is non-`nil', all extents in the buffer + which overlap that part of the buffer are checked to ensure none + has a `read-only' property. (Extents that lie completely within the + range, however, are not checked.) END defaults to the value of + START. + + If START and END are equal, the range checked is [START, END] + (i.e. closed on both ends); otherwise, the range checked is + (START, END) \(open on both ends), except that extents that lie + completely within [START, END] are not checked. See + `extent-in-region-p' for a fuller discussion. - (window-buffer) - => # + +File: lispref.info, Node: The Buffer List, Next: Creating Buffers, Prev: Read Only Buffers, Up: Buffers - - Function: get-buffer-window buffer-or-name &optional frame - This function returns a window currently displaying - BUFFER-OR-NAME, or `nil' if there is none. If there are several - such windows, then the function returns the first one in the - cyclic ordering of windows, starting from the selected window. - *Note Cyclic Window Ordering::. +The Buffer List +=============== - The argument ALL-FRAMES controls which windows to consider. + The "buffer list" is a list of all live buffers. Creating a buffer +adds it to this list, and killing a buffer deletes it. The order of +the buffers in the list is based primarily on how recently each buffer +has been displayed in the selected window. Buffers move to the front +of the list when they are selected and to the end when they are buried. +Several functions, notably `other-buffer', use this ordering. A +buffer list displayed for the user also follows this order. - * If it is `nil', consider windows on the selected frame. + Every frame has its own order for the buffer list. Switching to a +new buffer inside of a particular frame changes the buffer list order +for that frame, but does not affect the buffer list order of any other +frames. In addition, there is a global, non-frame buffer list order +that is independent of the buffer list orders for any particular frame. - * If it is `t', consider windows on all frames. + Note that the different buffer lists all contain the same elements. +It is only the order of those elements that is different. - * If it is `visible', consider windows on all visible frames. + - Function: buffer-list &optional frame + This function returns a list of all buffers, including those whose + names begin with a space. The elements are actual buffers, not + their names. The order of the list is specific to FRAME, which + defaults to the current frame. If FRAME is `t', the global, + non-frame ordering is returned instead. - * If it is 0, consider windows on all visible or iconified - frames. + (buffer-list) + => (# + # # + # #) + + ;; Note that the name of the minibuffer + ;; begins with a space! + (mapcar (function buffer-name) (buffer-list)) + => ("buffers.texi" " *Minibuf-1*" + "buffer.c" "*Help*" "TAGS") - * If it is a frame, consider windows on that frame. + Buffers appear earlier in the list if they were current more + recently. - -File: lispref.info, Node: Displaying Buffers, Next: Choosing Window, Prev: Buffers and Windows, Up: Windows - -Displaying Buffers in Windows -============================= - - In this section we describe convenient functions that choose a window -automatically and use it to display a specified buffer. These functions -can also split an existing window in certain circumstances. We also -describe variables that parameterize the heuristics used for choosing a -window. *Note Buffers and Windows::, for low-level functions that give -you more precise control. - - Do not use the functions in this section in order to make a buffer -current so that a Lisp program can access or modify it; they are too -drastic for that purpose, since they change the display of buffers in -windows, which is gratuitous and will surprise the user. Instead, use -`set-buffer' (*note Current Buffer::) and `save-excursion' (*note -Excursions::), which designate buffers as current for programmed access -without affecting the display of buffers in windows. - - - Command: switch-to-buffer buffer-or-name &optional norecord - This function makes BUFFER-OR-NAME the current buffer, and also - displays the buffer in the selected window. This means that a - human can see the buffer and subsequent keyboard commands will - apply to it. Contrast this with `set-buffer', which makes - BUFFER-OR-NAME the current buffer but does not display it in the - selected window. *Note Current Buffer::. - - If BUFFER-OR-NAME does not identify an existing buffer, then a new - buffer by that name is created. The major mode for the new buffer - is set according to the variable `default-major-mode'. *Note Auto - Major Mode::. - - Normally the specified buffer is put at the front of the buffer - list. This affects the operation of `other-buffer'. However, if - NORECORD is non-`nil', this is not done. *Note The Buffer List::. - - The `switch-to-buffer' function is often used interactively, as - the binding of `C-x b'. It is also used frequently in programs. - It always returns `nil'. - - - Command: switch-to-buffer-other-window buffer-or-name - This function makes BUFFER-OR-NAME the current buffer and displays - it in a window not currently selected. It then selects that - window. The handling of the buffer is the same as in - `switch-to-buffer'. - - The currently selected window is absolutely never used to do the - job. If it is the only window, then it is split to make a - distinct window for this purpose. If the selected window is - already displaying the buffer, then it continues to do so, but - another window is nonetheless found to display it in as well. - - - Function: pop-to-buffer buffer-or-name &optional other-window - on-frame - This function makes BUFFER-OR-NAME the current buffer and switches - to it in some window, preferably not the window previously - selected. The "popped-to" window becomes the selected window - within its frame. - - If the variable `pop-up-frames' is non-`nil', `pop-to-buffer' - looks for a window in any visible frame already displaying the - buffer; if there is one, it returns that window and makes it be - selected within its frame. If there is none, it creates a new - frame and displays the buffer in it. - - If `pop-up-frames' is `nil', then `pop-to-buffer' operates - entirely within the selected frame. (If the selected frame has - just a minibuffer, `pop-to-buffer' operates within the most - recently selected frame that was not just a minibuffer.) - - If the variable `pop-up-windows' is non-`nil', windows may be - split to create a new window that is different from the original - window. For details, see *Note Choosing Window::. - - If OTHER-WINDOW is non-`nil', `pop-to-buffer' finds or creates - another window even if BUFFER-OR-NAME is already visible in the - selected window. Thus BUFFER-OR-NAME could end up displayed in - two windows. On the other hand, if BUFFER-OR-NAME is already - displayed in the selected window and OTHER-WINDOW is `nil', then - the selected window is considered sufficient display for - BUFFER-OR-NAME, so that nothing needs to be done. - - All the variables that affect `display-buffer' affect - `pop-to-buffer' as well. *Note Choosing Window::. - - If BUFFER-OR-NAME is a string that does not name an existing - buffer, a buffer by that name is created. The major mode for the - new buffer is set according to the variable `default-major-mode'. - *Note Auto Major Mode::. - - If ON-FRAME is non-`nil', it is the frame to pop to this buffer on. - - An example use of this function is found at the end of *Note - Filter Functions::. - - - Command: replace-buffer-in-windows buffer - This function replaces BUFFER with some other buffer in all - windows displaying it. The other buffer used is chosen with - `other-buffer'. In the usual applications of this function, you - don't care which other buffer is used; you just want to make sure - that BUFFER is no longer displayed. - - This function returns `nil'. + This list is a copy of a list used inside XEmacs; modifying it has + no effect on the buffers. - -File: lispref.info, Node: Choosing Window, Next: Window Point, Prev: Displaying Buffers, Up: Windows + - Function: other-buffer &optional buffer-or-name frame visible-ok + This function returns the first buffer in the buffer list other + than BUFFER-OR-NAME, in FRAME's ordering for the buffer list. + (FRAME defaults to the current frame. If FRAME is `t', then the + global, non-frame ordering is used.) Usually this is the buffer + most recently shown in the selected window, aside from + BUFFER-OR-NAME. Buffers are moved to the front of the list when + they are selected and to the end when they are buried. Buffers + whose names start with a space are not considered. -Choosing a Window for Display -============================= + If BUFFER-OR-NAME is not supplied (or if it is not a buffer), then + `other-buffer' returns the first buffer on the buffer list that is + not visible in any window in a visible frame. - This section describes the basic facility that chooses a window to -display a buffer in--`display-buffer'. All the higher-level functions -and commands use this subroutine. Here we describe how to use -`display-buffer' and how to customize it. + If the selected frame has a non-`nil' `buffer-predicate' property, + then `other-buffer' uses that predicate to decide which buffers to + consider. It calls the predicate once for each buffer, and if the + value is `nil', that buffer is ignored. *Note X Frame + Properties::. - - Command: display-buffer buffer-or-name &optional not-this-window - This command makes BUFFER-OR-NAME appear in some window, like - `pop-to-buffer', but it does not select that window and does not - make the buffer current. The identity of the selected window is - unaltered by this function. + If VISIBLE-OK is `nil', `other-buffer' avoids returning a buffer + visible in any window on any visible frame, except as a last + resort. If VISIBLE-OK is non-`nil', then it does not matter + whether a buffer is displayed somewhere or not. - If NOT-THIS-WINDOW is non-`nil', it means to display the specified - buffer in a window other than the selected one, even if it is - already on display in the selected window. This can cause the - buffer to appear in two windows at once. Otherwise, if - BUFFER-OR-NAME is already being displayed in any window, that is - good enough, so this function does nothing. + If no suitable buffer exists, the buffer `*scratch*' is returned + (and created, if necessary). - `display-buffer' returns the window chosen to display - BUFFER-OR-NAME. + Note that in FSF Emacs 19, there is no FRAME argument, and + VISIBLE-OK is the second argument instead of the third. - Precisely how `display-buffer' finds or creates a window depends on - the variables described below. + - Command: list-buffers &optional files-only + This function displays a listing of the names of existing buffers. + It clears the buffer `*Buffer List*', then inserts the listing + into that buffer and displays it in a window. `list-buffers' is + intended for interactive use, and is described fully in `The XEmacs + Reference Manual'. It returns `nil'. - A window can be marked as "dedicated" to a particular buffer. Then -XEmacs will not automatically change which buffer appears in the -window, such as `display-buffer' might normally do. + - Command: bury-buffer &optional buffer-or-name before + This function puts BUFFER-OR-NAME at the end of the buffer list + without changing the order of any of the other buffers on the list. + This buffer therefore becomes the least desirable candidate for + `other-buffer' to return. - - Function: window-dedicated-p window - This function returns WINDOW's dedicated object, usually `t' or - `nil'. + If BUFFER-OR-NAME is `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 + `other-buffer') in the selected window. But if the buffer is + displayed in some other window, it remains displayed there. - - Function: set-window-buffer-dedicated window buffer - This function makes WINDOW display BUFFER and be dedicated to that - buffer. Then XEmacs will not automatically change which buffer - appears in WINDOW. If BUFFER is `nil', this function makes WINDOW - not be dedicated (but doesn't change which buffer appears in it - currently). - - - User Option: pop-up-windows - This variable controls whether `display-buffer' makes new windows. - If it is non-`nil' and there is only one window, then that window - is split. If it is `nil', then `display-buffer' does not split - the single window, but uses it whole. - - - User Option: split-height-threshold - This variable determines when `display-buffer' may split a window, - if there are multiple windows. `display-buffer' always splits the - largest window if it has at least this many lines. If the largest - window is not this tall, it is split only if it is the sole window - and `pop-up-windows' is non-`nil'. - - - User Option: pop-up-frames - This variable controls whether `display-buffer' makes new frames. - If it is non-`nil', `display-buffer' looks for an existing window - already displaying the desired buffer, on any visible frame. If - it finds one, it returns that window. Otherwise it makes a new - frame. The variables `pop-up-windows' and - `split-height-threshold' do not matter if `pop-up-frames' is - non-`nil'. - - If `pop-up-frames' is `nil', then `display-buffer' either splits a - window or reuses one. - - *Note Frames::, for more information. - - - Variable: pop-up-frame-function - This variable specifies how to make a new frame if `pop-up-frames' - is non-`nil'. - - Its value should be a function of no arguments. When - `display-buffer' makes a new frame, it does so by calling that - function, which should return a frame. The default value of the - variable is a function that creates a frame using properties from - `pop-up-frame-plist'. - - - Variable: pop-up-frame-plist - This variable holds a plist specifying frame properties used when - `display-buffer' makes a new frame. *Note Frame Properties::, for - more information about frame properties. - - - Variable: special-display-buffer-names - A list of buffer names for buffers that should be displayed - specially. If the buffer's name is in this list, `display-buffer' - handles the buffer specially. - - By default, special display means to give the buffer a dedicated - frame. - - If an element is a list, instead of a string, then the CAR of the - list is the buffer name, and the rest of the list says how to - create the frame. There are two possibilities for the rest of the - list. It can be a plist, specifying frame properties, or it can - contain a function and arguments to give to it. (The function's - first argument is always the buffer to be displayed; the arguments - from the list come after that.) - - - Variable: special-display-regexps - A list of regular expressions that specify buffers that should be - displayed specially. If the buffer's name matches any of the - regular expressions in this list, `display-buffer' handles the - buffer specially. - - By default, special display means to give the buffer a dedicated - frame. - - If an element is a list, instead of a string, then the CAR of the - list is the regular expression, and the rest of the list says how - to create the frame. See above, under - `special-display-buffer-names'. - - - Variable: special-display-function - This variable holds the function to call to display a buffer - specially. It receives the buffer as an argument, and should - return the window in which it is displayed. - - The default value of this variable is - `special-display-popup-frame'. - - - Function: special-display-popup-frame buffer - This function makes BUFFER visible in a frame of its own. If - BUFFER is already displayed in a window in some frame, it makes - the frame visible and raises it, to use that window. Otherwise, it - creates a frame that will be dedicated to BUFFER. - - This function uses an existing window displaying BUFFER whether or - not it is in a frame of its own; but if you set up the above - variables in your init file, before BUFFER was created, then - presumably the window was previously made by this function. - - - User Option: special-display-frame-plist - This variable holds frame properties for - `special-display-popup-frame' to use when it creates a frame. - - - Variable: same-window-buffer-names - A list of buffer names for buffers that should be displayed in the - selected window. If the buffer's name is in this list, - `display-buffer' handles the buffer by switching to it in the - selected window. - - - Variable: same-window-regexps - A list of regular expressions that specify buffers that should be - displayed in the selected window. If the buffer's name matches - any of the regular expressions in this list, `display-buffer' - handles the buffer by switching to it in the selected window. - - - Variable: display-buffer-function - This variable is the most flexible way to customize the behavior of - `display-buffer'. If it is non-`nil', it should be a function - that `display-buffer' calls to do the work. The function should - accept two arguments, the same two arguments that `display-buffer' - received. It should choose or create a window, display the - specified buffer, and then return the window. - - This hook takes precedence over all the other options and hooks - described above. - - A window can be marked as "dedicated" to its buffer. Then -`display-buffer' does not try to use that window. - - - Function: window-dedicated-p window - This function returns `t' if WINDOW is marked as dedicated; - otherwise `nil'. - - - Function: set-window-dedicated-p window flag - This function marks WINDOW as dedicated if FLAG is non-`nil', and - nondedicated otherwise. + If you wish to replace a buffer in all the windows that display + it, use `replace-buffer-in-windows'. *Note Buffers and Windows::.