-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
Foundation instead of in the original English.
\1f
+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'.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
+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.
+
+\1f
File: lispref.info, Node: Buffer Basics, Next: Current Buffer, Up: Buffers
Buffer Basics
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.
\1f
File: lispref.info, Node: Buffer Names, Next: Buffer File Name, Prev: Current Buffer, Up: Buffers
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"))
=> #<buffer lewis>
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
`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.
\1f
File: lispref.info, Node: The Buffer List, Next: Creating Buffers, Prev: Read Only Buffers, Up: Buffers
(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.
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
If you wish to replace a buffer in all the windows that display
it, use `replace-buffer-in-windows'. *Note Buffers and Windows::.
-\1f
-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")
- => #<buffer 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 `<N>' 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")
- => #<buffer bar>
- (generate-new-buffer "bar")
- => #<buffer bar<2>>
- (generate-new-buffer "bar")
- => #<buffer bar<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::.
-
- See the related function `generate-new-buffer-name' in *Note
- Buffer Names::.
-
-\1f
-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::.
-
-\1f
-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")
- => #<buffer "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"))
- => #<buffer "*scratch*">
-
- - 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*"))
- => (#<buffer "indirect">)
-
-\1f
-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.
-
-\1f
-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.
-
-\1f
-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 8 on windows.texi>
- (window-edges) ; Edges in order:
- => (0 0 80 50) ; left-top-right-bottom
-
- ;; Returns window created
- (setq w2 (split-window w 15))
- => #<window 28 on windows.texi>
- (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 32 on windows.texi>
- (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.
-
-\1f
-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'.
-
projects / chise / xemacs-chise.git / blobdiff