X-Git-Url: http://git.chise.org/gitweb/?a=blobdiff_plain;f=info%2Flispref.info-25;h=02833772944e0d000e8d554c071560fc1cba9e88;hb=b5f26301ee1ad7dbc9ad1c22e5b8564b5161d9ad;hp=4c3e6d686123af879d9a867872ee3c27777b1223;hpb=e5cd8d4ed475af329be5df9627a53edd584fd3de;p=chise%2Fxemacs-chise.git diff --git a/info/lispref.info-25 b/info/lispref.info-25 index 4c3e6d6..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,6 +50,491 @@ may be included in a translation approved by the Free Software Foundation instead of in the original English.  +File: lispref.info, Node: Rename or Copy, Next: Numbered Backups, Prev: Making Backups, Up: Backup Files + +Backup by Renaming or by Copying? +--------------------------------- + + There are two ways that XEmacs can make a backup file: + + * 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. + + * 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. + + The first method, renaming, is the default. + + 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::. + + - Variable: backup-by-copying + If this variable is non-`nil', XEmacs always makes backup files by + copying. + + 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. + + - Variable: backup-by-copying-when-linked + If this variable is non-`nil', XEmacs makes backups by copying for + files with multiple names (hard links). + + This variable is significant only if `backup-by-copying' is `nil', + since copying is always used when that variable is non-`nil'. + + - 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. + + 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. + + This variable is significant only if `backup-by-copying' is `nil', + since copying is always used when that variable is non-`nil'. + + +File: lispref.info, Node: Numbered Backups, Next: Backup Names, Prev: Rename or Copy, Up: Backup Files + +Making and Deleting Numbered Backup Files +----------------------------------------- + + 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. + + - User Option: version-control + This variable controls whether to make a single non-numbered backup + file or multiple numbered backups. + + `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: Backup Names, Prev: Numbered Backups, Up: Backup Files + +Naming Backup Files +------------------- + + 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. + + - 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. + + (backup-file-name-p "foo") + => nil + (backup-file-name-p "foo~") + => 3 + + The standard definition of this function is as follows: + + (defun backup-file-name-p (file) + "Return non-nil if FILE is a backup file \ + name (numeric or not)..." + (string-match "~$" file)) + + 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.) + + This simple expression is placed in a separate function to make it + easy to redefine for customization. + + - 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. + + The standard definition of this function is as follows: + + (defun make-backup-file-name (file) + "Create the non-numeric backup file name for FILE. + ..." + (concat file "~")) + + 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: + + (defun make-backup-file-name (filename) + (concat "." filename "~")) + + (make-backup-file-name "backups.texi") + => ".backups.texi~" + + - 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. + + 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::. + + 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. + + (find-backup-file-name "~rms/foo") + => ("~rms/foo.~5~" "~rms/foo.~3~") + + - 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. + + Some file comparison commands use this function so that they can + automatically compare a file with its most recent backup. + + +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 + + 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. + + +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'. + + Font Lock mode uses this hook to recompute the fonts for the + updated buffer contents. + + +File: lispref.info, Node: Buffers, Next: Windows, Prev: Backups and Auto-Saving, Up: Top + +Buffers +******* + + 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: + +* 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: Buffer Basics, Next: Current Buffer, Up: Buffers Buffer Basics @@ -66,7 +551,7 @@ 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 -extendable string; insertions and deletions may occur in any part of +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 @@ -193,9 +678,9 @@ Using `save-excursion', as shown below, handles quitting, errors, and other window, so the user cannot necessarily see the buffer. But Lisp programs can in any case work on it. - This function returns the buffer identified by BUFFER-OR-NAME. An - error is signaled if BUFFER-OR-NAME does not identify an existing - buffer. + 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.  File: lispref.info, Node: Buffer Names, Next: Buffer File Name, Prev: Current Buffer, Up: Buffers @@ -248,11 +733,11 @@ also initially disables recording undo information; see *Note Undo::. shell buffer under the name `*shell*'. - Function: get-buffer buffer-or-name - This function returns the buffer specified by BUFFER-OR-NAME. If + 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 a buffer, it is returned - as given. (That is not very useful, so the argument is usually a - name.) For example: + 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")) => # @@ -396,9 +881,10 @@ file formerly visited. otherwise. If BUFFER is not supplied, the current buffer is tested. - - Function: set-buffer-modified-p flag - This function marks the current buffer as modified if FLAG is - non-`nil', or as unmodified if the flag is `nil'. + - 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 @@ -531,17 +1017,33 @@ narrowing. `read-only' character properties have no effect if they are members of the list (comparison is done with `eq'). - - Command: toggle-read-only - This command changes whether the current buffer is read-only. It - is intended for interactive use; 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 - This function signals a `buffer-read-only' error if the current - buffer is read-only. *Note Interactive Call::, for another way to - signal an error if the current buffer is read-only. + - 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.  File: lispref.info, Node: The Buffer List, Next: Creating Buffers, Prev: Read Only Buffers, Up: Buffers @@ -619,8 +1121,7 @@ It is only the order of those elements that is different. (and created, if necessary). 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. + VISIBLE-OK is the second argument instead of the third. - Command: list-buffers &optional files-only This function displays a listing of the names of existing buffers. @@ -629,7 +1130,7 @@ It is only the order of those elements that is different. intended for interactive use, and is described fully in `The XEmacs Reference Manual'. It returns `nil'. - - Command: bury-buffer &optional buffer-or-name + - 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 @@ -644,548 +1145,3 @@ It is only the order of those elements that is different. If you wish to replace a buffer in all the windows that display it, use `replace-buffer-in-windows'. *Note Buffers and Windows::. - -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. - - 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::). - - - 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. - - An error is signaled if NAME is not a string. - - (get-buffer-create "foo") - => # - - 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: 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. - - An error is signaled if NAME is not a string. - - (generate-new-buffer "bar") - => # - (generate-new-buffer "bar") - => #> - (generate-new-buffer "bar") - => #> - - 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::. - - See the related function `generate-new-buffer-name' in *Note - Buffer Names::. - - -File: lispref.info, Node: Killing Buffers, Next: Indirect Buffers, Prev: Creating Buffers, Up: Buffers - -Killing Buffers -=============== - - "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 ---------- - - => 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 -================ - - 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". - - 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. - - 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. - - 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. - - Killing an indirect buffer has no effect on its base buffer. Killing -the base buffer kills all its indirect children. - - - 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. - - 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. - - (buffer-base-buffer (get-buffer "indirect")) - => # - - - 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. - - (buffer-indirect-children (get-buffer "*scratch*")) - => (#) - - -File: lispref.info, Node: Windows, Next: Frames, Prev: Buffers, Up: Top - -Windows -******* - - 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. - -* 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. - - -File: lispref.info, Node: Basic Windows, Next: Splitting Windows, Up: Windows - -Basic Concepts of Emacs Windows -=============================== - - 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 - - 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. - - 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. - - 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::. - - *Note Display::, for information on how the contents of the window's -buffer are displayed in the window. - - - Function: windowp object - This function returns `t' if OBJECT is a window. - - -File: lispref.info, Node: Splitting Windows, Next: Deleting Windows, Prev: Basic Windows, Up: Windows - -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 - - ;; 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. - - `t' - Count all windows in all existing frames. - - `visible' - Count all windows in all visible frames. - - 0 - Count all windows in all visible or iconified frames. - - anything else - Count precisely the windows in the selected frame, and no - others. - - -File: lispref.info, Node: Deleting Windows, Next: Selecting Windows, Prev: Splitting Windows, Up: Windows - -Deleting Windows -================ - - 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'. -