-This is ../info/lispref.info, produced by makeinfo version 4.0 from
+This is ../info/lispref.info, produced by makeinfo version 4.6 from
lispref/lispref.texi.
INFO-DIR-SECTION XEmacs Editor
Foundation instead of in the original English.
\1f
-File: lispref.info, Node: String Basics, Next: Predicates for Strings, Up: Strings and Characters
+File: lispref.info, Node: Create/Delete Dirs, Next: Magic File Names, Prev: Contents of Directories, Up: Files
-String and Character Basics
-===========================
+Creating and Deleting Directories
+=================================
- Strings in XEmacs Lisp are arrays that contain an ordered sequence of
-characters. Characters are their own primitive object type in XEmacs
-20. However, in XEmacs 19, characters are represented in XEmacs Lisp as
-integers; whether an integer was intended as a character or not is
-determined only by how it is used. *Note Character Type::.
-
- The length of a string (like any array) is fixed and independent of
-the string contents, and cannot be altered. Strings in Lisp are _not_
-terminated by a distinguished character code. (By contrast, strings in
-C are terminated by a character with ASCII code 0.) This means that
-any character, including the null character (ASCII code 0), is a valid
-element of a string.
-
- Since strings are considered arrays, you can operate on them with the
-general array functions. (*Note Sequences Arrays Vectors::.) For
-example, you can access or change individual characters in a string
-using the functions `aref' and `aset' (*note Array Functions::).
-
- Strings use an efficient representation for storing the characters
-in them, and thus take up much less memory than a vector of the same
-length.
-
- Sometimes you will see strings used to hold key sequences. This
-exists for backward compatibility with Emacs 18, but should _not_ be
-used in new code, since many key chords can't be represented at all and
-others (in particular meta key chords) are confused with accented
-characters.
-
- Strings are useful for holding regular expressions. You can also
-match regular expressions against strings (*note Regexp Search::). The
-functions `match-string' (*note Simple Match Data::) and
-`replace-match' (*note Replacing Match::) are useful for decomposing
-and modifying strings based on regular expression matching.
-
- Like a buffer, a string can contain extents in it. These extents are
-created when a function such as `buffer-substring' is called on a
-region with duplicable extents in it. When the string is inserted into
-a buffer, the extents are inserted along with it. *Note Duplicable
-Extents::.
-
- *Note Text::, for information about functions that display strings or
-copy them into buffers. *Note Character Type::, and *Note String
-Type::, for information about the syntax of characters and strings.
-
-\1f
-File: lispref.info, Node: Predicates for Strings, Next: Creating Strings, Prev: String Basics, Up: Strings and Characters
-
-The Predicates for Strings
-==========================
+Most XEmacs Lisp file-manipulation functions get errors when used on
+files that are directories. For example, you cannot delete a directory
+with `delete-file'. These special functions exist to create and delete
+directories.
- For more information about general sequence and array predicates,
-see *Note Sequences Arrays Vectors::, and *Note Arrays::.
+ - Command: make-directory dirname &optional parents
+ This function creates a directory named DIRNAME. Interactively,
+ the default choice of directory to create is the current default
+ directory for file names. That is useful when you have visited a
+ file in a nonexistent directory.
- - Function: stringp object
- This function returns `t' if OBJECT is a string, `nil' otherwise.
+ Non-interactively, optional argument PARENTS says whether to
+ create parent directories if they don't exist. (Interactively, this
+ always happens.)
- - Function: char-or-string-p object
- This function returns `t' if OBJECT is a string or a character,
- `nil' otherwise.
+ - Command: delete-directory dirname
+ This function deletes the directory named DIRNAME. The function
+ `delete-file' does not work for files that are directories; you
+ must use `delete-directory' in that case.
+
+\1f
+File: lispref.info, Node: Magic File Names, Next: Partial Files, Prev: Create/Delete Dirs, Up: Files
+
+Making Certain File Names "Magic"
+=================================
+
+You can implement special handling for certain file names. This is
+called making those names "magic". You must supply a regular
+expression to define the class of names (all those that match the
+regular expression), plus a handler that implements all the primitive
+XEmacs file operations for file names that do match.
+
+ The variable `file-name-handler-alist' holds a list of handlers,
+together with regular expressions that determine when to apply each
+handler. Each element has this form:
+
+ (REGEXP . HANDLER)
+
+All the XEmacs primitives for file access and file name transformation
+check the given file name against `file-name-handler-alist'. If the
+file name matches REGEXP, the primitives handle that file by calling
+HANDLER.
+
+ The first argument given to HANDLER is the name of the primitive;
+the remaining arguments are the arguments that were passed to that
+operation. (The first of these arguments is typically the file name
+itself.) For example, if you do this:
+
+ (file-exists-p FILENAME)
+
+and FILENAME has handler HANDLER, then HANDLER is called like this:
+
+ (funcall HANDLER 'file-exists-p FILENAME)
+
+ Here are the operations that a magic file name handler gets to
+handle:
+
+`add-name-to-file', `copy-file', `delete-directory', `delete-file',
+`diff-latest-backup-file', `directory-file-name', `directory-files',
+`dired-compress-file', `dired-uncache', `expand-file-name',
+`file-accessible-directory-p', `file-attributes', `file-directory-p',
+`file-executable-p', `file-exists-p', `file-local-copy', `file-modes',
+`file-name-all-completions', `file-name-as-directory',
+`file-name-completion', `file-name-directory', `file-name-nondirectory',
+`file-name-sans-versions', `file-newer-than-file-p', `file-readable-p',
+`file-regular-p', `file-symlink-p', `file-truename', `file-writable-p',
+`get-file-buffer', `insert-directory', `insert-file-contents', `load',
+`make-directory', `make-symbolic-link', `rename-file', `set-file-modes',
+`set-visited-file-modtime', `unhandled-file-name-directory',
+`verify-visited-file-modtime', `write-region'.
+
+ Handlers for `insert-file-contents' typically need to clear the
+buffer's modified flag, with `(set-buffer-modified-p nil)', if the
+VISIT argument is non-`nil'. This also has the effect of unlocking the
+buffer if it is locked.
+
+ The handler function must handle all of the above operations, and
+possibly others to be added in the future. It need not implement all
+these operations itself--when it has nothing special to do for a
+certain operation, it can reinvoke the primitive, to handle the
+operation "in the usual way". It should always reinvoke the primitive
+for an operation it does not recognize. Here's one way to do this:
+
+ (defun my-file-handler (operation &rest args)
+ ;; First check for the specific operations
+ ;; that we have special handling for.
+ (cond ((eq operation 'insert-file-contents) ...)
+ ((eq operation 'write-region) ...)
+ ...
+ ;; Handle any operation we don't know about.
+ (t (let ((inhibit-file-name-handlers
+ (cons 'my-file-handler
+ (and (eq inhibit-file-name-operation operation)
+ inhibit-file-name-handlers)))
+ (inhibit-file-name-operation operation))
+ (apply operation args)))))
+
+ When a handler function decides to call the ordinary Emacs primitive
+for the operation at hand, it needs to prevent the primitive from
+calling the same handler once again, thus leading to an infinite
+recursion. The example above shows how to do this, with the variables
+`inhibit-file-name-handlers' and `inhibit-file-name-operation'. Be
+careful to use them exactly as shown above; the details are crucial for
+proper behavior in the case of multiple handlers, and for operations
+that have two file names that may each have handlers.
+
+ - Variable: inhibit-file-name-handlers
+ This variable holds a list of handlers whose use is presently
+ inhibited for a certain operation.
+
+ - Variable: inhibit-file-name-operation
+ The operation for which certain handlers are presently inhibited.
+
+ - Function: find-file-name-handler filename &optional operation
+ This function returns the handler function for file name FILENAME,
+ or `nil' if there is none. The argument OPERATION should be the
+ operation to be performed on the file--the value you will pass to
+ the handler as its first argument when you call it. The operation
+ is needed for comparison with `inhibit-file-name-operation'.
+
+ - Function: file-local-copy filename
+ This function copies file FILENAME to an ordinary non-magic file,
+ if it isn't one already.
+
+ If FILENAME specifies a "magic" file name, which programs outside
+ Emacs cannot directly read or write, this copies the contents to
+ an ordinary file and returns that file's name.
+
+ If FILENAME is an ordinary file name, not magic, then this function
+ does nothing and returns `nil'.
+
+ - Function: unhandled-file-name-directory filename
+ This function returns the name of a directory that is not magic.
+ It uses the directory part of FILENAME if that is not magic.
+ Otherwise, it asks the handler what to do.
+
+ This is useful for running a subprocess; every subprocess must
+ have a non-magic directory to serve as its current directory, and
+ this function is a good way to come up with one.
+
+\1f
+File: lispref.info, Node: Partial Files, Next: Format Conversion, Prev: Magic File Names, Up: Files
+
+Partial Files
+=============
+
+* Menu:
+
+* Intro to Partial Files::
+* Creating a Partial File::
+* Detached Partial Files::
+
+\1f
+File: lispref.info, Node: Intro to Partial Files, Next: Creating a Partial File, Up: Partial Files
+
+Intro to Partial Files
+----------------------
+
+A "partial file" is a section of a buffer (called the "master buffer")
+that is placed in its own buffer and treated as its own file. Changes
+made to the partial file are not reflected in the master buffer until
+the partial file is "saved" using the standard buffer save commands.
+Partial files can be "reverted" (from the master buffer) just like
+normal files. When a file part is active on a master buffer, that
+section of the master buffer is marked as read-only. Two file parts on
+the same master buffer are not allowed to overlap. Partial file
+buffers are indicated by the words `File Part' in the modeline.
+
+ The master buffer knows about all the partial files that are active
+on it, and thus killing or reverting the master buffer will be handled
+properly. When the master buffer is saved, if there are any unsaved
+partial files active on it then the user will be given the opportunity
+to first save these files.
+
+ When a partial file buffer is first modified, the master buffer is
+automatically marked as modified so that saving the master buffer will
+work correctly.
+
+\1f
+File: lispref.info, Node: Creating a Partial File, Next: Detached Partial Files, Prev: Intro to Partial Files, Up: Partial Files
+
+Creating a Partial File
+-----------------------
- In XEmacs addition, this function also returns `t' if OBJECT is an
- integer that can be represented as a character. This is because
- of compatibility with previous XEmacs and should not be depended
- on.
+ - Command: make-file-part &optional start end name buffer
+ Make a file part on buffer BUFFER out of the region. Call it
+ NAME. This command creates a new buffer containing the contents
+ of the region and marks the buffer as referring to the specified
+ buffer, called the "master buffer". When the file-part buffer is
+ saved, its changes are integrated back into the master buffer.
+ When the master buffer is deleted, all file parts are deleted with
+ it.
+
+ When called from a function, expects four arguments, START, END,
+ NAME, and BUFFER, all of which are optional and default to the
+ beginning of BUFFER, the end of BUFFER, a name generated from
+ BUFFER's name, and the current buffer, respectively.
+
+\1f
+File: lispref.info, Node: Detached Partial Files, Prev: Creating a Partial File, Up: Partial Files
+
+Detached Partial Files
+----------------------
+
+Every partial file has an extent in the master buffer associated with it
+(called the "master extent"), marking where in the master buffer the
+partial file begins and ends. If the text in master buffer that is
+contained by the extent is deleted, then the extent becomes "detached",
+meaning that it no longer refers to a specific region of the master
+buffer. This can happen either when the text is deleted directly or
+when the master buffer is reverted. Neither of these should happen in
+normal usage because the master buffer should generally not be edited
+directly.
+
+ Before doing any operation that references a partial file's master
+extent, XEmacs checks to make sure that the extent is not detached. If
+this is the case, XEmacs warns the user of this and the master extent is
+deleted out of the master buffer, disconnecting the file part. The file
+part's filename is cleared and thus must be explicitly specified if the
+detached file part is to be saved.
+
+\1f
+File: lispref.info, Node: Format Conversion, Next: Files and MS-DOS, Prev: Partial Files, Up: Files
+
+File Format Conversion
+======================
+
+The variable `format-alist' defines a list of "file formats", which
+describe textual representations used in files for the data (text,
+text-properties, and possibly other information) in an Emacs buffer.
+Emacs performs format conversion if appropriate when reading and writing
+files.
+
+ - Variable: format-alist
+ This list contains one format definition for each defined file
+ format.
+
+ Each format definition is a list of this form:
+
+ (NAME DOC-STRING REGEXP FROM-FN TO-FN MODIFY MODE-FN)
+
+ Here is what the elements in a format definition mean:
+
+NAME
+ The name of this format.
+
+DOC-STRING
+ A documentation string for the format.
+
+REGEXP
+ A regular expression which is used to recognize files represented
+ in this format.
+
+FROM-FN
+ A function to call to decode data in this format (to convert file
+ data into the usual Emacs data representation).
+
+ The FROM-FN is called with two args, BEGIN and END, which specify
+ the part of the buffer it should convert. It should convert the
+ text by editing it in place. Since this can change the length of
+ the text, FROM-FN should return the modified end position.
+
+ One responsibility of FROM-FN is to make sure that the beginning
+ of the file no longer matches REGEXP. Otherwise it is likely to
+ get called again.
+
+TO-FN
+ A function to call to encode data in this format (to convert the
+ usual Emacs data representation into this format).
+
+ The TO-FN is called with two args, BEGIN and END, which specify
+ the part of the buffer it should convert. There are two ways it
+ can do the conversion:
+
+ * By editing the buffer in place. In this case, TO-FN should
+ return the end-position of the range of text, as modified.
+
+ * By returning a list of annotations. This is a list of
+ elements of the form `(POSITION . STRING)', where POSITION is
+ an integer specifying the relative position in the text to be
+ written, and STRING is the annotation to add there. The list
+ must be sorted in order of position when TO-FN returns it.
+
+ When `write-region' actually writes the text from the buffer
+ to the file, it intermixes the specified annotations at the
+ corresponding positions. All this takes place without
+ modifying the buffer.
+
+MODIFY
+ A flag, `t' if the encoding function modifies the buffer, and
+ `nil' if it works by returning a list of annotations.
+
+MODE
+ A mode function to call after visiting a file converted from this
+ format.
+
+ The function `insert-file-contents' automatically recognizes file
+formats when it reads the specified file. It checks the text of the
+beginning of the file against the regular expressions of the format
+definitions, and if it finds a match, it calls the decoding function for
+that format. Then it checks all the known formats over again. It
+keeps checking them until none of them is applicable.
+
+ Visiting a file, with `find-file-noselect' or the commands that use
+it, performs conversion likewise (because it calls
+`insert-file-contents'); it also calls the mode function for each
+format that it decodes. It stores a list of the format names in the
+buffer-local variable `buffer-file-format'.
+
+ - Variable: buffer-file-format
+ This variable states the format of the visited file. More
+ precisely, this is a list of the file format names that were
+ decoded in the course of visiting the current buffer's file. It
+ is always local in all buffers.
+
+ When `write-region' writes data into a file, it first calls the
+encoding functions for the formats listed in `buffer-file-format', in
+the order of appearance in the list.
+
+ - Command: format-write-file file format
+ This command writes the current buffer contents into the file FILE
+ in format FORMAT, and makes that format the default for future
+ saves of the buffer. The argument FORMAT is a list of format
+ names.
+
+ - Command: format-find-file file format
+ This command finds the file FILE, converting it according to
+ format FORMAT. It also makes FORMAT the default if the buffer is
+ saved later.
+
+ The argument FORMAT is a list of format names. If FORMAT is
+ `nil', no conversion takes place. Interactively, typing just
+ <RET> for FORMAT specifies `nil'.
+
+ - Command: format-insert-file file format &optional start end
+ This command inserts the contents of file FILE, converting it
+ according to format FORMAT. If START and END are non-`nil', they
+ specify which part of the file to read, as in
+ `insert-file-contents' (*note Reading from Files::).
+
+ The return value is like what `insert-file-contents' returns: a
+ list of the absolute file name and the length of the data inserted
+ (after conversion).
+
+ The argument FORMAT is a list of format names. If FORMAT is
+ `nil', no conversion takes place. Interactively, typing just
+ <RET> for FORMAT specifies `nil'.
+
+ - Variable: auto-save-file-format
+ This variable specifies the format to use for auto-saving. Its
+ value is a list of format names, just like the value of
+ `buffer-file-format'; but it is used instead of
+ `buffer-file-format' for writing auto-save files. This variable
+ is always local in all buffers.
\1f
-File: lispref.info, Node: Creating Strings, Next: Predicates for Characters, Prev: Predicates for Strings, Up: Strings and Characters
+File: lispref.info, Node: Files and MS-DOS, Prev: Format Conversion, Up: Files
-Creating Strings
+Files and MS-DOS
================
- The following functions create strings, either from scratch, or by
-putting strings together, or by taking them apart.
-
- - Function: string &rest characters
- This function returns a new string made up of CHARACTERS.
-
- (string ?X ?E ?m ?a ?c ?s)
- => "XEmacs"
- (string)
- => ""
-
- Analogous functions operating on other data types include `list',
- `cons' (*note Building Lists::), `vector' (*note Vectors::) and
- `bit-vector' (*note Bit Vectors::). This function has not been
- available in XEmacs prior to 21.0 and FSF Emacs prior to 20.3.
-
- - Function: make-string length character
- This function returns a new string consisting entirely of LENGTH
- successive copies of CHARACTER. LENGTH must be a non-negative
- integer.
-
- (make-string 5 ?x)
- => "xxxxx"
- (make-string 0 ?x)
- => ""
-
- Other functions to compare with this one include `char-to-string'
- (*note String Conversion::), `make-vector' (*note Vectors::), and
- `make-list' (*note Building Lists::).
-
- - Function: substring string start &optional end
- This function returns a new string which consists of those
- characters from STRING in the range from (and including) the
- character at the index START up to (but excluding) the character
- at the index END. The first character is at index zero.
-
- (substring "abcdefg" 0 3)
- => "abc"
-
- Here the index for `a' is 0, the index for `b' is 1, and the index
- for `c' is 2. Thus, three letters, `abc', are copied from the
- string `"abcdefg"'. The index 3 marks the character position up
- to which the substring is copied. The character whose index is 3
- is actually the fourth character in the string.
-
- A negative number counts from the end of the string, so that -1
- signifies the index of the last character of the string. For
- example:
+Emacs on MS-DOS makes a distinction between text files and binary
+files. This is necessary because ordinary text files on MS-DOS use a
+two character sequence between lines: carriage-return and linefeed
+(CRLF). Emacs expects just a newline character (a linefeed) between
+lines. When Emacs reads or writes a text file on MS-DOS, it needs to
+convert the line separators. This means it needs to know which files
+are text files and which are binary. It makes this decision when
+visiting a file, and records the decision in the variable
+`buffer-file-type' for use when the file is saved.
+
+ *Note MS-DOS Subprocesses::, for a related feature for subprocesses.
+
+ - Variable: buffer-file-type
+ This variable, automatically local in each buffer, records the
+ file type of the buffer's visited file. The value is `nil' for
+ text, `t' for binary.
+
+ - Function: find-buffer-file-type filename
+ This function determines whether file FILENAME is a text file or a
+ binary file. It returns `nil' for text, `t' for binary.
+
+ - User Option: file-name-buffer-file-type-alist
+ This variable holds an alist for distinguishing text files from
+ binary files. Each element has the form (REGEXP . TYPE), where
+ REGEXP is matched against the file name, and TYPE may be is `nil'
+ for text, `t' for binary, or a function to call to compute which.
+ If it is a function, then it is called with a single argument (the
+ file name) and should return `t' or `nil'.
+
+ - User Option: default-buffer-file-type
+ This variable specifies the default file type for files whose names
+ don't indicate anything in particular. Its value should be `nil'
+ for text, or `t' for binary.
+
+ - Command: find-file-text filename
+ Like `find-file', but treat the file as text regardless of its
+ name.
+
+ - Command: find-file-binary filename
+ Like `find-file', but treat the file as binary regardless of its
+ name.
- (substring "abcdefg" -3 -1)
- => "ef"
-
- In this example, the index for `e' is -3, the index for `f' is -2,
- and the index for `g' is -1. Therefore, `e' and `f' are included,
- and `g' is excluded.
-
- When `nil' is used as an index, it stands for the length of the
- string. Thus,
-
- (substring "abcdefg" -3 nil)
- => "efg"
-
- Omitting the argument END is equivalent to specifying `nil'. It
- follows that `(substring STRING 0)' returns a copy of all of
- STRING.
-
- (substring "abcdefg" 0)
- => "abcdefg"
-
- But we recommend `copy-sequence' for this purpose (*note Sequence
- Functions::).
-
- If the characters copied from STRING have duplicable extents or
- text properties, those are copied into the new string also. *Note
- Duplicable Extents::.
-
- A `wrong-type-argument' error is signaled if either START or END
- is not an integer or `nil'. An `args-out-of-range' error is
- signaled if START indicates a character following END, or if
- either integer is out of range for STRING.
-
- Contrast this function with `buffer-substring' (*note Buffer
- Contents::), which returns a string containing a portion of the
- text in the current buffer. The beginning of a string is at index
- 0, but the beginning of a buffer is at index 1.
-
- - Function: concat &rest sequences
- This function returns a new string consisting of the characters in
- the arguments passed to it (along with their text properties, if
- any). The arguments may be strings, lists of numbers, or vectors
- of numbers; they are not themselves changed. If `concat' receives
- no arguments, it returns an empty string.
-
- (concat "abc" "-def")
- => "abc-def"
- (concat "abc" (list 120 (+ 256 121)) [122])
- => "abcxyz"
- ;; `nil' is an empty sequence.
- (concat "abc" nil "-def")
- => "abc-def"
- (concat "The " "quick brown " "fox.")
- => "The quick brown fox."
- (concat)
- => ""
-
- The second example above shows how characters stored in strings are
- taken modulo 256. In other words, each character in the string is
- stored in one byte.
-
- The `concat' function always constructs a new string that is not
- `eq' to any existing string.
-
- When an argument is an integer (not a sequence of integers), it is
- converted to a string of digits making up the decimal printed
- representation of the integer. *Don't use this feature; we plan
- to eliminate it. If you already use this feature, change your
- programs now!* The proper way to convert an integer to a decimal
- number in this way is with `format' (*note Formatting Strings::) or
- `number-to-string' (*note String Conversion::).
-
- (concat 137)
- => "137"
- (concat 54 321)
- => "54321"
-
- For information about other concatenation functions, see the
- description of `mapconcat' in *Note Mapping Functions::, `vconcat'
- in *Note Vectors::, `bvconcat' in *Note Bit Vectors::, and `append'
- in *Note Building Lists::.
-
-\1f
-File: lispref.info, Node: Predicates for Characters, Next: Character Codes, Prev: Creating Strings, Up: Strings and Characters
-
-The Predicates for Characters
-=============================
+\1f
+File: lispref.info, Node: Backups and Auto-Saving, Next: Buffers, Prev: Files, Up: Top
- - Function: characterp object
- This function returns `t' if OBJECT is a character.
+Backups and Auto-Saving
+***********************
- Some functions that work on integers (e.g. the comparison functions
- <, <=, =, /=, etc. and the arithmetic functions +, -, *, etc.)
- accept characters and implicitly convert them into integers. In
- general, functions that work on characters also accept char-ints
- and implicitly convert them into characters. WARNING: Neither of
- these behaviors is very desirable, and they are maintained for
- backward compatibility with old E-Lisp programs that confounded
- characters and integers willy-nilly. These behaviors may change
- in the future; therefore, do not rely on them. Instead, convert
- the characters explicitly using `char-int'.
+Backup files and auto-save files are two methods by which XEmacs tries
+to protect the user from the consequences of crashes or of the user's
+own errors. Auto-saving preserves the text from earlier in the current
+editing session; backup files preserve file contents prior to the
+current session.
- - Function: integer-or-char-p object
- This function returns `t' if OBJECT is an integer or character.
+* Menu:
+
+* Backup Files:: How backup files are made; how their names are chosen.
+* Auto-Saving:: How auto-save files are made; how their names are chosen.
+* Reverting:: `revert-buffer', and how to customize what it does.
\1f
-File: lispref.info, Node: Character Codes, Next: Text Comparison, Prev: Predicates for Characters, Up: Strings and Characters
+File: lispref.info, Node: Backup Files, Next: Auto-Saving, Up: Backups and Auto-Saving
-Character Codes
-===============
+Backup Files
+============
+
+A "backup file" is a copy of the old contents of a file you are
+editing. XEmacs makes a backup file the first time you save a buffer
+into its visited file. Normally, this means that the backup file
+contains the contents of the file as it was before the current editing
+session. The contents of the backup file normally remain unchanged once
+it exists.
+
+ Backups are usually made by renaming the visited file to a new name.
+Optionally, you can specify that backup files should be made by copying
+the visited file. This choice makes a difference for files with
+multiple names; it also can affect whether the edited file remains owned
+by the original owner or becomes owned by the user editing it.
+
+ By default, XEmacs makes a single backup file for each file edited.
+You can alternatively request numbered backups; then each new backup
+file gets a new name. You can delete old numbered backups when you
+don't want them any more, or XEmacs can delete them automatically.
+
+* Menu:
- - Function: char-int character
- This function converts a character into an equivalent integer.
- The resulting integer will always be non-negative. The integers in
- the range 0 - 255 map to characters as follows:
+* Making Backups:: How XEmacs makes backup files, and when.
+* Rename or Copy:: Two alternatives: renaming the old file or copying it.
+* Numbered Backups:: Keeping multiple backups for each source file.
+* Backup Names:: How backup file names are computed; customization.
- 0 - 31
- Control set 0
+\1f
+File: lispref.info, Node: Making Backups, Next: Rename or Copy, Up: Backup Files
+
+Making Backup Files
+-------------------
+
+ - Function: backup-buffer
+ This function makes a backup of the file visited by the current
+ buffer, if appropriate. It is called by `save-buffer' before
+ saving the buffer the first time.
+
+ - Variable: buffer-backed-up
+ This buffer-local variable indicates whether this buffer's file has
+ been backed up on account of this buffer. If it is non-`nil', then
+ the backup file has been written. Otherwise, the file should be
+ backed up when it is next saved (if backups are enabled). This is
+ a permanent local; `kill-local-variables' does not alter it.
+
+ - User Option: make-backup-files
+ This variable determines whether or not to make backup files. If
+ it is non-`nil', then XEmacs creates a backup of each file when it
+ is saved for the first time--provided that `backup-inhibited' is
+ `nil' (see below).
+
+ The following example shows how to change the `make-backup-files'
+ variable only in the `RMAIL' buffer and not elsewhere. Setting it
+ `nil' stops XEmacs from making backups of the `RMAIL' file, which
+ may save disk space. (You would put this code in your `.emacs'
+ file.)
+
+ (add-hook 'rmail-mode-hook
+ (function (lambda ()
+ (make-local-variable
+ 'make-backup-files)
+ (setq make-backup-files nil))))
+
+ - Variable: backup-enable-predicate
+ This variable's value is a function to be called on certain
+ occasions to decide whether a file should have backup files. The
+ function receives one argument, a file name to consider. If the
+ function returns `nil', backups are disabled for that file.
+ Otherwise, the other variables in this section say whether and how
+ to make backups.
+
+ The default value is this:
+
+ (lambda (name)
+ (or (< (length name) 5)
+ (not (string-equal "/tmp/"
+ (substring name 0 5)))))
+
+ - Variable: backup-inhibited
+ If this variable is non-`nil', backups are inhibited. It records
+ the result of testing `backup-enable-predicate' on the visited file
+ name. It can also coherently be used by other mechanisms that
+ inhibit backups based on which file is visited. For example, VC
+ sets this variable non-`nil' to prevent making backups for files
+ managed with a version control system.
+
+ This is a permanent local, so that changing the major mode does
+ not lose its value. Major modes should not set this
+ variable--they should set `make-backup-files' instead.
+
+\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.
- 32 - 127
- ASCII
+ 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::.
- 128 - 159
- Control set 1
+ - Variable: backup-by-copying
+ If this variable is non-`nil', XEmacs always makes backup files by
+ copying.
- 160 - 255
- Right half of ISO-8859-1
+ 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.
- If support for MULE does not exist, these are the only valid
- character values. When MULE support exists, the values assigned to
- other characters may vary depending on the particular version of
- XEmacs, the order in which character sets were loaded, etc., and
- you should not depend on them.
+ - Variable: backup-by-copying-when-linked
+ If this variable is non-`nil', XEmacs makes backups by copying for
+ files with multiple names (hard links).
- - Function: int-char integer
- This function converts an integer into the equivalent character.
- Not all integers correspond to valid characters; use `char-int-p'
- to determine whether this is the case. If the integer cannot be
- converted, `nil' is returned.
+ This variable is significant only if `backup-by-copying' is `nil',
+ since copying is always used when that variable is non-`nil'.
- - Function: char-int-p object
- This function returns `t' if OBJECT is an integer that can be
- converted into a character.
+ - 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.
- - Function: char-or-char-int-p object
- This function returns `t' if OBJECT is a character or an integer
- that can be converted into one.
+ 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: Text Comparison, Next: String Conversion, Prev: Character Codes, Up: Strings and Characters
+File: lispref.info, Node: Numbered Backups, Next: Backup Names, Prev: Rename or Copy, Up: Backup Files
-Comparison of Characters and Strings
-====================================
+Making and Deleting Numbered Backup Files
+-----------------------------------------
- - Function: char-equal character1 character2 &optional buffer
- This function returns `t' if the arguments represent the same
- character, `nil' otherwise. This function ignores differences in
- case if the value of `case-fold-search' is non-`nil' in BUFFER,
- which defaults to the current buffer.
+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.
- (char-equal ?x ?x)
- => t
- (let ((case-fold-search t))
- (char-equal ?x ?X))
- => t
- (let ((case-fold-search nil))
- (char-equal ?x ?X))
- => nil
+ - User Option: version-control
+ This variable controls whether to make a single non-numbered backup
+ file or multiple numbered backups.
- - Function: char= character1 character2
- This function returns `t' if the arguments represent the same
- character, `nil' otherwise. Case is significant.
+ `nil'
+ Make numbered backups if the visited file already has
+ numbered backups; otherwise, do not.
- (char= ?x ?x)
- => t
- (char= ?x ?X)
- => nil
- (let ((case-fold-search t))
- (char-equal ?x ?X))
- => nil
- (let ((case-fold-search nil))
- (char-equal ?x ?X))
- => nil
+ `never'
+ Do not make numbered backups.
- - Function: string= string1 string2
- This function returns `t' if the characters of the two strings
- match exactly; case is significant.
+ ANYTHING ELSE
+ Make numbered backups.
- (string= "abc" "abc")
- => t
- (string= "abc" "ABC")
- => nil
- (string= "ab" "ABC")
+ 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:
- - Function: string-equal string1 string2
- `string-equal' is another name for `string='.
+ (defun backup-file-name-p (file)
+ "Return non-nil if FILE is a backup file \
+ name (numeric or not)..."
+ (string-match "~$" file))
- - Function: string< string1 string2
- This function compares two strings a character at a time. First it
- scans both the strings at once to find the first pair of
- corresponding characters that do not match. If the lesser
- character of those two is the character from STRING1, then STRING1
- is less, and this function returns `t'. If the lesser character
- is the one from STRING2, then STRING1 is greater, and this
- function returns `nil'. If the two strings match entirely, the
- value is `nil'.
+ 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.)
- Pairs of characters are compared by their ASCII codes. Keep in
- mind that lower case letters have higher numeric values in the
- ASCII character set than their upper case counterparts; numbers and
- many punctuation characters have a lower numeric value than upper
- case letters.
+ This simple expression is placed in a separate function to make it
+ easy to redefine for customization.
- (string< "abc" "abd")
- => t
- (string< "abd" "abc")
+ - 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
- (string< "123" "abc")
- => t
- When the strings have different lengths, and they match up to the
- length of STRING1, then the result is `t'. If they match up to
- the length of STRING2, the result is `nil'. A string of no
- characters is less than any other string.
+ 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.
- (string< "" "abc")
- => t
- (string< "ab" "abc")
- => t
- (string< "abc" "")
+\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
+=============
+
+A "buffer" is a Lisp object containing text to be edited. Buffers are
+used to hold the contents of files that are being visited; there may
+also be buffers that are not visiting files. While several buffers may
+exist at one time, exactly one buffer is designated the "current
+buffer" at any time. Most editing commands act on the contents of the
+current buffer. Each buffer, including the current buffer, may or may
+not be displayed in any windows.
+
+Buffers in Emacs editing are objects that have distinct names and hold
+text that can be edited. Buffers appear to Lisp programs as a special
+data type. You can think of the contents of a buffer as an extendible
+string; insertions and deletions may occur in any part of the buffer.
+*Note Text::.
+
+ A Lisp buffer object contains numerous pieces of information. Some
+of this information is directly accessible to the programmer through
+variables, while other information is accessible only through
+special-purpose functions. For example, the visited file name is
+directly accessible through a variable, while the value of point is
+accessible only through a primitive function.
+
+ Buffer-specific information that is directly accessible is stored in
+"buffer-local" variable bindings, which are variable values that are
+effective only in a particular buffer. This feature allows each buffer
+to override the values of certain variables. Most major modes override
+variables such as `fill-column' or `comment-column' in this way. For
+more information about buffer-local variables and functions related to
+them, see *Note Buffer-Local Variables::.
+
+ For functions and variables related to visiting files in buffers, see
+*Note Visiting Files:: and *Note Saving Buffers::. For functions and
+variables related to the display of buffers in windows, see *Note
+Buffers and Windows::.
+
+ - Function: bufferp object
+ This function returns `t' if OBJECT is a buffer, `nil' otherwise.
+
+\1f
+File: lispref.info, Node: Current Buffer, Next: Buffer Names, Prev: Buffer Basics, Up: Buffers
+
+The Current Buffer
+==================
+
+There are, in general, many buffers in an Emacs session. At any time,
+one of them is designated as the "current buffer". This is the buffer
+in which most editing takes place, because most of the primitives for
+examining or changing text in a buffer operate implicitly on the
+current buffer (*note Text::). Normally the buffer that is displayed on
+the screen in the selected window is the current buffer, but this is not
+always so: a Lisp program can designate any buffer as current
+temporarily in order to operate on its contents, without changing what
+is displayed on the screen.
+
+ The way to designate a current buffer in a Lisp program is by calling
+`set-buffer'. The specified buffer remains current until a new one is
+designated.
+
+ When an editing command returns to the editor command loop, the
+command loop designates the buffer displayed in the selected window as
+current, to prevent confusion: the buffer that the cursor is in when
+Emacs reads a command is the buffer that the command will apply to.
+(*Note Command Loop::.) Therefore, `set-buffer' is not the way to
+switch visibly to a different buffer so that the user can edit it. For
+this, you must use the functions described in *Note Displaying
+Buffers::.
+
+ However, Lisp functions that change to a different current buffer
+should not depend on the command loop to set it back afterwards.
+Editing commands written in XEmacs Lisp can be called from other
+programs as well as from the command loop. It is convenient for the
+caller if the subroutine does not change which buffer is current
+(unless, of course, that is the subroutine's purpose). Therefore, you
+should normally use `set-buffer' within a `save-excursion' that will
+restore the current buffer when your function is done (*note
+Excursions::). Here is an example, the code for the command
+`append-to-buffer' (with the documentation string abridged):
+
+ (defun append-to-buffer (buffer start end)
+ "Append to specified buffer the text of the region.
+ ..."
+ (interactive "BAppend to buffer: \nr")
+ (let ((oldbuf (current-buffer)))
+ (save-excursion
+ (set-buffer (get-buffer-create buffer))
+ (insert-buffer-substring oldbuf start end))))
+
+This function binds a local variable to the current buffer, and then
+`save-excursion' records the values of point, the mark, and the
+original buffer. Next, `set-buffer' makes another buffer current.
+Finally, `insert-buffer-substring' copies the string from the original
+current buffer to the new current buffer.
+
+ If the buffer appended to happens to be displayed in some window,
+the next redisplay will show how its text has changed. Otherwise, you
+will not see the change immediately on the screen. The buffer becomes
+current temporarily during the execution of the command, but this does
+not cause it to be displayed.
+
+ If you make local bindings (with `let' or function arguments) for a
+variable that may also have buffer-local bindings, make sure that the
+same buffer is current at the beginning and at the end of the local
+binding's scope. Otherwise you might bind it in one buffer and unbind
+it in another! There are two ways to do this. In simple cases, you may
+see that nothing ever changes the current buffer within the scope of the
+binding. Otherwise, use `save-excursion' to make sure that the buffer
+current at the beginning is current again whenever the variable is
+unbound.
+
+ It is not reliable to change the current buffer back with
+`set-buffer', because that won't do the job if a quit happens while the
+wrong buffer is current. Here is what _not_ to do:
+
+ (let (buffer-read-only
+ (obuf (current-buffer)))
+ (set-buffer ...)
+ ...
+ (set-buffer obuf))
+
+Using `save-excursion', as shown below, handles quitting, errors, and
+`throw', as well as ordinary evaluation.
+
+ (let (buffer-read-only)
+ (save-excursion
+ (set-buffer ...)
+ ...))
+
+ - Function: current-buffer
+ This function returns the current buffer.
+
+ (current-buffer)
+ => #<buffer buffers.texi>
+
+ - Function: set-buffer buffer-or-name
+ This function makes BUFFER-OR-NAME the current buffer. It does
+ not display the buffer in the currently selected window or in any
+ other window, so the user cannot necessarily see the buffer. But
+ Lisp programs can in any case work on it.
+
+ BUFFER-OR-NAME must be a buffer or the name of an existing
+ buffer-else an error is signaled. This function returns the buffer
+ identified by BUFFER-OR-NAME.
+
+\1f
+File: lispref.info, Node: Buffer Names, Next: Buffer File Name, Prev: Current Buffer, Up: Buffers
+
+Buffer Names
+============
+
+Each buffer has a unique name, which is a string. Many of the
+functions that work on buffers accept either a buffer or a buffer name
+as an argument. Any argument called BUFFER-OR-NAME is of this sort,
+and an error is signaled if it is neither a string nor a buffer. Any
+argument called BUFFER must be an actual buffer object, not a name.
+
+ Buffers that are ephemeral and generally uninteresting to the user
+have names starting with a space, so that the `list-buffers' and
+`buffer-menu' commands don't mention them. A name starting with space
+also initially disables recording undo information; see *Note Undo::.
+
+ - Function: buffer-name &optional buffer
+ This function returns the name of BUFFER as a string. If BUFFER
+ is not supplied, it defaults to the current buffer.
+
+ If `buffer-name' returns `nil', it means that BUFFER has been
+ killed. *Note Killing Buffers::.
+
+ (buffer-name)
+ => "buffers.texi"
+
+ (setq foo (get-buffer "temp"))
+ => #<buffer temp>
+ (kill-buffer foo)
=> nil
- (string< "abc" "ab")
+ (buffer-name foo)
=> nil
- (string< "" "")
+ foo
+ => #<killed buffer>
+
+ - Command: rename-buffer newname &optional unique
+ This function renames the current buffer to NEWNAME. An error is
+ signaled if NEWNAME is not a string, or if there is already a
+ buffer with that name. The function returns `nil'.
+
+ Ordinarily, `rename-buffer' signals an error if NEWNAME is already
+ in use. However, if UNIQUE is non-`nil', it modifies NEWNAME to
+ make a name that is not in use. Interactively, you can make
+ UNIQUE non-`nil' with a numeric prefix argument.
+
+ One application of this command is to rename the `*shell*' buffer
+ to some other name, thus making it possible to create a second
+ shell buffer under the name `*shell*'.
+
+ - Function: get-buffer buffer-or-name
+ This function returns the buffer named BUFFER-OR-NAME. If
+ BUFFER-OR-NAME is a string and there is no buffer with that name,
+ the value is `nil'. If BUFFER-OR-NAME is actually a buffer, it is
+ returned as given. (That is not very useful, so the argument is
+ usually a name.) For example:
+
+ (setq b (get-buffer "lewis"))
+ => #<buffer lewis>
+ (get-buffer b)
+ => #<buffer lewis>
+ (get-buffer "Frazzle-nots")
=> nil
- - Function: string-lessp string1 string2
- `string-lessp' is another name for `string<'.
+ See also the function `get-buffer-create' in *Note Creating
+ Buffers::.
+
+ - Function: generate-new-buffer-name starting-name &optional ignore
+ This function returns a name that would be unique for a new
+ buffer--but does not create the buffer. It starts with
+ STARTING-NAME, and produces a name not currently in use for any
+ buffer by appending a number inside of `<...>'.
- See also `compare-buffer-substrings' in *Note Comparing Text::, for
-a way to compare text in buffers. The function `string-match', which
-matches a regular expression against a string, can be used for a kind
-of string comparison; see *Note Regexp Search::.
+ If IGNORE is given, it specifies a name that is okay to use (if it
+ is in the sequence to be tried), even if a buffer with that name
+ exists.
+
+ See the related function `generate-new-buffer' in *Note Creating
+ Buffers::.
\1f
-File: lispref.info, Node: String Conversion, Next: Modifying Strings, Prev: Text Comparison, Up: Strings and Characters
+File: lispref.info, Node: Buffer File Name, Next: Buffer Modification, Prev: Buffer Names, Up: Buffers
-Conversion of Characters and Strings
-====================================
+Buffer File Name
+================
- This section describes functions for conversions between characters,
-strings and integers. `format' and `prin1-to-string' (*note Output
-Functions::) can also convert Lisp objects into strings.
-`read-from-string' (*note Input Functions::) can "convert" a string
-representation of a Lisp object into an object.
-
- *Note Documentation::, for functions that produce textual
-descriptions of text characters and general input events
-(`single-key-description' and `text-char-description'). These
-functions are used primarily for making help messages.
-
- - Function: char-to-string character
- This function returns a new string with a length of one character.
- The value of CHARACTER, modulo 256, is used to initialize the
- element of the string.
-
- This function is similar to `make-string' with an integer argument
- of 1. (*Note Creating Strings::.) This conversion can also be
- done with `format' using the `%c' format specification. (*Note
- Formatting Strings::.)
-
- (char-to-string ?x)
- => "x"
- (char-to-string (+ 256 ?x))
- => "x"
- (make-string 1 ?x)
- => "x"
-
- - Function: string-to-char string
- This function returns the first character in STRING. If the
- string is empty, the function returns 0. (Under XEmacs 19, the
- value is also 0 when the first character of STRING is the null
- character, ASCII code 0.)
-
- (string-to-char "ABC")
- => ?A ;; Under XEmacs 20.
- => 65 ;; Under XEmacs 19.
- (string-to-char "xyz")
- => ?x ;; Under XEmacs 20.
- => 120 ;; Under XEmacs 19.
- (string-to-char "")
- => 0
- (string-to-char "\000")
- => ?\^ ;; Under XEmacs 20.
- => 0 ;; Under XEmacs 20.
-
- This function may be eliminated in the future if it does not seem
- useful enough to retain.
-
- - Function: number-to-string number
- This function returns a string consisting of the printed
- representation of NUMBER, which may be an integer or a floating
- point number. The value starts with a sign if the argument is
- negative.
-
- (number-to-string 256)
- => "256"
- (number-to-string -23)
- => "-23"
- (number-to-string -23.5)
- => "-23.5"
-
- `int-to-string' is a semi-obsolete alias for this function.
-
- See also the function `format' in *Note Formatting Strings::.
-
- - Function: string-to-number string &optional base
- This function returns the numeric value represented by STRING,
- read in BASE. It skips spaces and tabs at the beginning of
- STRING, then reads as much of STRING as it can interpret as a
- number. (On some systems it ignores other whitespace at the
- beginning, not just spaces and tabs.) If the first character
- after the ignored whitespace is not a digit or a minus sign, this
- function returns 0.
-
- If BASE is not specified, it defaults to ten. With BASE other
- than ten, only integers can be read.
-
- (string-to-number "256")
- => 256
- (string-to-number "25 is a perfect square.")
- => 25
- (string-to-number "X256")
- => 0
- (string-to-number "-4.5")
- => -4.5
- (string-to-number "ffff" 16)
- => 65535
+The "buffer file name" is the name of the file that is visited in that
+buffer. When a buffer is not visiting a file, its buffer file name is
+`nil'. Most of the time, the buffer name is the same as the
+nondirectory part of the buffer file name, but the buffer file name and
+the buffer name are distinct and can be set independently. *Note
+Visiting Files::.
+
+ - Function: buffer-file-name &optional buffer
+ This function returns the absolute file name of the file that
+ BUFFER is visiting. If BUFFER is not visiting any file,
+ `buffer-file-name' returns `nil'. If BUFFER is not supplied, it
+ defaults to the current buffer.
+
+ (buffer-file-name (other-buffer))
+ => "/usr/user/lewis/manual/files.texi"
+
+ - Variable: buffer-file-name
+ This buffer-local variable contains the name of the file being
+ visited in the current buffer, or `nil' if it is not visiting a
+ file. It is a permanent local, unaffected by
+ `kill-local-variables'.
+
+ buffer-file-name
+ => "/usr/user/lewis/manual/buffers.texi"
+
+ It is risky to change this variable's value without doing various
+ other things. See the definition of `set-visited-file-name' in
+ `files.el'; some of the things done there, such as changing the
+ buffer name, are not strictly necessary, but others are essential
+ to avoid confusing XEmacs.
+
+ - Variable: buffer-file-truename
+ This buffer-local variable holds the truename of the file visited
+ in the current buffer, or `nil' if no file is visited. It is a
+ permanent local, unaffected by `kill-local-variables'. *Note
+ Truenames::.
+
+ - Variable: buffer-file-number
+ This buffer-local variable holds the file number and directory
+ device number of the file visited in the current buffer, or `nil'
+ if no file or a nonexistent file is visited. It is a permanent
+ local, unaffected by `kill-local-variables'. *Note Truenames::.
+
+ The value is normally a list of the form `(FILENUM DEVNUM)'. This
+ pair of numbers uniquely identifies the file among all files
+ accessible on the system. See the function `file-attributes', in
+ *Note File Attributes::, for more information about them.
+
+ - Function: get-file-buffer filename
+ This function returns the buffer visiting file FILENAME. If there
+ is no such buffer, it returns `nil'. The argument FILENAME, which
+ must be a string, is expanded (*note File Name Expansion::), then
+ compared against the visited file names of all live buffers.
+
+ (get-file-buffer "buffers.texi")
+ => #<buffer buffers.texi>
+
+ In unusual circumstances, there can be more than one buffer
+ visiting the same file name. In such cases, this function returns
+ the first such buffer in the buffer list.
+
+ - Command: set-visited-file-name filename
+ If FILENAME is a non-empty string, this function changes the name
+ of the file visited in current buffer to FILENAME. (If the buffer
+ had no visited file, this gives it one.) The _next time_ the
+ buffer is saved it will go in the newly-specified file. This
+ command marks the buffer as modified, since it does not (as far as
+ XEmacs knows) match the contents of FILENAME, even if it matched
+ the former visited file.
+
+ If FILENAME is `nil' or the empty string, that stands for "no
+ visited file". In this case, `set-visited-file-name' marks the
+ buffer as having no visited file.
+
+ When the function `set-visited-file-name' is called interactively,
+ it prompts for FILENAME in the minibuffer.
+
+ See also `clear-visited-file-modtime' and
+ `verify-visited-file-modtime' in *Note Buffer Modification::.
+
+ - Variable: list-buffers-directory
+ This buffer-local variable records a string to display in a buffer
+ listing in place of the visited file name, for buffers that don't
+ have a visited file name. Dired buffers use this variable.
+
+\1f
+File: lispref.info, Node: Buffer Modification, Next: Modification Time, Prev: Buffer File Name, Up: Buffers
+
+Buffer Modification
+===================
+
+XEmacs keeps a flag called the "modified flag" for each buffer, to
+record whether you have changed the text of the buffer. This flag is
+set to `t' whenever you alter the contents of the buffer, and cleared
+to `nil' when you save it. Thus, the flag shows whether there are
+unsaved changes. The flag value is normally shown in the modeline
+(*note Modeline Variables::), and controls saving (*note Saving
+Buffers::) and auto-saving (*note Auto-Saving::).
+
+ Some Lisp programs set the flag explicitly. For example, the
+function `set-visited-file-name' sets the flag to `t', because the text
+does not match the newly-visited file, even if it is unchanged from the
+file formerly visited.
+
+ The functions that modify the contents of buffers are described in
+*Note Text::.
+
+ - Function: buffer-modified-p &optional buffer
+ This function returns `t' if the buffer BUFFER has been modified
+ since it was last read in from a file or saved, or `nil'
+ otherwise. If BUFFER is not supplied, the current buffer is
+ tested.
+
+ - Function: set-buffer-modified-p flag &optional buffer
+ This function marks BUFFER as modified if FLAG is non-`nil', or as
+ unmodified if the flag is `nil'. BUFFER defaults to the current
+ buffer.
+
+ Another effect of calling this function is to cause unconditional
+ redisplay of the modeline for the current buffer. In fact, the
+ function `redraw-modeline' works by doing this:
+
+ (set-buffer-modified-p (buffer-modified-p))
+
+ - Command: not-modified &optional arg
+ This command marks the current buffer as unmodified, and not
+ needing to be saved. (If ARG is non-`nil', the buffer is instead
+ marked as modified.) Don't use this function in programs, since it
+ prints a message in the echo area; use `set-buffer-modified-p'
+ (above) instead.
+
+ - Function: buffer-modified-tick &optional buffer
+ This function returns BUFFER`s modification-count. This is a
+ counter that increments every time the buffer is modified. If
+ BUFFER is `nil' (or omitted), the current buffer is used.
- `string-to-int' is an obsolete alias for this function.
+\1f
+File: lispref.info, Node: Modification Time, Next: Read Only Buffers, Prev: Buffer Modification, Up: Buffers
+
+Comparison of Modification Time
+===============================
+
+Suppose that you visit a file and make changes in its buffer, and
+meanwhile the file itself is changed on disk. At this point, saving the
+buffer would overwrite the changes in the file. Occasionally this may
+be what you want, but usually it would lose valuable information.
+XEmacs therefore checks the file's modification time using the functions
+described below before saving the file.
+
+ - Function: verify-visited-file-modtime buffer
+ This function compares what BUFFER has recorded for the
+ modification time of its visited file against the actual
+ modification time of the file as recorded by the operating system.
+ The two should be the same unless some other process has written
+ the file since XEmacs visited or saved it.
+
+ The function returns `t' if the last actual modification time and
+ XEmacs's recorded modification time are the same, `nil' otherwise.
+
+ - Function: clear-visited-file-modtime
+ This function clears out the record of the last modification time
+ of the file being visited by the current buffer. As a result, the
+ next attempt to save this buffer will not complain of a
+ discrepancy in file modification times.
+
+ This function is called in `set-visited-file-name' and other
+ exceptional places where the usual test to avoid overwriting a
+ changed file should not be done.
+
+ - Function: visited-file-modtime
+ This function returns the buffer's recorded last file modification
+ time, as a list of the form `(HIGH . LOW)'. (This is the same
+ format that `file-attributes' uses to return time values; see
+ *Note File Attributes::.)
+
+ - Function: set-visited-file-modtime &optional time
+ This function updates the buffer's record of the last modification
+ time of the visited file, to the value specified by TIME if TIME
+ is not `nil', and otherwise to the last modification time of the
+ visited file.
+
+ If TIME is not `nil', it should have the form `(HIGH . LOW)' or
+ `(HIGH LOW)', in either case containing two integers, each of
+ which holds 16 bits of the time.
+
+ This function is useful if the buffer was not read from the file
+ normally, or if the file itself has been changed for some known
+ benign reason.
+
+ - Function: ask-user-about-supersession-threat filename
+ This function is used to ask a user how to proceed after an
+ attempt to modify an obsolete buffer visiting file FILENAME. An
+ "obsolete buffer" is an unmodified buffer for which the associated
+ file on disk is newer than the last save-time of the buffer. This
+ means some other program has probably altered the file.
+
+ Depending on the user's answer, the function may return normally,
+ in which case the modification of the buffer proceeds, or it may
+ signal a `file-supersession' error with data `(FILENAME)', in which
+ case the proposed buffer modification is not allowed.
+
+ This function is called automatically by XEmacs on the proper
+ occasions. It exists so you can customize XEmacs by redefining it.
+ See the file `userlock.el' for the standard definition.
+
+ See also the file locking mechanism in *Note File Locks::.
\1f
-File: lispref.info, Node: Modifying Strings, Next: String Properties, Prev: String Conversion, Up: Strings and Characters
+File: lispref.info, Node: Read Only Buffers, Next: The Buffer List, Prev: Modification Time, Up: Buffers
-Modifying Strings
+Read-Only Buffers
=================
- You can modify a string using the general array-modifying primitives.
-*Note Arrays::. The function `aset' modifies a single character; the
-function `fillarray' sets all characters in the string to a specified
-character.
+If a buffer is "read-only", then you cannot change its contents,
+although you may change your view of the contents by scrolling and
+narrowing.
+
+ Read-only buffers are used in two kinds of situations:
+
+ * A buffer visiting a write-protected file is normally read-only.
+
+ Here, the purpose is to show the user that editing the buffer with
+ the aim of saving it in the file may be futile or undesirable.
+ The user who wants to change the buffer text despite this can do
+ so after clearing the read-only flag with `C-x C-q'.
+
+ * Modes such as Dired and Rmail make buffers read-only when altering
+ the contents with the usual editing commands is probably a mistake.
+
+ The special commands of these modes bind `buffer-read-only' to
+ `nil' (with `let') or bind `inhibit-read-only' to `t' around the
+ places where they change the text.
+
+ - Variable: buffer-read-only
+ This buffer-local variable specifies whether the buffer is
+ read-only. The buffer is read-only if this variable is non-`nil'.
+
+ - Variable: inhibit-read-only
+ If this variable is non-`nil', then read-only buffers and read-only
+ characters may be modified. Read-only characters in a buffer are
+ those that have non-`nil' `read-only' properties (either text
+ properties or extent properties). *Note Extent Properties::, for
+ more information about text properties and extent properties.
+
+ If `inhibit-read-only' is `t', all `read-only' character
+ properties have no effect. If `inhibit-read-only' is a list, then
+ `read-only' character properties have no effect if they are members
+ of the list (comparison is done with `eq').
+
+ - Command: toggle-read-only &optional arg
+ This command changes whether the current buffer is read-only.
+ Interactively, if a prefix arg ARG is supplied, set the current
+ buffer read only if and only if ARG is positive.
+
+ This command is intended for interactive use only; don't use it in
+ programs. At any given point in a program, you should know
+ whether you want the read-only flag on or off; so you can set
+ `buffer-read-only' explicitly to the proper value, `t' or `nil'.
+
+ - Function: barf-if-buffer-read-only &optional buffer start end
+ This function signals a `buffer-read-only' error if BUFFER is
+ read-only. BUFFER defaults to the current buffer. *Note
+ Interactive Call::, for another way to signal an error if the
+ current buffer is read-only.
+
+ If optional argument START is non-`nil', all extents in the buffer
+ which overlap that part of the buffer are checked to ensure none
+ has a `read-only' property. (Extents that lie completely within the
+ range, however, are not checked.) END defaults to the value of
+ START.
+
+ If START and END are equal, the range checked is [START, END]
+ (i.e. closed on both ends); otherwise, the range checked is
+ (START, END) \(open on both ends), except that extents that lie
+ completely within [START, END] are not checked. See
+ `extent-in-region-p' for a fuller discussion.
+
+\1f
+File: lispref.info, Node: The Buffer List, Next: Creating Buffers, Prev: Read Only Buffers, Up: Buffers
- Each string has a tick counter that starts out at zero (when the
-string is created) and is incremented each time a change is made to that
-string.
+The Buffer List
+===============
- - Function: string-modified-tick string
- This function returns the tick counter for `string'.
+The "buffer list" is a list of all live buffers. Creating a buffer
+adds it to this list, and killing a buffer deletes it. The order of
+the buffers in the list is based primarily on how recently each buffer
+has been displayed in the selected window. Buffers move to the front
+of the list when they are selected and to the end when they are buried.
+Several functions, notably `other-buffer', use this ordering. A
+buffer list displayed for the user also follows this order.
+
+ Every frame has its own order for the buffer list. Switching to a
+new buffer inside of a particular frame changes the buffer list order
+for that frame, but does not affect the buffer list order of any other
+frames. In addition, there is a global, non-frame buffer list order
+that is independent of the buffer list orders for any particular frame.
+
+ Note that the different buffer lists all contain the same elements.
+It is only the order of those elements that is different.
+
+ - Function: buffer-list &optional frame
+ This function returns a list of all buffers, including those whose
+ names begin with a space. The elements are actual buffers, not
+ their names. The order of the list is specific to FRAME, which
+ defaults to the current frame. If FRAME is `t', the global,
+ non-frame ordering is returned instead.
+
+ (buffer-list)
+ => (#<buffer buffers.texi>
+ #<buffer *Minibuf-1*> #<buffer buffer.c>
+ #<buffer *Help*> #<buffer TAGS>)
+
+ ;; Note that the name of the minibuffer
+ ;; begins with a space!
+ (mapcar (function buffer-name) (buffer-list))
+ => ("buffers.texi" " *Minibuf-1*"
+ "buffer.c" "*Help*" "TAGS")
+
+ Buffers appear earlier in the list if they were current more
+ recently.
+
+ This list is a copy of a list used inside XEmacs; modifying it has
+ no effect on the buffers.
+
+ - Function: other-buffer &optional buffer-or-name frame visible-ok
+ This function returns the first buffer in the buffer list other
+ than BUFFER-OR-NAME, in FRAME's ordering for the buffer list.
+ (FRAME defaults to the current frame. If FRAME is `t', then the
+ global, non-frame ordering is used.) Usually this is the buffer
+ most recently shown in the selected window, aside from
+ BUFFER-OR-NAME. Buffers are moved to the front of the list when
+ they are selected and to the end when they are buried. Buffers
+ whose names start with a space are not considered.
+
+ If BUFFER-OR-NAME is not supplied (or if it is not a buffer), then
+ `other-buffer' returns the first buffer on the buffer list that is
+ not visible in any window in a visible frame.
+
+ If the selected frame has a non-`nil' `buffer-predicate' property,
+ then `other-buffer' uses that predicate to decide which buffers to
+ consider. It calls the predicate once for each buffer, and if the
+ value is `nil', that buffer is ignored. *Note X Frame
+ Properties::.
+
+ If VISIBLE-OK is `nil', `other-buffer' avoids returning a buffer
+ visible in any window on any visible frame, except as a last
+ resort. If VISIBLE-OK is non-`nil', then it does not matter
+ whether a buffer is displayed somewhere or not.
+
+ If no suitable buffer exists, the buffer `*scratch*' is returned
+ (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.
+
+ - Command: list-buffers &optional files-only
+ This function displays a listing of the names of existing buffers.
+ It clears the buffer `*Buffer List*', then inserts the listing
+ into that buffer and displays it in a window. `list-buffers' is
+ intended for interactive use, and is described fully in `The XEmacs
+ Reference Manual'. It returns `nil'.
+
+ - Command: bury-buffer &optional buffer-or-name before
+ This function puts BUFFER-OR-NAME at the end of the buffer list
+ without changing the order of any of the other buffers on the list.
+ This buffer therefore becomes the least desirable candidate for
+ `other-buffer' to return.
+
+ If BUFFER-OR-NAME is `nil' or omitted, this means to bury the
+ current buffer. In addition, if the buffer is displayed in the
+ selected window, this switches to some other buffer (obtained using
+ `other-buffer') in the selected window. But if the buffer is
+ displayed in some other window, it remains displayed there.
+
+ 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: String Properties, Next: Formatting Strings, Prev: Modifying Strings, Up: Strings and Characters
+File: lispref.info, Node: Creating Buffers, Next: Killing Buffers, Prev: The Buffer List, Up: Buffers
-String Properties
-=================
+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>
- Just as with symbols, extents, faces, and glyphs, you can attach
-additional information to strings in the form of "string properties".
-These differ from text properties, which are logically attached to
-particular characters in the string.
+ 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::.
- To attach a property to a string, use `put'. To retrieve a property
-from a string, use `get'. You can also use `remprop' to remove a
-property from a string and `object-plist' to retrieve a list of all the
-properties in a string.
+ - 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: Formatting Strings, Next: Character Case, Prev: String Properties, Up: Strings and Characters
+File: lispref.info, Node: Killing Buffers, Next: Indirect Buffers, Prev: Creating Buffers, Up: Buffers
-Formatting Strings
-==================
+Killing Buffers
+===============
- "Formatting" means constructing a string by substitution of computed
-values at various places in a constant string. This string controls
-how the other values are printed as well as where they appear; it is
-called a "format string".
-
- Formatting is often useful for computing messages to be displayed.
-In fact, the functions `message' and `error' provide the same
-formatting feature described here; they differ from `format' only in
-how they use the result of formatting.
-
- - Function: format string &rest objects
- This function returns a new string that is made by copying STRING
- and then replacing any format specification in the copy with
- encodings of the corresponding OBJECTS. The arguments OBJECTS are
- the computed values to be formatted.
-
- A format specification is a sequence of characters beginning with a
-`%'. Thus, if there is a `%d' in STRING, the `format' function
-replaces it with the printed representation of one of the values to be
-formatted (one of the arguments OBJECTS). For example:
-
- (format "The value of fill-column is %d." fill-column)
- => "The value of fill-column is 72."
-
- If STRING contains more than one format specification, the format
-specifications correspond with successive values from OBJECTS. Thus,
-the first format specification in STRING uses the first such value, the
-second format specification uses the second such value, and so on. Any
-extra format specifications (those for which there are no corresponding
-values) cause unpredictable behavior. Any extra values to be formatted
-are ignored.
-
- Certain format specifications require values of particular types.
-However, no error is signaled if the value actually supplied fails to
-have the expected type. Instead, the output is likely to be
-meaningless.
-
- Here is a table of valid format specifications:
-
-`%s'
- Replace the specification with the printed representation of the
- object, made without quoting. Thus, strings are represented by
- their contents alone, with no `"' characters, and symbols appear
- without `\' characters. This is equivalent to printing the object
- with `princ'.
-
- If there is no corresponding object, the empty string is used.
-
-`%S'
- Replace the specification with the printed representation of the
- object, made with quoting. Thus, strings are enclosed in `"'
- characters, and `\' characters appear where necessary before
- special characters. This is equivalent to printing the object
- with `prin1'.
-
- If there is no corresponding object, the empty string is used.
-
-`%o'
- Replace the specification with the base-eight representation of an
- integer.
-
-`%d'
-`%i'
- Replace the specification with the base-ten representation of an
- integer.
-
-`%x'
- Replace the specification with the base-sixteen representation of
- an integer, using lowercase letters.
-
-`%X'
- Replace the specification with the base-sixteen representation of
- an integer, using uppercase letters.
-
-`%c'
- Replace the specification with the character which is the value
- given.
-
-`%e'
- Replace the specification with the exponential notation for a
- floating point number (e.g. `7.85200e+03').
-
-`%f'
- Replace the specification with the decimal-point notation for a
- floating point number.
-
-`%g'
- Replace the specification with notation for a floating point
- number, using a "pretty format". Either exponential notation or
- decimal-point notation will be used (usually whichever is
- shorter), and trailing zeroes are removed from the fractional part.
-
-`%%'
- A single `%' is placed in the string. This format specification is
- unusual in that it does not use a value. For example, `(format "%%
- %d" 30)' returns `"% 30"'.
-
- Any other format character results in an `Invalid format operation'
-error.
-
- Here are several examples:
-
- (format "The name of this buffer is %s." (buffer-name))
- => "The name of this buffer is strings.texi."
-
- (format "The buffer object prints as %s." (current-buffer))
- => "The buffer object prints as #<buffer strings.texi>."
-
- (format "The octal value of %d is %o,
- and the hex value is %x." 18 18 18)
- => "The octal value of 18 is 22,
- and the hex value is 12."
+"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 object
+ This function returns `t' if OBJECT is an editor buffer that has
+ not been deleted, `nil' 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'. The argument BUFFER-OR-NAME may be a buffer or
+ the name of one.
+
+ 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
- There are many additional flags and specifications that can occur
-between the `%' and the format character, in the following order:
+ - 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::.
- 1. An optional repositioning specification, which is a positive
- integer followed by a `$'.
+\1f
+File: lispref.info, Node: Indirect Buffers, Prev: Killing Buffers, Up: Buffers
- 2. Zero or more of the optional flag characters `-', `+', ` ', `0',
- and `#'.
+Indirect Buffers
+================
- 3. An asterisk (`*', meaning that the field width is now assumed to
- have been specified as an argument.
+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".
- 4. An optional minimum field width.
+ 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.
- 5. An optional precision, preceded by a `.' character.
+ 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.
- A "repositioning" specification changes which argument to `format'
-is used by the current and all following format specifications.
-Normally the first specification uses the first argument, the second
-specification uses the second argument, etc. Using a repositioning
-specification, you can change this. By placing a number N followed by
-a `$' between the `%' and the format character, you cause the
-specification to use the Nth argument. The next specification will use
-the N+1'th argument, etc.
+ 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.
- For example:
+ Killing an indirect buffer has no effect on its base buffer. Killing
+the base buffer kills all its indirect children.
- (format "Can't find file `%s' in directory `%s'."
- "ignatius.c" "loyola/")
- => "Can't find file `ignatius.c' in directory `loyola/'."
-
- (format "In directory `%2$s', the file `%1$s' was not found."
- "ignatius.c" "loyola/")
- => "In directory `loyola/', the file `ignatius.c' was not found."
-
- (format
- "The numbers %d and %d are %1$x and %x in hex and %1$o and %o in octal."
- 37 12)
- => "The numbers 37 and 12 are 25 and c in hex and 45 and 14 in octal."
-
- As you can see, this lets you reprocess arguments more than once or
-reword a format specification (thereby moving the arguments around)
-without having to actually reorder the arguments. This is especially
-useful in translating messages from one language to another: Different
-languages use different word orders, and this sometimes entails changing
-the order of the arguments. By using repositioning specifications,
-this can be accomplished without having to embed knowledge of particular
-languages into the location in the program's code where the message is
-displayed.
-
- All the specification characters allow an optional numeric prefix
-between the `%' and the character, and following any repositioning
-specification or flag. The optional numeric prefix defines the minimum
-width for the object. If the printed representation of the object
-contains fewer characters than this, then it is padded. The padding is
-normally on the left, but will be on the right if the `-' flag
-character is given. The padding character is normally a space, but if
-the `0' flag character is given, zeros are used for padding.
-
- (format "%06d is padded on the left with zeros" 123)
- => "000123 is padded on the left with zeros"
-
- (format "%-6d is padded on the right" 123)
- => "123 is padded on the right"
-
- `format' never truncates an object's printed representation, no
-matter what width you specify. Thus, you can use a numeric prefix to
-specify a minimum spacing between columns with no risk of losing
-information.
-
- In the following three examples, `%7s' specifies a minimum width of
-7. In the first case, the string inserted in place of `%7s' has only 3
-letters, so 4 blank spaces are inserted for padding. In the second
-case, the string `"specification"' is 13 letters wide but is not
-truncated. In the third case, the padding is on the right.
-
- (format "The word `%7s' actually has %d letters in it."
- "foo" (length "foo"))
- => "The word ` foo' actually has 3 letters in it."
-
- (format "The word `%7s' actually has %d letters in it."
- "specification" (length "specification"))
- => "The word `specification' actually has 13 letters in it."
-
- (format "The word `%-7s' actually has %d letters in it."
- "foo" (length "foo"))
- => "The word `foo ' actually has 3 letters in it."
+ - 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.
- After any minimum field width, a precision may be specified by
-preceding it with a `.' character. The precision specifies the minimum
-number of digits to appear in `%d', `%i', `%o', `%x', and `%X'
-conversions (the number is padded on the left with zeroes as
-necessary); the number of digits printed after the decimal point for
-`%f', `%e', and `%E' conversions; the number of significant digits
-printed in `%g' and `%G' conversions; and the maximum number of
-non-padding characters printed in `%s' and `%S' conversions. The
-default precision for floating-point conversions is six.
+ (make-indirect-buffer "*scratch*" "indirect")
+ => #<buffer "indirect">
- The other flag characters have the following meanings:
+ - 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.
- * The ` ' flag means prefix non-negative numbers with a space.
+ (buffer-base-buffer (get-buffer "indirect"))
+ => #<buffer "*scratch*">
- * The `+' flag means prefix non-negative numbers with a plus sign.
+ - 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.
- * The `#' flag means print numbers in an alternate, more verbose
- format: octal numbers begin with zero; hex numbers begin with a
- `0x' or `0X'; a decimal point is printed in `%f', `%e', and `%E'
- conversions even if no numbers are printed after it; and trailing
- zeroes are not omitted in `%g' and `%G' conversions.
+ (buffer-indirect-children (get-buffer "*scratch*"))
+ => (#<buffer "indirect">)
\1f
-File: lispref.info, Node: Character Case, Next: Case Tables, Prev: Formatting Strings, Up: Strings and Characters
+File: lispref.info, Node: Windows, Next: Frames, Prev: Buffers, Up: Top
-Character Case
-==============
+Windows
+*******
- The character case functions change the case of single characters or
-of the contents of strings. The functions convert only alphabetic
-characters (the letters `A' through `Z' and `a' through `z'); other
-characters are not altered. The functions do not modify the strings
-that are passed to them as arguments.
+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.
- The examples below use the characters `X' and `x' which have ASCII
-codes 88 and 120 respectively.
+* Menu:
- - Function: downcase string-or-char &optional buffer
- This function converts a character or a string to lower case.
+* 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.
- When the argument to `downcase' is a string, the function creates
- and returns a new string in which each letter in the argument that
- is upper case is converted to lower case. When the argument to
- `downcase' is a character, `downcase' returns the corresponding
- lower case character. (This value is actually an integer under
- XEmacs 19.) If the original character is lower case, or is not a
- letter, then the value equals the original character.
+\1f
+File: lispref.info, Node: Basic Windows, Next: Splitting Windows, Up: Windows
- Optional second arg BUFFER specifies which buffer's case tables to
- use, and defaults to the current buffer.
+Basic Concepts of Emacs Windows
+===============================
- (downcase "The cat in the hat")
- => "the cat in the hat"
-
- (downcase ?X)
- => ?x ;; Under XEmacs 20.
- => 120 ;; Under XEmacs 19.
+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.
- - Function: upcase string-or-char &optional buffer
- This function converts a character or a string to upper case.
+ 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.
- When the argument to `upcase' is a string, the function creates
- and returns a new string in which each letter in the argument that
- is lower case is converted to upper case.
+ 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::.
- When the argument to `upcase' is a character, `upcase' returns the
- corresponding upper case character. (This value is actually an
- integer under XEmacs 19.) If the original character is upper
- case, or is not a letter, then the value equals the original
- character.
+ 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::.)
- Optional second arg BUFFER specifies which buffer's case tables to
- use, and defaults to the current buffer.
+ Each window has the following attributes:
- (upcase "The cat in the hat")
- => "THE CAT IN THE HAT"
-
- (upcase ?x)
- => ?X ;; Under XEmacs 20.
- => 88 ;; Under XEmacs 19.
-
- - Function: capitalize string-or-char &optional buffer
- This function capitalizes strings or characters. If
- STRING-OR-CHAR is a string, the function creates and returns a new
- string, whose contents are a copy of STRING-OR-CHAR in which each
- word has been capitalized. This means that the first character of
- each word is converted to upper case, and the rest are converted
- to lower case.
-
- The definition of a word is any sequence of consecutive characters
- that are assigned to the word constituent syntax class in the
- current syntax table (*note Syntax Class Table::).
-
- When the argument to `capitalize' is a character, `capitalize' has
- the same result as `upcase'.
-
- Optional second arg BUFFER specifies which buffer's case tables to
- use, and defaults to the current buffer.
-
- (capitalize "The cat in the hat")
- => "The Cat In The Hat"
-
- (capitalize "THE 77TH-HATTED CAT")
- => "The 77th-Hatted Cat"
+ * 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 nomini which-frames which-devices
+ This function returns non-`nil' if there is only one window. The
+ argument NOMINI, 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 remaining arguments controls which set of windows are counted,
+ as with `next-window'.
+
+ - 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
- (capitalize ?x)
- => ?X ;; Under XEmacs 20.
- => 88 ;; Under XEmacs 19.
+ ;; 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-window'. 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-window'. 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))
\1f
-File: lispref.info, Node: Case Tables, Next: Char Tables, Prev: Character Case, Up: Strings and Characters
+File: lispref.info, Node: Deleting Windows, Next: Selecting Windows, Prev: Splitting Windows, Up: Windows
-The Case Table
-==============
+Deleting Windows
+================
- You can customize case conversion by installing a special "case
-table". A case table specifies the mapping between upper case and lower
-case letters. It affects both the string and character case conversion
-functions (see the previous section) and those that apply to text in the
-buffer (*note Case Changes::). You need a case table if you are using a
-language which has letters other than the standard ASCII letters.
+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.
- A case table is a list of this form:
+ 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.)
- (DOWNCASE UPCASE CANONICALIZE EQUIVALENCES)
+ - Function: window-live-p window
+ This function returns `nil' if WINDOW is deleted, and `t'
+ otherwise.
-where each element is either `nil' or a string of length 256. The
-element DOWNCASE says how to map each character to its lower-case
-equivalent. The element UPCASE maps each character to its upper-case
-equivalent. If lower and upper case characters are in one-to-one
-correspondence, use `nil' for UPCASE; then XEmacs deduces the upcase
-table from DOWNCASE.
+ *Warning:* Erroneous information or fatal errors may result from
+ using a deleted window as if it were live.
- For some languages, upper and lower case letters are not in
-one-to-one correspondence. There may be two different lower case
-letters with the same upper case equivalent. In these cases, you need
-to specify the maps for both directions.
+ - Command: delete-window &optional window force
+ This function removes WINDOW from the display. If WINDOW is
+ omitted, then the selected window is deleted. If window is the
+ only one on its frame, the frame is deleted as well.
- The element CANONICALIZE maps each character to a canonical
-equivalent; any two characters that are related by case-conversion have
-the same canonical equivalent character.
+ Normally, you cannot delete the last non-minibuffer-only frame
+ (you must use `save-buffers-kill-emacs' or `kill-emacs'); an error
+ is signaled instead. However, if optional second argument FORCE is
+ non-`nil', you can delete the last frame. (This will automatically
+ call `save-buffers-kill-emacs'.)
- The element EQUIVALENCES is a map that cyclicly permutes each
-equivalence class (of characters with the same canonical equivalent).
-(For ordinary ASCII, this would map `a' into `A' and `A' into `a', and
-likewise for each set of equivalent characters.)
+ This function returns `nil'.
- When you construct a case table, you can provide `nil' for
-CANONICALIZE; then Emacs fills in this string from UPCASE and DOWNCASE.
-You can also provide `nil' for EQUIVALENCES; then Emacs fills in this
-string from CANONICALIZE. In a case table that is actually in use,
-those components are non-`nil'. Do not try to specify EQUIVALENCES
-without also specifying CANONICALIZE.
+ When `delete-window' is called interactively, the selected window
+ is deleted.
- Each buffer has a case table. XEmacs also has a "standard case
-table" which is copied into each buffer when you create the buffer.
-Changing the standard case table doesn't affect any existing buffers.
+ - 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.
- Here are the functions for working with case tables:
+ The result is `nil'.
- - Function: case-table-p object
- This predicate returns non-`nil' if OBJECT is a valid case table.
+ - Command: delete-windows-on buffer &optional which-frames
+ which-devices
+ This function deletes all windows showing BUFFER. If there are no
+ windows showing BUFFER, it does nothing.
- - Function: set-standard-case-table case-table
- This function makes CASE-TABLE the standard case table, so that it
- will apply to any buffers created subsequently.
+ `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::.
- - Function: standard-case-table
- This returns the standard case table.
+ The argument WHICH-FRAMES controls which frames to operate on:
- - Function: current-case-table &optional buffer
- This function returns the case table of BUFFER, which defaults to
- the current buffer.
+ `nil'
+ Delete all windows showing BUFFER in any frame.
+
+ `t'
+ Delete only windows showing BUFFER in the selected frame.
+
+ `visible'
+ Delete all windows showing BUFFER in any visible frame.
+
+ `0'
+ Delete all windows showing BUFFER in any visible frame.
- - Function: set-case-table case-table
- This sets the current buffer's case table to CASE-TABLE.
+ FRAME
+ If it is a frame, delete all windows showing BUFFER in that
+ frame.
- The following three functions are convenient subroutines for packages
-that define non-ASCII character sets. They modify a string
-DOWNCASE-TABLE provided as an argument; this should be a string to be
-used as the DOWNCASE part of a case table. They also modify the
-standard syntax table. *Note Syntax Tables::.
+ *Warning:* This is similar to, but not identical to, the meaning
+ of the WHICH-FRAMES argument to `next-window'; the meanings of
+ `nil' and `t' are reversed.
- - Function: set-case-syntax-pair uc lc downcase-table
- This function specifies a pair of corresponding letters, one upper
- case and one lower case.
+ The optional argument WHICH-DEVICES further clarifies on which
+ devices to search for frames as specified by WHICH-FRAMES. This
+ value is only meaningful if WHICH-FRAMES is not `t'.
- - Function: set-case-syntax-delims l r downcase-table
- This function makes characters L and R a matching pair of
- case-invariant delimiters.
+ `nil'
+ Consider all devices on the selected console.
- - Function: set-case-syntax char syntax downcase-table
- This function makes CHAR case-invariant, with syntax SYNTAX.
+ DEVICE
+ Consider only the one device DEVICE.
- - Command: describe-buffer-case-table
- This command displays a description of the contents of the current
- buffer's case table.
+ CONSOLE
+ Consider all devices on CONSOLE.
- You can load the library `iso-syntax' to set up the standard syntax
-table and define a case table for the 8-bit ISO Latin 1 character set.
+ DEVICE-TYPE
+ Consider all devices with device type DEVICE-TYPE.
+
+ `window-system'
+ Consider all devices on window system consoles.
+
+ anything else
+ Consider all devices without restriction.
+
+ This function always returns `nil'.
\1f
-File: lispref.info, Node: Char Tables, Prev: Case Tables, Up: Strings and Characters
+File: lispref.info, Node: Selecting Windows, Next: Cyclic Window Ordering, Prev: Deleting Windows, Up: Windows
-The Char Table
-==============
+Selecting Windows
+=================
- A char table is a table that maps characters (or ranges of
-characters) to values. Char tables are specialized for characters,
-only allowing particular sorts of ranges to be assigned values.
-Although this loses in generality, it makes for extremely fast
-(constant-time) lookups, and thus is feasible for applications that do
-an extremely large number of lookups (e.g. scanning a buffer for a
-character in a particular syntax, where a lookup in the syntax table
-must occur once per character).
+When a window is selected, the buffer in the window becomes the current
+buffer, and the cursor will appear in it.
- Note that char tables as a primitive type, and all of the functions
-in this section, exist only in XEmacs 20. In XEmacs 19, char tables are
-generally implemented using a vector of 256 elements.
+ - Function: selected-window &optional device
+ This function returns the selected window. This is the window in
+ which the cursor appears and to which many commands apply. Each
+ separate device can have its own selected window, which is
+ remembered as focus changes from device to device. Optional
+ argument DEVICE specifies which device to return the selected
+ window for, and defaults to the selected device.
- When MULE support exists, the types of ranges that can be assigned
-values are
+ - Function: select-window window &optional norecord
+ This function makes WINDOW the selected window. The cursor then
+ appears in WINDOW (on redisplay). The buffer being displayed in
+ WINDOW is immediately designated the current buffer.
- * all characters
+ If optional argument NORECORD is non-`nil' then the global and
+ per-frame buffer orderings are not modified, as by the function
+ `record-buffer'.
- * an entire charset
+ The return value is WINDOW.
- * a single row in a two-octet charset
+ (setq w (next-window))
+ (select-window w)
+ => #<window 65 on windows.texi>
- * a single character
+ - Special Form: save-selected-window forms...
+ This special form records the selected window, executes FORMS in
+ sequence, then restores the earlier selected window. It does not
+ save or restore anything about the sizes, arrangement or contents
+ of windows; therefore, if the FORMS change them, the changes are
+ permanent.
- When MULE support is not present, the types of ranges that can be
-assigned values are
+ The following functions choose one of the windows on the screen,
+offering various criteria for the choice.
- * all characters
+ - Function: get-lru-window &optional which-frames which-devices
+ This function returns the window least recently "used" (that is,
+ selected). The selected window is always the most recently used
+ window.
- * a single character
+ The selected window can be the least recently used window if it is
+ the only window. A newly created window becomes the least
+ recently used window until it is selected. A minibuffer window is
+ never a candidate.
- - Function: char-table-p object
- This function returns non-`nil' if OBJECT is a char table.
+ By default, only the windows in the selected frame are considered.
+ The optional argument WHICH-FRAMES changes this behavior. Here
+ are the possible values and their meanings:
-* Menu:
+ `nil'
+ Consider all the windows in the selected windows's frame,
+ plus the minibuffer used by that frame even if it lies in
+ some other frame.
+
+ `t'
+ Consider all windows in all existing frames.
+
+ `visible'
+ Consider all windows in all visible frames. (To get useful
+ results, you must ensure WINDOW is in a visible frame.)
+
+ `0'
+ Consider all windows in all visible or iconified frames.
+
+ FRAME
+ Consider all windows on frame FRAME.
+
+ anything else
+ Consider precisely the windows in the selected window's
+ frame, and no others.
+
+ The optional argument WHICH-DEVICES further clarifies on which
+ devices to search for frames as specified by WHICH-FRAMES. This
+ value is only meaningful if WHICH-FRAMES is non-`nil'.
-* Char Table Types:: Char tables have different uses.
-* Working With Char Tables:: Creating and working with char tables.
+ `nil'
+ Consider all devices on the selected console.
+
+ DEVICE
+ Consider only the one device DEVICE.
+
+ CONSOLE
+ Consider all devices on CONSOLE.
+
+ DEVICE-TYPE
+ Consider all devices with device type DEVICE-TYPE.
+
+ `window-system'
+ Consider all devices on window system consoles.
+
+ anything else
+ Consider all devices without restriction.
+
+
+ - Function: get-largest-window &optional which-frames which-devices
+ This function returns the window with the largest area (height
+ times width). If there are no side-by-side windows, then this is
+ the window with the most lines. A minibuffer window is never a
+ candidate.
+
+ If there are two windows of the same size, then the function
+ returns the window that is first in the cyclic ordering of windows
+ (see following section), starting from the selected window.
+
+ The remaining arguments control which set of windows are
+ considered. See `next-window', above.
\1f
-File: lispref.info, Node: Char Table Types, Next: Working With Char Tables, Up: Char Tables
+File: lispref.info, Node: Cyclic Window Ordering, Next: Buffers and Windows, Prev: Selecting Windows, Up: Windows
+
+Cyclic Ordering of Windows
+==========================
-Char Table Types
-----------------
+When you use the command `C-x o' (`other-window') to select the next
+window, it moves through all the windows on the screen in a specific
+cyclic order. For any given configuration of windows, this order never
+varies. It is called the "cyclic ordering of windows".
+
+ This ordering generally goes from top to bottom, and from left to
+right. But it may go down first or go right first, depending on the
+order in which the windows were split.
+
+ If the first split was vertical (into windows one above each other),
+and then the subwindows were split horizontally, then the ordering is
+left to right in the top of the frame, and then left to right in the
+next lower part of the frame, and so on. If the first split was
+horizontal, the ordering is top to bottom in the left part, and so on.
+In general, within each set of siblings at any level in the window tree,
+the order is left to right, or top to bottom.
- Each char table type is used for a different purpose and allows
-different sorts of values. The different char table types are
+ - Function: next-window &optional window minibuf which-frames
+ which-devices
+ This function returns the window following WINDOW in the cyclic
+ ordering of windows. This is the window that `C-x o' would select
+ if typed when WINDOW is selected. If WINDOW is the only window
+ visible, then this function returns WINDOW. If omitted, WINDOW
+ defaults to the selected window.
-`category'
- Used for category tables, which specify the regexp categories that
- a character is in. The valid values are `nil' or a bit vector of
- 95 elements. Higher-level Lisp functions are provided for working
- with category tables. Currently categories and category tables
- only exist when MULE support is present.
+ The value of the argument MINIBUF determines whether the
+ minibuffer is included in the window order. Normally, when
+ MINIBUF is `nil', the minibuffer is included if it is currently
+ active; this is the behavior of `C-x o'. (The minibuffer window
+ is active while the minibuffer is in use. *Note Minibuffers::.)
-`char'
- A generalized char table, for mapping from one character to
- another. Used for case tables, syntax matching tables,
- `keyboard-translate-table', etc. The valid values are characters.
+ If MINIBUF is `t', then the cyclic ordering includes the
+ minibuffer window even if it is not active.
-`generic'
- An even more generalized char table, for mapping from a character
- to anything.
+ If MINIBUF is neither `t' nor `nil', then the minibuffer window is
+ not included even if it is active.
-`display'
- Used for display tables, which specify how a particular character
- is to appear when displayed. #### Not yet implemented.
+ By default, only the windows in the selected frame are considered.
+ The optional argument WHICH-FRAMES changes this behavior. Here
+ are the possible values and their meanings:
+
+ `nil'
+ Consider all the windows in WINDOW's frame, plus the
+ minibuffer used by that frame even if it lies in some other
+ frame.
+
+ `t'
+ Consider all windows in all existing frames.
+
+ `visible'
+ Consider all windows in all visible frames. (To get useful
+ results, you must ensure WINDOW is in a visible frame.)
+
+ `0'
+ Consider all windows in all visible or iconified frames.
-`syntax'
- Used for syntax tables, which specify the syntax of a particular
- character. Higher-level Lisp functions are provided for working
- with syntax tables. The valid values are integers.
+ FRAME
+ Consider all windows on frame FRAME.
- - Function: char-table-type char-table
- This function returns the type of char table CHAR-TABLE.
+ anything else
+ Consider precisely the windows in WINDOW's frame, and no
+ others.
- - Function: char-table-type-list
- This function returns a list of the recognized char table types.
+ The optional argument WHICH-DEVICES further clarifies on which
+ devices to search for frames as specified by WHICH-FRAMES. This
+ value is only meaningful if WHICH-FRAMES is non-`nil'.
- - Function: valid-char-table-type-p type
- This function returns `t' if TYPE if a recognized char table type.
+ `nil'
+ Consider all devices on the selected console.
+
+ DEVICE
+ Consider only the one device DEVICE.
+
+ CONSOLE
+ Consider all devices on CONSOLE.
+
+ DEVICE-TYPE
+ Consider all devices with device type DEVICE-TYPE.
+
+ `window-system'
+ Consider all devices on window system consoles.
+
+ anything else
+ Consider all devices without restriction.
+
+ If you use consistent values for MINIBUF, WHICH-FRAMES, and
+ WHICH-DEVICES, you can use `next-window' to iterate through the
+ entire cycle of acceptable windows, eventually ending up back at
+ the window you started with. `previous-window' traverses the same
+ cycle, in the reverse order.
+
+ This example assumes there are two windows, both displaying the
+ buffer `windows.texi':
+
+ (selected-window)
+ => #<window 56 on windows.texi>
+ (next-window (selected-window))
+ => #<window 52 on windows.texi>
+ (next-window (next-window (selected-window)))
+ => #<window 56 on windows.texi>
+
+ - Function: previous-window &optional window minibuf which-frames
+ which-devices
+ This function returns the window preceding WINDOW in the cyclic
+ ordering of windows. The other arguments specify which windows to
+ include in the cycle, as in `next-window'.
+
+ - Command: other-window count &optional which-frames which-devices
+ This function selects the COUNTth following window in the cyclic
+ order. If COUNT is negative, then it selects the -COUNTth
+ preceding window. It returns `nil'.
+
+ In an interactive call, COUNT is the numeric prefix argument.
+
+ The other arguments specify which windows to include in the cycle,
+ as in `next-window'.
+
+ - Function: walk-windows function &optional minibuf which-frames
+ which-devices
+ This function cycles through all windows, calling `function' once
+ for each window with the window as its sole argument.
+
+ The other arguments specify which windows to cycle through, as in
+ `next-window'.
\1f
-File: lispref.info, Node: Working With Char Tables, Prev: Char Table Types, Up: Char Tables
+File: lispref.info, Node: Buffers and Windows, Next: Displaying Buffers, Prev: Cyclic Window Ordering, Up: Windows
-Working With Char Tables
-------------------------
+Buffers and Windows
+===================
- - Function: make-char-table type
- This function makes a new, empty char table of type TYPE. TYPE
- should be a symbol, one of `char', `category', `display',
- `generic', or `syntax'.
+This section describes low-level functions to examine windows or to
+display buffers in windows in a precisely controlled fashion. *Note
+Displaying Buffers::, for related functions that find a window to use
+and specify a buffer for it. The functions described there are easier
+to use than these, but they employ heuristics in choosing or creating a
+window; use these functions when you need complete control.
- - Function: put-char-table range value char-table
- This function sets the value for chars in RANGE to be VALUE in
- CHAR-TABLE.
+ - Function: set-window-buffer window buffer-or-name &optional norecord
+ This function makes WINDOW display BUFFER-OR-NAME as its contents.
+ BUFFER-OR-NAME can be a buffer or a buffer name.
- RANGE specifies one or more characters to be affected and should be
- one of the following:
+ With non-`nil' optional argument NORECORD, do not modify the
+ global or per-frame buffer ordering.
- * `t' (all characters are affected)
+ This function returns `nil'.
- * A charset (only allowed when MULE support is present)
+ (set-window-buffer (selected-window) "foo")
+ => nil
- * A vector of two elements: a two-octet charset and a row number
- (only allowed when MULE support is present)
+ - Function: window-buffer &optional window
+ This function returns the buffer that WINDOW is displaying. If
+ WINDOW is omitted, this function returns the buffer for the
+ selected window.
- * A single character
+ (window-buffer)
+ => #<buffer windows.texi>
- VALUE must be a value appropriate for the type of CHAR-TABLE.
+ - Function: get-buffer-window buffer-or-name &optional which-frames
+ which-devices
+ This function returns a window currently displaying
+ BUFFER-OR-NAME, or `nil' if there is none. If there are several
+ such windows, then the function returns the first one in the
+ cyclic ordering of windows, starting from the selected window.
+ *Note Cyclic Window Ordering::.
- - Function: get-char-table character char-table
- This function finds the value for CHARACTER in CHAR-TABLE.
+ The remaining arguments control which windows to consider. They
+ have the same meaning as for `next-window'.
- - Function: get-range-char-table range char-table &optional multi
- This function finds the value for a range in CHAR-TABLE. If there
- is more than one value, MULTI is returned (defaults to `nil').
+\1f
+File: lispref.info, Node: Displaying Buffers, Next: Choosing Window, Prev: Buffers and Windows, Up: Windows
- - Function: reset-char-table char-table
- This function resets CHAR-TABLE to its default state.
+Displaying Buffers in Windows
+=============================
- - Function: map-char-table function char-table &optional range
- This function maps FUNCTION over entries in CHAR-TABLE, calling it
- with two args, each key and value in the table.
+In this section we describe convenient functions that choose a window
+automatically and use it to display a specified buffer. These functions
+can also split an existing window in certain circumstances. We also
+describe variables that parameterize the heuristics used for choosing a
+window. *Note Buffers and Windows::, for low-level functions that give
+you more precise control.
+
+ Do not use the functions in this section in order to make a buffer
+current so that a Lisp program can access or modify it; they are too
+drastic for that purpose, since they change the display of buffers in
+windows, which is gratuitous and will surprise the user. Instead, use
+`set-buffer' (*note Current Buffer::) and `save-excursion' (*note
+Excursions::), which designate buffers as current for programmed access
+without affecting the display of buffers in windows.
+
+ - Command: switch-to-buffer buffer-or-name &optional norecord
+ This function makes BUFFER-OR-NAME the current buffer, and also
+ displays the buffer in the selected window. This means that a
+ human can see the buffer and subsequent keyboard commands will
+ apply to it. Contrast this with `set-buffer', which makes
+ BUFFER-OR-NAME the current buffer but does not display it in the
+ selected window. *Note Current Buffer::.
+
+ If BUFFER-OR-NAME does not identify an existing buffer, then a new
+ buffer by that name is created. The major mode for the new buffer
+ is set according to the variable `default-major-mode'. *Note Auto
+ Major Mode::.
+
+ Normally the specified buffer is put at the front of the buffer
+ list. This affects the operation of `other-buffer'. However, if
+ NORECORD is non-`nil', this is not done. *Note The Buffer List::.
+
+ The `switch-to-buffer' function is often used interactively, as
+ the binding of `C-x b'. It is also used frequently in programs.
+ It always returns `nil'.
+
+ - Command: switch-to-buffer-other-window buffer-or-name
+ This function makes BUFFER-OR-NAME the current buffer and displays
+ it in a window not currently selected. It then selects that
+ window. The handling of the buffer is the same as in
+ `switch-to-buffer'.
+
+ The currently selected window is absolutely never used to do the
+ job. If it is the only window, then it is split to make a
+ distinct window for this purpose. If the selected window is
+ already displaying the buffer, then it continues to do so, but
+ another window is nonetheless found to display it in as well.
+
+ - Function: pop-to-buffer buffer-or-name &optional other-window
+ on-frame
+ This function makes BUFFER-OR-NAME the current buffer and switches
+ to it in some window, preferably not the window previously
+ selected. The "popped-to" window becomes the selected window
+ within its frame.
+
+ If the variable `pop-up-frames' is non-`nil', `pop-to-buffer'
+ looks for a window in any visible frame already displaying the
+ buffer; if there is one, it returns that window and makes it be
+ selected within its frame. If there is none, it creates a new
+ frame and displays the buffer in it.
+
+ If `pop-up-frames' is `nil', then `pop-to-buffer' operates
+ entirely within the selected frame. (If the selected frame has
+ just a minibuffer, `pop-to-buffer' operates within the most
+ recently selected frame that was not just a minibuffer.)
+
+ If the variable `pop-up-windows' is non-`nil', windows may be
+ split to create a new window that is different from the original
+ window. For details, see *Note Choosing Window::.
+
+ If OTHER-WINDOW is non-`nil', `pop-to-buffer' finds or creates
+ another window even if BUFFER-OR-NAME is already visible in the
+ selected window. Thus BUFFER-OR-NAME could end up displayed in
+ two windows. On the other hand, if BUFFER-OR-NAME is already
+ displayed in the selected window and OTHER-WINDOW is `nil', then
+ the selected window is considered sufficient display for
+ BUFFER-OR-NAME, so that nothing needs to be done.
+
+ All the variables that affect `display-buffer' affect
+ `pop-to-buffer' as well. *Note Choosing Window::.
+
+ If BUFFER-OR-NAME is a string that does not name an existing
+ buffer, a buffer by that name is created. The major mode for the
+ new buffer is set according to the variable `default-major-mode'.
+ *Note Auto Major Mode::.
+
+ If ON-FRAME is non-`nil', it is the frame to pop to this buffer on.
+
+ An example use of this function is found at the end of *Note
+ Filter Functions::.
+
+ - Command: replace-buffer-in-windows buffer &optional which-frames
+ which-devices
+ This function replaces BUFFER with some other buffer in all
+ windows displaying it. The other buffer used is chosen with
+ `other-buffer'. In the usual applications of this function, you
+ don't care which other buffer is used; you just want to make sure
+ that BUFFER is no longer displayed.
+
+ The optional arguments WHICH-FRAMES and WHICH-DEVICES have the
+ same meaning as with `delete-windows-on'.
+
+ This function returns `nil'.
- RANGE specifies a subrange to map over and is in the same format
- as the RANGE argument to `put-range-table'. If omitted or `t', it
- defaults to the entire table.
+\1f
+File: lispref.info, Node: Choosing Window, Next: Window Point, Prev: Displaying Buffers, Up: Windows
- - Function: valid-char-table-value-p value char-table-type
- This function returns non-`nil' if VALUE is a valid value for
- CHAR-TABLE-TYPE.
+Choosing a Window for Display
+=============================
- - Function: check-valid-char-table-value value char-table-type
- This function signals an error if VALUE is not a valid value for
- CHAR-TABLE-TYPE.
+This section describes the basic facility that chooses a window to
+display a buffer in--`display-buffer'. All the higher-level functions
+and commands use this subroutine. Here we describe how to use
+`display-buffer' and how to customize it.
+
+ - Command: display-buffer buffer-or-name &optional not-this-window
+ override-frame
+ This command makes BUFFER-OR-NAME appear in some window, like
+ `pop-to-buffer', but it does not select that window and does not
+ make the buffer current. The identity of the selected window is
+ unaltered by this function.
+
+ BUFFER-OR-NAME can be a buffer or the name of one.
+
+ If NOT-THIS-WINDOW is non-`nil', it means to display the specified
+ buffer in a window other than the selected one, even if it is
+ already on display in the selected window. This can cause the
+ buffer to appear in two windows at once. Otherwise, if
+ BUFFER-OR-NAME is already being displayed in any window, that is
+ good enough, so this function does nothing.
+
+ If OVERRIDE-FRAME is non-`nil', display on that frame instead of
+ the current frame (or the dedicated frame).
+
+ `display-buffer' returns the window chosen to display
+ BUFFER-OR-NAME.
+
+ Precisely how `display-buffer' finds or creates a window depends on
+ the variables described below.
+
+ A window can be marked as "dedicated" to a particular buffer. Then
+XEmacs will not automatically change which buffer appears in the
+window, such as `display-buffer' might normally do.
+
+ - Function: window-dedicated-p window
+ This function returns WINDOW's dedicated object, usually `t' or
+ `nil'.
+
+ - Function: set-window-buffer-dedicated window buffer
+ This function makes WINDOW display BUFFER and be dedicated to that
+ buffer. Then XEmacs will not automatically change which buffer
+ appears in WINDOW. If BUFFER is `nil', this function makes WINDOW
+ not be dedicated (but doesn't change which buffer appears in it
+ currently).
+
+ - User Option: pop-up-windows
+ This variable controls whether `display-buffer' makes new windows.
+ If it is non-`nil' and there is only one window, then that window
+ is split. If it is `nil', then `display-buffer' does not split
+ the single window, but uses it whole.
+
+ - User Option: split-height-threshold
+ This variable determines when `display-buffer' may split a window,
+ if there are multiple windows. `display-buffer' always splits the
+ largest window if it has at least this many lines. If the largest
+ window is not this tall, it is split only if it is the sole window
+ and `pop-up-windows' is non-`nil'.
+
+ - User Option: pop-up-frames
+ This variable controls whether `display-buffer' makes new frames.
+ If it is non-`nil', `display-buffer' looks for an existing window
+ already displaying the desired buffer, on any visible frame. If
+ it finds one, it returns that window. Otherwise it makes a new
+ frame. The variables `pop-up-windows' and
+ `split-height-threshold' do not matter if `pop-up-frames' is
+ non-`nil'.
+
+ If `pop-up-frames' is `nil', then `display-buffer' either splits a
+ window or reuses one.
+
+ *Note Frames::, for more information.
+
+ - Variable: pop-up-frame-function
+ This variable specifies how to make a new frame if `pop-up-frames'
+ is non-`nil'.
+
+ Its value should be a function of no arguments. When
+ `display-buffer' makes a new frame, it does so by calling that
+ function, which should return a frame. The default value of the
+ variable is a function that creates a frame using properties from
+ `pop-up-frame-plist'.
+
+ - Variable: pop-up-frame-plist
+ This variable holds a plist specifying frame properties used when
+ `display-buffer' makes a new frame. *Note Frame Properties::, for
+ more information about frame properties.
+
+ - Variable: special-display-buffer-names
+ A list of buffer names for buffers that should be displayed
+ specially. If the buffer's name is in this list, `display-buffer'
+ handles the buffer specially.
+
+ By default, special display means to give the buffer a dedicated
+ frame.
+
+ If an element is a list, instead of a string, then the CAR of the
+ list is the buffer name, and the rest of the list says how to
+ create the frame. There are two possibilities for the rest of the
+ list. It can be a plist, specifying frame properties, or it can
+ contain a function and arguments to give to it. (The function's
+ first argument is always the buffer to be displayed; the arguments
+ from the list come after that.)
+
+ - Variable: special-display-regexps
+ A list of regular expressions that specify buffers that should be
+ displayed specially. If the buffer's name matches any of the
+ regular expressions in this list, `display-buffer' handles the
+ buffer specially.
+
+ By default, special display means to give the buffer a dedicated
+ frame.
+
+ If an element is a list, instead of a string, then the CAR of the
+ list is the regular expression, and the rest of the list says how
+ to create the frame. See above, under
+ `special-display-buffer-names'.
+
+ - Variable: special-display-function
+ This variable holds the function to call to display a buffer
+ specially. It receives the buffer as an argument, and should
+ return the window in which it is displayed.
+
+ The default value of this variable is
+ `special-display-popup-frame'.
+
+ - Function: special-display-popup-frame buffer
+ This function makes BUFFER visible in a frame of its own. If
+ BUFFER is already displayed in a window in some frame, it makes
+ the frame visible and raises it, to use that window. Otherwise, it
+ creates a frame that will be dedicated to BUFFER.
+
+ This function uses an existing window displaying BUFFER whether or
+ not it is in a frame of its own; but if you set up the above
+ variables in your init file, before BUFFER was created, then
+ presumably the window was previously made by this function.
+
+ - User Option: special-display-frame-plist
+ This variable holds frame properties for
+ `special-display-popup-frame' to use when it creates a frame.
+
+ - Variable: same-window-buffer-names
+ A list of buffer names for buffers that should be displayed in the
+ selected window. If the buffer's name is in this list,
+ `display-buffer' handles the buffer by switching to it in the
+ selected window.
+
+ - Variable: same-window-regexps
+ A list of regular expressions that specify buffers that should be
+ displayed in the selected window. If the buffer's name matches
+ any of the regular expressions in this list, `display-buffer'
+ handles the buffer by switching to it in the selected window.
+
+ - Variable: display-buffer-function
+ This variable is the most flexible way to customize the behavior of
+ `display-buffer'. If it is non-`nil', it should be a function
+ that `display-buffer' calls to do the work. The function should
+ accept two arguments, the same two arguments that `display-buffer'
+ received. It should choose or create a window, display the
+ specified buffer, and then return the window.
+
+ This hook takes precedence over all the other options and hooks
+ described above.
+
+ A window can be marked as "dedicated" to its buffer. Then
+`display-buffer' does not try to use that window.
+
+ - Function: window-dedicated-p window
+ This function returns `t' if WINDOW is marked as dedicated;
+ otherwise `nil'.
+
+ - Function: set-window-dedicated-p window flag
+ This function marks WINDOW as dedicated if FLAG is non-`nil', and
+ nondedicated otherwise.
\1f
-File: lispref.info, Node: Lists, Next: Sequences Arrays Vectors, Prev: Strings and Characters, Up: Top
+File: lispref.info, Node: Window Point, Next: Window Start, Prev: Choosing Window, Up: Windows
-Lists
-*****
+Windows and Point
+=================
- A "list" represents a sequence of zero or more elements (which may
-be any Lisp objects). The important difference between lists and
-vectors is that two or more lists can share part of their structure; in
-addition, you can insert or delete elements in a list without copying
-the whole list.
+Each window has its own value of point, independent of the value of
+point in other windows displaying the same buffer. This makes it useful
+to have multiple windows showing one buffer.
-* Menu:
+ * The window point is established when a window is first created; it
+ is initialized from the buffer's point, or from the window point
+ of another window opened on the buffer if such a window exists.
+
+ * Selecting a window sets the value of point in its buffer to the
+ window's value of point. Conversely, deselecting a window sets
+ the window's value of point from that of the buffer. Thus, when
+ you switch between windows that display a given buffer, the point
+ value for the selected window is in effect in the buffer, while
+ the point values for the other windows are stored in those windows.
+
+ * As long as the selected window displays the current buffer, the
+ window's point and the buffer's point always move together; they
+ remain equal.
+
+ * *Note Positions::, for more details on buffer positions.
+
+ As far as the user is concerned, point is where the cursor is, and
+when the user switches to another buffer, the cursor jumps to the
+position of point in that buffer.
+
+ - Function: window-point &optional window
+ This function returns the current position of point in WINDOW.
+ For a non-selected window, this is the value point would have (in
+ that window's buffer) if that window were selected.
+
+ When WINDOW is the selected window and its buffer is also the
+ current buffer, the value returned is the same as the value of
+ point in that buffer.
+
+ Strictly speaking, it would be more correct to return the
+ "top-level" value of point, outside of any `save-excursion' forms.
+ But that value is hard to find.
+
+ - Function: set-window-point window position
+ This function positions point in WINDOW at position POSITION in
+ WINDOW's buffer.
+
+\1f
+File: lispref.info, Node: Window Start, Next: Vertical Scrolling, Prev: Window Point, Up: Windows
+
+The Window Start Position
+=========================
+
+Each window contains a marker used to keep track of a buffer position
+that specifies where in the buffer display should start. This position
+is called the "display-start" position of the window (or just the
+"start"). The character after this position is the one that appears at
+the upper left corner of the window. It is usually, but not
+inevitably, at the beginning of a text line.
+
+ - Function: window-start &optional window
+ This function returns the display-start position of window WINDOW.
+ If WINDOW is `nil', the selected window is used. For example,
+
+ (window-start)
+ => 7058
+
+ When you create a window, or display a different buffer in it, the
+ display-start position is set to a display-start position recently
+ used for the same buffer, or 1 if the buffer doesn't have any.
+
+ For a realistic example, see the description of `count-lines' in
+ *Note Text Lines::.
+
+ - Function: window-end &optional window guarantee
+ This function returns the position of the end of the display in
+ window WINDOW. If WINDOW is `nil', the selected window is used.
+
+ Simply changing the buffer text or setting `window-start' does not
+ update the value that `window-end' returns. The value is updated
+ only when Emacs redisplays and redisplay actually finishes.
+
+ If the last redisplay of WINDOW was preempted, and did not finish,
+ Emacs does not know the position of the end of display in that
+ window. In that case, this function returns a value that is not
+ correct. In a future version, `window-end' will return `nil' in
+ that case.
+
+ If optional arg GUARANTEE is non-`nil', the return value is
+ guaranteed to be the same as `window-end' would return at the end
+ of the next full redisplay assuming nothing else changes in the
+ meantime. This function is potentially much slower with this flag
+ set.
+
+
+ - Function: set-window-start window position &optional noforce
+ This function sets the display-start position of WINDOW to
+ POSITION in WINDOW's buffer. It returns POSITION.
+
+ The display routines insist that the position of point be visible
+ when a buffer is displayed. Normally, they change the
+ display-start position (that is, scroll the window) whenever
+ necessary to make point visible. However, if you specify the
+ start position with this function using `nil' for NOFORCE, it
+ means you want display to start at POSITION even if that would put
+ the location of point off the screen. If this does place point
+ off screen, the display routines move point to the left margin on
+ the middle line in the window.
+
+ For example, if point is 1 and you set the start of the window
+ to 2, then point would be "above" the top of the window. The
+ display routines will automatically move point if it is still 1
+ when redisplay occurs. Here is an example:
+
+ ;; Here is what `foo' looks like before executing
+ ;; the `set-window-start' expression.
+
+ ---------- Buffer: foo ----------
+ -!-This is the contents of buffer foo.
+ 2
+ 3
+ 4
+ 5
+ 6
+ ---------- Buffer: foo ----------
+
+ (set-window-start
+ (selected-window)
+ (1+ (window-start)))
+ => 2
+
+ ;; Here is what `foo' looks like after executing
+ ;; the `set-window-start' expression.
+ ---------- Buffer: foo ----------
+ his is the contents of buffer foo.
+ 2
+ 3
+ -!-4
+ 5
+ 6
+ ---------- Buffer: foo ----------
+
+ If NOFORCE is non-`nil', and POSITION would place point off screen
+ at the next redisplay, then redisplay computes a new window-start
+ position that works well with point, and thus POSITION is not used.
+
+ - Function: pos-visible-in-window-p &optional position window
+ This function returns `t' if POSITION is within the range of text
+ currently visible on the screen in WINDOW. It returns `nil' if
+ POSITION is scrolled vertically out of view. The argument
+ POSITION defaults to the current position of point; WINDOW, to the
+ selected window. Here is an example:
+
+ (or (pos-visible-in-window-p
+ (point) (selected-window))
+ (recenter 0))
+
+ The `pos-visible-in-window-p' function considers only vertical
+ scrolling. If POSITION is out of view only because WINDOW has
+ been scrolled horizontally, `pos-visible-in-window-p' returns `t'.
+ *Note Horizontal Scrolling::.
+
+\1f
+File: lispref.info, Node: Vertical Scrolling, Next: Horizontal Scrolling, Prev: Window Start, Up: Windows
+
+Vertical Scrolling
+==================
-* Cons Cells:: How lists are made out of cons cells.
-* Lists as Boxes:: Graphical notation to explain lists.
-* List-related Predicates:: Is this object a list? Comparing two lists.
-* List Elements:: Extracting the pieces of a list.
-* Building Lists:: Creating list structure.
-* Modifying Lists:: Storing new pieces into an existing list.
-* Sets And Lists:: A list can represent a finite mathematical set.
-* Association Lists:: A list can represent a finite relation or mapping.
-* Property Lists:: A different way to represent a finite mapping.
-* Weak Lists:: A list with special garbage-collection behavior.
+Vertical scrolling means moving the text up or down in a window. It
+works by changing the value of the window's display-start location. It
+may also change the value of `window-point' to keep it on the screen.
+
+ In the commands `scroll-up' and `scroll-down', the directions "up"
+and "down" refer to the motion of the text in the buffer at which you
+are looking through the window. Imagine that the text is written on a
+long roll of paper and that the scrolling commands move the paper up
+and down. Thus, if you are looking at text in the middle of a buffer
+and repeatedly call `scroll-down', you will eventually see the
+beginning of the buffer.
+
+ Some people have urged that the opposite convention be used: they
+imagine that the window moves over text that remains in place. Then
+"down" commands would take you to the end of the buffer. This view is
+more consistent with the actual relationship between windows and the
+text in the buffer, but it is less like what the user sees. The
+position of a window on the terminal does not move, and short scrolling
+commands clearly move the text up or down on the screen. We have chosen
+names that fit the user's point of view.
+
+ The scrolling functions (aside from `scroll-other-window') have
+unpredictable results if the current buffer is different from the buffer
+that is displayed in the selected window. *Note Current Buffer::.
+
+ - Command: scroll-up &optional lines
+ This function scrolls the text in the selected window upward LINES
+ lines. If LINES is negative, scrolling is actually downward.
+
+ If LINES is `nil' (or omitted), then the length of scroll is
+ `next-screen-context-lines' lines less than the usable height of
+ the window (not counting its modeline).
+
+ `scroll-up' returns `nil'.
+
+ - Command: scroll-down &optional lines
+ This function scrolls the text in the selected window downward
+ LINES lines. If LINES is negative, scrolling is actually upward.
+
+ If LINES is omitted or `nil', then the length of the scroll is
+ `next-screen-context-lines' lines less than the usable height of
+ the window (not counting its mode line).
+
+ `scroll-down' returns `nil'.
+
+ - Command: scroll-other-window &optional lines
+ This function scrolls the text in another window upward LINES
+ lines. Negative values of LINES, or `nil', are handled as in
+ `scroll-up'.
+
+ You can specify a buffer to scroll with the variable
+ `other-window-scroll-buffer'. When the selected window is the
+ minibuffer, the next window is normally the one at the top left
+ corner. You can specify a different window to scroll with the
+ variable `minibuffer-scroll-window'. This variable has no effect
+ when any other window is selected. *Note Minibuffer Misc::.
+
+ When the minibuffer is active, it is the next window if the
+ selected window is the one at the bottom right corner. In this
+ case, `scroll-other-window' attempts to scroll the minibuffer. If
+ the minibuffer contains just one line, it has nowhere to scroll
+ to, so the line reappears after the echo area momentarily displays
+ the message "Beginning of buffer".
+
+ - Variable: other-window-scroll-buffer
+ If this variable is non-`nil', it tells `scroll-other-window'
+ which buffer to scroll.
+
+ - User Option: scroll-step
+ This variable controls how scrolling is done automatically when
+ point moves off the screen. If the value is zero, then redisplay
+ scrolls the text to center point vertically in the window. If the
+ value is a positive integer N, then redisplay brings point back on
+ screen by scrolling N lines in either direction, if possible;
+ otherwise, it centers point. The default value is zero.
+
+ - User Option: scroll-conservatively
+ This variable controls how many lines Emacs tries to scroll before
+ recentering. If you set it to a small number, then when you move
+ point a short distance off the screen, XEmacs will scroll the
+ screen just far enough to bring point back on screen, provided
+ that does not exceed `scroll-conservatively' lines. This variable
+ overrides the redisplay preemption.
+
+ - User Option: next-screen-context-lines
+ The value of this variable is the number of lines of continuity to
+ retain when scrolling by full screens. For example, `scroll-up'
+ with an argument of `nil' scrolls so that this many lines at the
+ bottom of the window appear instead at the top. The default value
+ is `2'.
+
+ - Command: recenter &optional location window
+ This function scrolls WINDOW (which defaults to the selected
+ window) to put the text where point is located at a specified
+ vertical position within the window.
+
+ If LOCATION is a nonnegative number, it puts the line containing
+ point LOCATION lines down from the top of the window. If LOCATION
+ is a negative number, then it counts upward from the bottom of the
+ window, so that -1 stands for the last usable line in the window.
+ If LOCATION is a non-`nil' list, then it stands for the line in
+ the middle of the window.
+
+ If LOCATION is `nil', `recenter' puts the line containing point in
+ the middle of the window, then clears and redisplays the entire
+ selected frame.
+
+ When `recenter' is called interactively, LOCATION is the raw
+ prefix argument. Thus, typing `C-u' as the prefix sets the
+ LOCATION to a non-`nil' list, while typing `C-u 4' sets LOCATION
+ to 4, which positions the current line four lines from the top.
+
+ With an argument of zero, `recenter' positions the current line at
+ the top of the window. This action is so handy that some people
+ make a separate key binding to do this. For example,
+
+ (defun line-to-top-of-window ()
+ "Scroll current line to top of window.
+ Replaces three keystroke sequence C-u 0 C-l."
+ (interactive)
+ (recenter 0))
+
+ (global-set-key [kp-multiply] 'line-to-top-of-window)
\1f
-File: lispref.info, Node: Cons Cells, Next: Lists as Boxes, Up: Lists
+File: lispref.info, Node: Horizontal Scrolling, Next: Size of Window, Prev: Vertical Scrolling, Up: Windows
-Lists and Cons Cells
+Horizontal Scrolling
====================
- Lists in Lisp are not a primitive data type; they are built up from
-"cons cells". A cons cell is a data object that represents an ordered
-pair. It records two Lisp objects, one labeled as the CAR, and the
-other labeled as the CDR. These names are traditional; see *Note Cons
-Cell Type::. CDR is pronounced "could-er."
-
- A list is a series of cons cells chained together, one cons cell per
-element of the list. By convention, the CARs of the cons cells are the
-elements of the list, and the CDRs are used to chain the list: the CDR
-of each cons cell is the following cons cell. The CDR of the last cons
-cell is `nil'. This asymmetry between the CAR and the CDR is entirely
-a matter of convention; at the level of cons cells, the CAR and CDR
-slots have the same characteristics.
-
- Because most cons cells are used as part of lists, the phrase "list
-structure" has come to mean any structure made out of cons cells.
-
- The symbol `nil' is considered a list as well as a symbol; it is the
-list with no elements. For convenience, the symbol `nil' is considered
-to have `nil' as its CDR (and also as its CAR).
-
- The CDR of any nonempty list L is a list containing all the elements
-of L except the first.
-
-\1f
-File: lispref.info, Node: Lists as Boxes, Next: List-related Predicates, Prev: Cons Cells, Up: Lists
-
-Lists as Linked Pairs of Boxes
-==============================
-
- A cons cell can be illustrated as a pair of boxes. The first box
-represents the CAR and the second box represents the CDR. Here is an
-illustration of the two-element list, `(tulip lily)', made from two
-cons cells:
-
- --------------- ---------------
- | car | cdr | | car | cdr |
- | tulip | o---------->| lily | nil |
- | | | | | |
- --------------- ---------------
-
- Each pair of boxes represents a cons cell. Each box "refers to",
-"points to" or "contains" a Lisp object. (These terms are synonymous.)
-The first box, which is the CAR of the first cons cell, contains the
-symbol `tulip'. The arrow from the CDR of the first cons cell to the
-second cons cell indicates that the CDR of the first cons cell points
-to the second cons cell.
-
- The same list can be illustrated in a different sort of box notation
-like this:
-
- ___ ___ ___ ___
- |___|___|--> |___|___|--> nil
- | |
- | |
- --> tulip --> lily
-
- Here is a more complex illustration, showing the three-element list,
-`((pine needles) oak maple)', the first element of which is a
-two-element list:
-
- ___ ___ ___ ___ ___ ___
- |___|___|--> |___|___|--> |___|___|--> nil
- | | |
- | | |
- | --> oak --> maple
- |
- | ___ ___ ___ ___
- --> |___|___|--> |___|___|--> nil
- | |
- | |
- --> pine --> needles
-
- The same list represented in the first box notation looks like this:
-
- -------------- -------------- --------------
- | car | cdr | | car | cdr | | car | cdr |
- | o | o------->| oak | o------->| maple | nil |
- | | | | | | | | | |
- -- | --------- -------------- --------------
- |
- |
- | -------------- ----------------
- | | car | cdr | | car | cdr |
- ------>| pine | o------->| needles | nil |
- | | | | | |
- -------------- ----------------
-
- *Note Cons Cell Type::, for the read and print syntax of cons cells
-and lists, and for more "box and arrow" illustrations of lists.
-
-\1f
-File: lispref.info, Node: List-related Predicates, Next: List Elements, Prev: Lists as Boxes, Up: Lists
-
-Predicates on Lists
-===================
+Because we read English first from top to bottom and second from left
+to right, horizontal scrolling is not like vertical scrolling. Vertical
+scrolling involves selection of a contiguous portion of text to display.
+Horizontal scrolling causes part of each line to go off screen. The
+amount of horizontal scrolling is therefore specified as a number of
+columns rather than as a position in the buffer. It has nothing to do
+with the display-start position returned by `window-start'.
+
+ Usually, no horizontal scrolling is in effect; then the leftmost
+column is at the left edge of the window. In this state, scrolling to
+the right is meaningless, since there is no data to the left of the
+screen to be revealed by it; so this is not allowed. Scrolling to the
+left is allowed; it scrolls the first columns of text off the edge of
+the window and can reveal additional columns on the right that were
+truncated before. Once a window has a nonzero amount of leftward
+horizontal scrolling, you can scroll it back to the right, but only so
+far as to reduce the net horizontal scroll to zero. There is no limit
+to how far left you can scroll, but eventually all the text will
+disappear off the left edge.
+
+ - Command: scroll-left &optional count
+ This function scrolls the selected window COUNT columns to the
+ left (or to the right if COUNT is negative). The return value is
+ the total amount of leftward horizontal scrolling in effect after
+ the change--just like the value returned by `window-hscroll'
+ (below).
+
+ - Command: scroll-right &optional count
+ This function scrolls the selected window COUNT columns to the
+ right (or to the left if COUNT is negative). The return value is
+ the total amount of leftward horizontal scrolling in effect after
+ the change--just like the value returned by `window-hscroll'
+ (below).
+
+ Once you scroll a window as far right as it can go, back to its
+ normal position where the total leftward scrolling is zero,
+ attempts to scroll any farther right have no effect.
+
+ - Function: window-hscroll &optional window
+ This function returns the total leftward horizontal scrolling of
+ WINDOW--the number of columns by which the text in WINDOW is
+ scrolled left past the left margin.
+
+ The value is never negative. It is zero when no horizontal
+ scrolling has been done in WINDOW (which is usually the case).
+
+ If WINDOW is `nil', the selected window is used.
+
+ (window-hscroll)
+ => 0
+ (scroll-left 5)
+ => 5
+ (window-hscroll)
+ => 5
- The following predicates test whether a Lisp object is an atom, is a
-cons cell or is a list, or whether it is the distinguished object
-`nil'. (Many of these predicates can be defined in terms of the
-others, but they are used so often that it is worth having all of them.)
+ - Function: set-window-hscroll window columns
+ This function sets the number of columns from the left margin that
+ WINDOW is scrolled to the value of COLUMNS. The argument COLUMNS
+ should be zero or positive; if not, it is taken as zero.
- - Function: consp object
- This function returns `t' if OBJECT is a cons cell, `nil'
- otherwise. `nil' is not a cons cell, although it _is_ a list.
+ The value returned is COLUMNS.
- - Function: atom object
- This function returns `t' if OBJECT is an atom, `nil' otherwise.
- All objects except cons cells are atoms. The symbol `nil' is an
- atom and is also a list; it is the only Lisp object that is both.
+ (set-window-hscroll (selected-window) 10)
+ => 10
- (atom OBJECT) == (not (consp OBJECT))
+ Here is how you can determine whether a given position POSITION is
+off the screen due to horizontal scrolling:
- - Function: listp object
- This function returns `t' if OBJECT is a cons cell or `nil'.
- Otherwise, it returns `nil'.
+ (defun hscroll-on-screen (window position)
+ (save-excursion
+ (goto-char position)
+ (and
+ (>= (- (current-column) (window-hscroll window)) 0)
+ (< (- (current-column) (window-hscroll window))
+ (window-width window)))))
- (listp '(1))
- => t
- (listp '())
- => t
+\1f
+File: lispref.info, Node: Size of Window, Next: Position of Window, Prev: Horizontal Scrolling, Up: Windows
- - Function: nlistp object
- This function is the opposite of `listp': it returns `t' if OBJECT
- is not a list. Otherwise, it returns `nil'.
+The Size of a Window
+====================
- (listp OBJECT) == (not (nlistp OBJECT))
+An Emacs window is rectangular, and its size information consists of
+the height (in lines or pixels) and the width (in character positions
+or pixels). The modeline is included in the height. The pixel width
+and height values include scrollbars and margins, while the
+line/character-position values do not.
+
+ Note that the height in lines, and the width in characters, are
+determined by dividing the corresponding pixel value by the height or
+width of the default font in that window (if this is a variable-width
+font, the average width is used). The resulting values may or may not
+represent the actual number of lines in the window, or the actual number
+of character positions in any particular line, esp. if there are pixmaps
+or various different fonts in the window.
+
+ The following functions return size information about a window:
+
+ - Function: window-height &optional window
+ This function returns the number of lines in WINDOW, including its
+ modeline but not including the horizontal scrollbar, if any (this
+ is different from `window-pixel-height'). If WINDOW is `nil', the
+ function uses the selected window.
+
+ (window-height)
+ => 40
+ (split-window-vertically)
+ => #<window on "windows.texi" 0x679b>
+ (window-height)
+ => 20
+
+ - Function: window-width &optional window
+ This function returns the number of columns in WINDOW, not
+ including any left margin, right margin, or vertical scrollbar
+ (this is different from `window-pixel-width'). If WINDOW is
+ `nil', the function uses the selected window.
+
+ (window-width)
+ => 80
+ (window-height)
+ => 40
+ (split-window-horizontally)
+ => #<window on "windows.texi" 0x7538>
+ (window-width)
+ => 39
+
+ Note that after splitting the window into two side-by-side windows,
+the width of each window is less the half the width of the original
+window because a vertical scrollbar appeared between the windows,
+occupying two columns worth of space. Also, the height shrunk by one
+because horizontal scrollbars appeared that weren't there before.
+(Horizontal scrollbars appear only when lines are truncated, not when
+they wrap. This is usually the case for horizontally split windows but
+not for full-frame windows. You can change this using the variables
+`truncate-lines' and `truncate-partial-width-windows'.)
+
+ - Function: window-pixel-height &optional window
+ This function returns the height of WINDOW in pixels, including
+ its modeline and horizontal scrollbar, if any. If WINDOW is
+ `nil', the function uses the selected window.
+
+ (window-pixel-height)
+ => 600
+ (split-window-vertically)
+ => #<window on "windows.texi" 0x68a6>
+ (window-pixel-height)
+ => 300
+
+ - Function: window-pixel-width &optional window
+ This function returns the width of WINDOW in pixels, including any
+ left margin, right margin, or vertical scrollbar that may be
+ displayed alongside it. If WINDOW is `nil', the function uses the
+ selected window.
+
+ (window-pixel-width)
+ => 735
+ (window-pixel-height)
+ => 600
+ (split-window-horizontally)
+ => #<window on "windows.texi" 0x7538>
+ (window-pixel-width)
+ => 367
+ (window-pixel-height)
+ => 600
+
+ - Function: window-text-area-pixel-height &optional window
+ This function returns the height in pixels of the text displaying
+ portion of WINDOW, which defaults to the selected window. Unlike
+ `window-pixel-height', the space occupied by the modeline and
+ horizontal scrollbar, if any, is not counted.
+
+ - Function: window-text-area-pixel-width &optional window
+ This function returns the width in pixels of the text displaying
+ portion of WINDOW, which defaults to the selected window. Unlike
+ `window-pixel-width', the space occupied by the vertical scrollbar
+ and divider, if any, is not counted.
+
+ - Function: window-displayed-text-pixel-height &optional window
+ noclipped
+ This function returns the height in pixels of the text displayed in
+ WINDOW, which defaults to the selected window. Unlike
+ `window-text-area-pixel-height', any blank space below the end of
+ the buffer is not included. If optional argument NOCLIPPED is
+ non-`nil', any space occupied by clipped lines will not be
+ included.
- - Function: null object
- This function returns `t' if OBJECT is `nil', and returns `nil'
- otherwise. This function is identical to `not', but as a matter
- of clarity we use `null' when OBJECT is considered a list and
- `not' when it is considered a truth value (see `not' in *Note
- Combining Conditions::).
+\1f
+File: lispref.info, Node: Position of Window, Next: Resizing Windows, Prev: Size of Window, Up: Windows
+
+The Position of a Window
+========================
+
+XEmacs provides functions to determine the absolute location of windows
+within a frame, and the relative location of a window in comparison to
+other windows in the same frame.
+
+ - Function: window-pixel-edges &optional window
+ This function returns a list of the pixel edge coordinates of
+ WINDOW. If WINDOW is `nil', the selected window is used.
+
+ The order of the list is `(LEFT TOP RIGHT BOTTOM)', all elements
+ relative to 0, 0 at the top left corner of WINDOW's frame. The
+ element RIGHT of the value is one more than the rightmost pixel
+ used by WINDOW (including any left margin, right margin, or
+ vertical scrollbar displayed alongside it), and BOTTOM is one more
+ than the bottommost pixel used by WINDOW (including any modeline
+ or horizontal scrollbar displayed above or below it). The frame
+ area does not include any frame menubars, toolbars, or gutters
+ that may be displayed; thus, for example, if there is only one
+ window on the frame, the values for LEFT and TOP will always be 0.
+
+ If WINDOW is at the upper left corner of its frame, RIGHT and
+ BOTTOM are the same as the values returned by
+ `(window-pixel-width)' and `(window-pixel-height)' respectively,
+ and LEFT and TOP are zero.
+
+ There is no longer a function `window-edges' because it does not
+make sense in a world with variable-width and variable-height lines, as
+are allowed in XEmacs.
+
+ - Function: window-highest-p window
+ This function returns non-`nil' if WINDOW is along the top of its
+ frame.
+
+ - Function: window-lowest-p window
+ This function returns non-`nil' if WINDOW is along the bottom of
+ its frame.
+
+ - Function: window-text-area-pixel-edges &optional window
+ This function allows one to determine the location of the
+ text-displaying portion of WINDOW, which defaults to the selected
+ window, with respect to the top left corner of the window. It
+ returns a list of integer pixel positions `(left top right
+ bottom)', all relative to `(0,0)' at the top left corner of the
+ window.
- (null '(1))
- => nil
- (null '())
+\1f
+File: lispref.info, Node: Resizing Windows, Next: Window Configurations, Prev: Position of Window, Up: Windows
+
+Changing the Size of a Window
+=============================
+
+The window size functions fall into two classes: high-level commands
+that change the size of windows and low-level functions that access
+window size. XEmacs does not permit overlapping windows or gaps between
+windows, so resizing one window affects other windows.
+
+ - Command: enlarge-window count &optional horizontal window
+ This function makes the selected window COUNT lines taller,
+ stealing lines from neighboring windows. It takes the lines from
+ one window at a time until that window is used up, then takes from
+ another. If a window from which lines are stolen shrinks below
+ `window-min-height' lines, that window disappears.
+
+ If HORIZONTAL is non-`nil', this function makes WINDOW wider by
+ COUNT columns, stealing columns instead of lines. If a window
+ from which columns are stolen shrinks below `window-min-width'
+ columns, that window disappears.
+
+ If the requested size would exceed that of the window's frame,
+ then the function makes the window occupy the entire height (or
+ width) of the frame.
+
+ If COUNT is negative, this function shrinks the window by -COUNT
+ lines or columns. If that makes the window smaller than the
+ minimum size (`window-min-height' and `window-min-width'),
+ `enlarge-window' deletes the window.
+
+ If WINDOW is non-`nil', it specifies a window to change instead of
+ the selected window.
+
+ `enlarge-window' returns `nil'.
+
+ - Command: enlarge-window-horizontally columns
+ This function makes the selected window COLUMNS wider. It could
+ be defined as follows:
+
+ (defun enlarge-window-horizontally (columns)
+ (enlarge-window columns t))
+
+ - Command: enlarge-window-pixels count &optional side window
+ This function makes the selected window COUNT pixels larger. When
+ called from Lisp, optional second argument SIDE non-`nil' means to
+ grow sideways COUNT pixels, and optional third argument WINDOW
+ specifies the window to change instead of the selected window.
+
+ - Command: shrink-window count &optional horizontal window
+ This function is like `enlarge-window' but negates the argument
+ COUNT, making the selected window smaller by giving lines (or
+ columns) to the other windows. If the window shrinks below
+ `window-min-height' or `window-min-width', then it disappears.
+
+ If COUNT is negative, the window is enlarged by -COUNT lines or
+ columns.
+
+ If WINDOW is non-`nil', it specifies a window to change instead of
+ the selected window.
+
+ - Command: shrink-window-horizontally columns
+ This function makes the selected window COLUMNS narrower. It
+ could be defined as follows:
+
+ (defun shrink-window-horizontally (columns)
+ (shrink-window columns t))
+
+ - Command: shrink-window-pixels count &optional side window
+ This function makes the selected window COUNT pixels smaller.
+ When called from Lisp, optional second argument SIDE non-`nil'
+ means to shrink sideways COUNT pixels, and optional third argument
+ WINDOW specifies the window to change instead of the selected
+ window.
+
+ The following two variables constrain the window-size-changing
+functions to a minimum height and width.
+
+ - User Option: window-min-height
+ The value of this variable determines how short a window may become
+ before it is automatically deleted. Making a window smaller than
+ `window-min-height' automatically deletes it, and no window may be
+ created shorter than this. The absolute minimum height is two
+ (allowing one line for the mode line, and one line for the buffer
+ display). Actions that change window sizes reset this variable to
+ two if it is less than two. The default value is 4.
+
+ - User Option: window-min-width
+ The value of this variable determines how narrow a window may
+ become before it automatically deleted. Making a window smaller
+ than `window-min-width' automatically deletes it, and no window
+ may be created narrower than this. The absolute minimum width is
+ one; any value below that is ignored. The default value is 10.
+
+ - Variable: window-size-change-functions
+ This variable holds a list of functions to be called if the size
+ of any window changes for any reason. The functions are called
+ just once per redisplay, and just once for each frame on which
+ size changes have occurred.
+
+ Each function receives the frame as its sole argument. There is no
+ direct way to find out which windows changed size, or precisely
+ how; however, if your size-change function keeps track, after each
+ change, of the windows that interest you, you can figure out what
+ has changed by comparing the old size data with the new.
+
+ Creating or deleting windows counts as a size change, and therefore
+ causes these functions to be called. Changing the frame size also
+ counts, because it changes the sizes of the existing windows.
+
+ It is not a good idea to use `save-window-excursion' in these
+ functions, because that always counts as a size change, and it
+ would cause these functions to be called over and over. In most
+ cases, `save-selected-window' is what you need here.
+
+\1f
+File: lispref.info, Node: Window Configurations, Prev: Resizing Windows, Up: Windows
+
+Window Configurations
+=====================
+
+A "window configuration" records the entire layout of a frame--all
+windows, their sizes, which buffers they contain, what part of each
+buffer is displayed, and the values of point and the mark. You can
+bring back an entire previous layout by restoring a window
+configuration previously saved.
+
+ If you want to record all frames instead of just one, use a frame
+configuration instead of a window configuration. *Note Frame
+Configurations::.
+
+ - Function: current-window-configuration &optional frame
+ This function returns a new object representing the current window
+ configuration of FRAME, namely the number of windows, their sizes
+ and current buffers, which window is the selected window, and for
+ each window the displayed buffer, the display-start position, and
+ the positions of point and the mark. An exception is made for
+ point in the current buffer, whose value is not saved.
+
+ FRAME defaults to the selected frame.
+
+ - Function: set-window-configuration configuration
+ This function restores the configuration of XEmacs's windows and
+ buffers to the state specified by CONFIGURATION. The argument
+ CONFIGURATION must be a value that was previously returned by
+ `current-window-configuration'.
+
+ This function always counts as a window size change and triggers
+ execution of the `window-size-change-functions'. (It doesn't know
+ how to tell whether the new configuration actually differs from
+ the old one.)
+
+ Here is a way of using this function to get the same effect as
+ `save-window-excursion':
+
+ (let ((config (current-window-configuration)))
+ (unwind-protect
+ (progn (split-window-vertically nil)
+ ...)
+ (set-window-configuration config)))
+
+ - Special Form: save-window-excursion forms...
+ This special form records the window configuration, executes FORMS
+ in sequence, then restores the earlier window configuration. The
+ window configuration includes the value of point and the portion
+ of the buffer that is visible. It also includes the choice of
+ selected window. However, it does not include the value of point
+ in the current buffer; use `save-excursion' if you wish to
+ preserve that.
+
+ Don't use this construct when `save-selected-window' is all you
+ need.
+
+ Exit from `save-window-excursion' always triggers execution of the
+ `window-size-change-functions'. (It doesn't know how to tell
+ whether the restored configuration actually differs from the one in
+ effect at the end of the FORMS.)
+
+ The return value is the value of the final form in FORMS. For
+ example:
+
+ (split-window)
+ => #<window 25 on control.texi>
+ (setq w (selected-window))
+ => #<window 19 on control.texi>
+ (save-window-excursion
+ (delete-other-windows w)
+ (switch-to-buffer "foo")
+ 'do-something)
+ => do-something
+ ;; The frame is now split again.
+
+ - Function: window-configuration-p object
+ This function returns `t' if OBJECT is a window configuration.
+
+ Primitives to look inside of window configurations would make sense,
+but none are implemented. It is not clear they are useful enough to be
+worth implementing.
+
+\1f
+File: lispref.info, Node: Frames, Next: Consoles and Devices, Prev: Windows, Up: Top
+
+Frames
+******
+
+A FRAME is a rectangle on the screen that contains one or more XEmacs
+windows (*note Windows::). A frame initially contains a single main
+window (plus perhaps an echo area), which you can subdivide vertically
+or horizontally into smaller windows. Each window is associated with a
+modeline (*note Modeline Format::), and optionally two scrollbars
+(*note Scrollbars::). By default the vertical scrollbar is on, the
+horizontal scrollbar is off.
+
+ The frame may also contain menubars (*note Menubar::), toolbars
+(*note Toolbar Intro::), and gutters (*note Gutter Intro::). By default
+there is one of each at the top of the frame, with menubar topmost,
+toolbar next, and gutter lowest, immediately above the windows.
+(Warning: the gutter is a new, experimental, and unstable feature of
+XEmacs version 21.2.)
+
+ When XEmacs runs on a text-only terminal, it starts with one "TTY
+frame". If you create additional ones, XEmacs displays one and only
+one at any given time--on the terminal screen, of course.
+
+ When XEmacs communicates directly with an X server, it does not have
+a TTY frame; instead, it starts with a single "X window frame". It can
+display multiple X window frames at the same time, each in its own X
+window.
+
+ - Function: framep object
+ This predicate returns `t' if OBJECT is a frame, and `nil'
+ otherwise.
+
+* Menu:
+
+* Creating Frames:: Creating additional frames.
+* Frame Properties:: Controlling frame size, position, font, etc.
+* Frame Titles:: Automatic updating of frame titles.
+* Deleting Frames:: Frames last until explicitly deleted.
+* Finding All Frames:: How to examine all existing frames.
+* Frames and Windows:: A frame contains windows;
+ display of text always works through windows.
+* Minibuffers and Frames:: How a frame finds the minibuffer to use.
+* Input Focus:: Specifying the selected frame.
+* Visibility of Frames:: Frames may be visible or invisible, or icons.
+* Raising and Lowering:: Raising a frame makes it hide other X windows;
+ lowering it makes the others hide them.
+* Frame Configurations:: Saving the state of all frames.
+* Frame Hooks:: Hooks for customizing frame behavior.
+
+ *Note Display::, for related information.
+
+\1f
+File: lispref.info, Node: Creating Frames, Next: Frame Properties, Up: Frames
+
+Creating Frames
+===============
+
+To create a new frame, call the function `make-frame'.
+
+ - Command: make-frame &optional props device
+ This function creates a new frame on DEVICE, if DEVICE permits
+ creation of frames. (An X server does; an ordinary terminal does
+ not (yet).) DEVICE defaults to the selected device if omitted.
+ *Note Consoles and Devices::.
+
+ The argument PROPS is a property list (a list of alternating
+ keyword-value specifications) of properties for the new frame. (An
+ alist is accepted for backward compatibility but should not be
+ passed in.) Any properties not mentioned in PROPS default
+ according to the value of the variable `default-frame-plist'. For
+ X devices, properties not specified in `default-frame-plist'
+ default in turn from `default-x-frame-plist' and, if not specified
+ there, from the X resources. For TTY devices,
+ `default-tty-frame-plist' is consulted as well as
+ `default-frame-plist'.
+
+ The set of possible properties depends in principle on what kind of
+ window system XEmacs uses to display its frames. *Note X Frame
+ Properties::, for documentation of individual properties you can
+ specify when creating an X window frame.
+
+\1f
+File: lispref.info, Node: Frame Properties, Next: Frame Titles, Prev: Creating Frames, Up: Frames
+
+Frame Properties
+================
+
+A frame has many properties that control its appearance and behavior.
+Just what properties a frame has depends on which display mechanism it
+uses.
+
+ Frame properties exist for the sake of window systems. A terminal
+frame has few properties, mostly for compatibility's sake; only the
+height, width and `buffer-predicate' properties really do something.
+
+* Menu:
+
+* Property Access:: How to change a frame's properties.
+* Initial Properties:: Specifying frame properties when you make a frame.
+* X Frame Properties:: List of frame properties.
+* Size and Position:: Changing the size and position of a frame.
+* Frame Name:: The name of a frame (as opposed to its title).
+
+\1f
+File: lispref.info, Node: Property Access, Next: Initial Properties, Up: Frame Properties
+
+Access to Frame Properties
+--------------------------
+
+These functions let you read and change the properties of a frame.
+
+ - Function: frame-properties &optional frame
+ This function returns a plist listing all the properties of FRAME
+ and their values.
+
+ - Function: frame-property frame property &optional default
+ This function returns FRAME's value for the property PROPERTY, or
+ DEFAULT if there is no such property.
+
+ - Function: set-frame-properties frame plist
+ This function alters the properties of frame FRAME based on the
+ elements of property list PLIST. If you don't mention a property
+ in PLIST, its value doesn't change.
+
+ - Function: set-frame-property frame property value
+ This function sets the property PROPERTY of frame FRAME to the
+ value VALUE.
+
+\1f
+File: lispref.info, Node: Initial Properties, Next: X Frame Properties, Prev: Property Access, Up: Frame Properties
+
+Initial Frame Properties
+------------------------
+
+You can specify the properties for the initial startup frame by setting
+`initial-frame-plist' in your `.emacs' file.
+
+ - Variable: initial-frame-plist
+ This variable's value is a plist of alternating property-value
+ pairs used when creating the initial X window frame.
+
+ XEmacs creates the initial frame before it reads your `~/.emacs'
+ file. After reading that file, XEmacs checks
+ `initial-frame-plist', and applies the property settings in the
+ altered value to the already created initial frame.
+
+ If these settings affect the frame geometry and appearance, you'll
+ see the frame appear with the wrong ones and then change to the
+ specified ones. If that bothers you, you can specify the same
+ geometry and appearance with X resources; those do take affect
+ before the frame is created. *Note X Resources: (xemacs)Resources
+ X.
+
+ X resource settings typically apply to all frames. If you want to
+ specify some X resources solely for the sake of the initial frame,
+ and you don't want them to apply to subsequent frames, here's how
+ to achieve this: specify properties in `default-frame-plist' to
+ override the X resources for subsequent frames; then, to prevent
+ these from affecting the initial frame, specify the same
+ properties in `initial-frame-plist' with values that match the X
+ resources.
+
+ If these properties specify a separate minibuffer-only frame via a
+`minibuffer' property of `nil', and you have not yet created one,
+XEmacs creates one for you.
+
+ - Variable: minibuffer-frame-plist
+ This variable's value is a plist of properties used when creating
+ an initial minibuffer-only frame--if such a frame is needed,
+ according to the properties for the main initial frame.
+
+ - Variable: default-frame-plist
+ This is a plist specifying default values of frame properties for
+ subsequent XEmacs frames (not the initial ones).
+
+ See also `special-display-frame-plist', in *Note Choosing Window::.
+
+ If you use options that specify window appearance when you invoke
+XEmacs, they take effect by adding elements to `default-frame-plist'.
+One exception is `-geometry', which adds the specified position to
+`initial-frame-plist' instead. *Note Command Arguments:
+(xemacs)Command Arguments.
+
+\1f
+File: lispref.info, Node: X Frame Properties, Next: Size and Position, Prev: Initial Properties, Up: Frame Properties
+
+X Window Frame Properties
+-------------------------
+
+Just what properties a frame has depends on what display mechanism it
+uses. Here is a table of the properties of an X window frame; of these,
+`name', `height', `width', and `buffer-predicate' provide meaningful
+information in non-X frames.
+
+`name'
+ The name of the frame. Most window managers display the frame's
+ name in the frame's border, at the top of the frame. If you don't
+ specify a name, and you have more than one frame, XEmacs sets the
+ frame name based on the buffer displayed in the frame's selected
+ window.
+
+ If you specify the frame name explicitly when you create the
+ frame, the name is also used (instead of the name of the XEmacs
+ executable) when looking up X resources for the frame.
+
+`display'
+ The display on which to open this frame. It should be a string of
+ the form `"HOST:DPY.SCREEN"', just like the `DISPLAY' environment
+ variable.
+
+`left'
+ The screen position of the left edge, in pixels, with respect to
+ the left edge of the screen. The value may be a positive number
+ POS, or a list of the form `(+ POS)' which permits specifying a
+ negative POS value.
+
+ A negative number -POS, or a list of the form `(- POS)', actually
+ specifies the position of the right edge of the window with
+ respect to the right edge of the screen. A positive value of POS
+ counts toward the left. If the property is a negative integer
+ -POS then POS is positive!
+
+`top'
+ The screen position of the top edge, in pixels, with respect to the
+ top edge of the screen. The value may be a positive number POS,
+ or a list of the form `(+ POS)' which permits specifying a
+ negative POS value.
+
+ A negative number -POS, or a list of the form `(- POS)', actually
+ specifies the position of the bottom edge of the window with
+ respect to the bottom edge of the screen. A positive value of POS
+ counts toward the top. If the property is a negative integer -POS
+ then POS is positive!
+
+`icon-left'
+ The screen position of the left edge _of the frame's icon_, in
+ pixels, counting from the left edge of the screen. This takes
+ effect if and when the frame is iconified.
+
+`icon-top'
+ The screen position of the top edge _of the frame's icon_, in
+ pixels, counting from the top edge of the screen. This takes
+ effect if and when the frame is iconified.
+
+`user-position'
+ Non-`nil' if the screen position of the frame was explicitly
+ requested by the user (for example, with the `-geometry' option).
+ Nothing automatically makes this property non-`nil'; it is up to
+ Lisp programs that call `make-frame' to specify this property as
+ well as specifying the `left' and `top' properties.
+
+`height'
+ The height of the frame contents, in characters. (To get the
+ height in pixels, call `frame-pixel-height'; see *Note Size and
+ Position::.)
+
+`width'
+ The width of the frame contents, in characters. (To get the
+ height in pixels, call `frame-pixel-width'; see *Note Size and
+ Position::.)
+
+`window-id'
+ The number of the X window for the frame.
+
+`minibuffer'
+ Whether this frame has its own minibuffer. The value `t' means
+ yes, `nil' means no, `only' means this frame is just a minibuffer.
+ If the value is a minibuffer window (in some other frame), the
+ new frame uses that minibuffer. (Minibuffer-only and
+ minibuffer-less frames are not yet implemented in XEmacs.)
+
+`buffer-predicate'
+ The buffer-predicate function for this frame. The function
+ `other-buffer' uses this predicate (from the selected frame) to
+ decide which buffers it should consider, if the predicate is not
+ `nil'. It calls the predicate with one arg, a buffer, once for
+ each buffer; if the predicate returns a non-`nil' value, it
+ considers that buffer.
+
+`scroll-bar-width'
+ The width of the vertical scroll bar, in pixels.
+
+`cursor-color'
+ The color for the cursor that shows point.
+
+`border-color'
+ The color for the border of the frame.
+
+`border-width'
+ The width in pixels of the window border.
+
+`internal-border-width'
+ The distance in pixels between text and border.
+
+`unsplittable'
+ If non-`nil', this frame's window is never split automatically.
+
+`inter-line-space'
+ The space in pixels between adjacent lines of text. (Not currently
+ implemented.)
+
+`modeline'
+ Whether the frame has a modeline.
+
+\1f
+File: lispref.info, Node: Size and Position, Next: Frame Name, Prev: X Frame Properties, Up: Frame Properties
+
+Frame Size And Position
+-----------------------
+
+You can read or change the size and position of a frame using the frame
+properties `left', `top', `height', and `width'. Whatever geometry
+properties you don't specify are chosen by the window manager in its
+usual fashion.
+
+ Here are some special features for working with sizes and positions:
+
+ - Function: set-frame-position frame left top
+ This function sets the position of the top left corner of FRAME to
+ LEFT and TOP. These arguments are measured in pixels, and count
+ from the top left corner of the screen. Negative property values
+ count up or rightward from the top left corner of the screen.
+
+ - Function: frame-height &optional frame
+ - Function: frame-width &optional frame
+ These functions return the height and width of FRAME, measured in
+ lines and columns. If you don't supply FRAME, they use the
+ selected frame.
+
+ - Function: frame-pixel-height &optional frame
+ - Function: frame-pixel-width &optional frame
+ These functions return the height and width of FRAME, measured in
+ pixels. If you don't supply FRAME, they use the selected frame.
+
+ - Function: set-frame-size frame cols rows &optional pretend
+ This function sets the size of FRAME, measured in characters; COLS
+ and ROWS specify the new width and height. (If PRETEND is
+ non-`nil', it means that redisplay should act as if the frame's
+ size is COLS by ROWS, but the actual size of the frame should not
+ be changed. You should not normally use this option.)
+
+ You can also use the functions `set-frame-height' and
+`set-frame-width' to set the height and width individually. The frame
+is the first argument and the size (in rows or columns) is the second.
+(There is an optional third argument, PRETEND, which has the same
+purpose as the corresponding argument in `set-frame-size'.)
+
+\1f
+File: lispref.info, Node: Frame Name, Prev: Size and Position, Up: Frame Properties
+
+The Name of a Frame (As Opposed to Its Title)
+---------------------------------------------
+
+Under X, every frame has a name, which is not the same as the title of
+the frame. A frame's name is used to look up its resources and does
+not normally change over the lifetime of a frame. It is perfectly
+allowable, and quite common, for multiple frames to have the same name.
+
+ - Function: frame-name &optional frame
+ This function returns the name of FRAME, which defaults to the
+ selected frame if not specified. The name of a frame can also be
+ obtained from the frame's properties. *Note Frame Properties::.
+
+ - Variable: default-frame-name
+ This variable holds the default name to assign to newly-created
+ frames. This can be overridden by arguments to `make-frame'. This
+ must be a string.
+
+\1f
+File: lispref.info, Node: Frame Titles, Next: Deleting Frames, Prev: Frame Properties, Up: Frames
+
+Frame Titles
+============
+
+Every frame has a title; most window managers display the frame title at
+the top of the frame. You can specify an explicit title with the
+`name' frame property. But normally you don't specify this explicitly,
+and XEmacs computes the title automatically.
+
+ XEmacs computes the frame title based on a template stored in the
+variable `frame-title-format'.
+
+ - Variable: frame-title-format
+ This variable specifies how to compute a title for a frame when
+ you have not explicitly specified one.
+
+ The variable's value is actually a modeline construct, just like
+ `modeline-format'. *Note Modeline Data::.
+
+ - Variable: frame-icon-title-format
+ This variable specifies how to compute the title for an iconified
+ frame, when you have not explicitly specified the frame title.
+ This title appears in the icon itself.
+
+ - Function: x-set-frame-icon-pixmap frame pixmap &optional mask
+ This function sets the icon of the given frame to the given image
+ instance, which should be an image instance object (as returned by
+ `make-image-instance'), a glyph object (as returned by
+ `make-glyph'), or `nil'. If a glyph object is given, the glyph
+ will be instantiated on the frame to produce an image instance
+ object.
+
+ If the given image instance has a mask, that will be used as the
+ icon mask; however, not all window managers support this.
+
+ The window manager is also not required to support color pixmaps,
+ only bitmaps (one plane deep).
+
+ If the image instance does not have a mask, then the optional
+ third argument may be the image instance to use as the mask (it
+ must be one plane deep). *Note Glyphs::.
+
+\1f
+File: lispref.info, Node: Deleting Frames, Next: Finding All Frames, Prev: Frame Titles, Up: Frames
+
+Deleting Frames
+===============
+
+Frames remain potentially visible until you explicitly "delete" them.
+A deleted frame cannot appear on the screen, but continues to exist as
+a Lisp object until there are no references to it.
+
+ - Command: delete-frame &optional frame force
+ This function deletes the frame FRAME. By default, FRAME is the
+ selected frame.
+
+ A frame may not be deleted if its minibuffer is used by other
+ frames. Normally, you cannot delete the last non-minibuffer-only
+ frame (you must use `save-buffers-kill-emacs' or `kill-emacs').
+ However, if optional second argument FORCE is non-`nil', you can
+ delete the last frame. (This will automatically call
+ `save-buffers-kill-emacs'.)
+
+ - Function: frame-live-p frame
+ The function `frame-live-p' returns non-`nil' if the frame FRAME
+ has not been deleted.
+
+\1f
+File: lispref.info, Node: Finding All Frames, Next: Frames and Windows, Prev: Deleting Frames, Up: Frames
+
+Finding All Frames
+==================
+
+ - Function: frame-list
+ The function `frame-list' returns a list of all the frames that
+ have not been deleted. It is analogous to `buffer-list' for
+ buffers. The list that you get is newly created, so modifying the
+ list doesn't have any effect on the internals of XEmacs.
+
+ - Function: device-frame-list &optional device
+ This function returns a list of all frames on DEVICE. If DEVICE
+ is `nil', the selected device will be used.
+
+ - Function: visible-frame-list &optional device
+ This function returns a list of just the currently visible frames.
+ If DEVICE is specified only frames on that device will be returned.
+ *Note Visibility of Frames::. (TTY frames always count as
+ "visible", even though only the selected one is actually
+ displayed.)
+
+ - Function: next-frame &optional frame which-frames which-devices
+ The function `next-frame' lets you cycle conveniently through all
+ the frames from an arbitrary starting point. It returns the "next"
+ frame after FRAME in the cycle. If FRAME defaults to the selected
+ frame.
+
+ The second argument, WHICH-FRAMES, says which frames to consider:
+
+ `visible'
+ Consider only frames that are visible.
+
+ `iconic'
+ Consider only frames that are iconic.
+
+ `invisible'
+ Consider only frames that are invisible (this is different
+ from iconic).
+
+ `visible-iconic'
+ Consider frames that are visible or iconic.
+
+ `invisible-iconic'
+ Consider frames that are invisible or iconic.
+
+ `nomini'
+ Consider all frames except minibuffer-only ones.
+
+ `visible-nomini'
+ Like `visible' but omits minibuffer-only frames.
+
+ `iconic-nomini'
+ Like `iconic' but omits minibuffer-only frames.
+
+ `invisible-nomini'
+ Like `invisible' but omits minibuffer-only frames.
+
+ `visible-iconic-nomini'
+ Like `visible-iconic' but omits minibuffer-only frames.
+
+ `invisible-iconic-nomini'
+ Like `invisible-iconic' but omits minibuffer-only frames.
+
+ `nil'
+ Identical to `nomini'.
+
+ WINDOW
+ Consider only the window WINDOW's frame and any frame now
+ using WINDOW as the minibuffer.
+
+ any other value
+ Consider all frames.
+
+ The optional argument WHICH-DEVICES further clarifies on which
+ devices to search for frames as specified by WHICH-FRAMES.
+
+ `nil'
+ Consider all devices on the selected console.
+
+ DEVICE
+ Consider only the one device DEVICE.
+
+ CONSOLE
+ Consider all devices on CONSOLE.
+
+ DEVICE-TYPE
+ Consider all devices with device type DEVICE-TYPE.
+
+ `window-system'
+ Consider all devices on window system consoles.
+
+ anything else
+ Consider all devices without restriction.
+
+ - Function: previous-frame &optional frame which-frames which-devices
+ Like `next-frame', but cycles through all frames in the opposite
+ direction.
+
+ See also `next-window' and `previous-window', in *Note Cyclic Window
+Ordering::.
+
+\1f
+File: lispref.info, Node: Frames and Windows, Next: Minibuffers and Frames, Prev: Finding All Frames, Up: Frames
+
+Frames and Windows
+==================
+
+Each window is part of one and only one frame; you can get the frame
+with `window-frame'.
+
+ - Function: frame-root-window &optional frame
+ This returns the root window of frame FRAME. FRAME defaults to
+ the selected frame if not specified.
+
+ - Function: window-frame &optional window
+ This function returns the frame that WINDOW is on. WINDOW
+ defaults to the selected window if omitted.
+
+ All the non-minibuffer windows in a frame are arranged in a cyclic
+order. The order runs from the frame's top window, which is at the
+upper left corner, down and to the right, until it reaches the window at
+the lower right corner (always the minibuffer window, if the frame has
+one), and then it moves back to the top.
+
+ - Function: frame-highest-window &optional frame position
+ This function returns the topmost, leftmost window of frame FRAME
+ at position POSITION.
+
+ If omitted, FRAME defaults to the currently selected frame.
+
+ POSITION is used to distinguish between multiple windows that abut
+ the top of the frame: 0 means the leftmost window abutting the top
+ of the frame, 1 the next-leftmost, etc. POSITION can also be less
+ than zero: -1 means the rightmost window abutting the top of the
+ frame, -2 the next-rightmost, etc. If omitted, POSITION defaults
+ to 0, i.e. the leftmost highest window. If there is no window at
+ the given POSITION, `nil' is returned.
+
+ The following three functions work similarly.
+
+ - Function: frame-lowest-window &optional frame position
+ This function returns the lowest window on FRAME which is at
+ POSITION.
+
+ - Function: frame-leftmost-window &optional frame position
+ This function returns the leftmost window on FRAME which is at
+ POSITION.
+
+ - Function: frame-rightmost-window &optional frame position
+ This function returns the rightmost window on FRAME which is at
+ POSITION.
+
+ At any time, exactly one window on any frame is "selected within the
+frame". The significance of this designation is that selecting the
+frame also selects this window. You can get the frame's current
+selected window with `frame-selected-window'.
+
+ - Function: frame-selected-window &optional frame
+ This function returns the window on FRAME that is selected within
+ FRAME. FRAME defaults to the selected frame if not specified.
+
+ Conversely, selecting a window for XEmacs with `select-window' also
+makes that window selected within its frame. *Note Selecting Windows::.
+
+ Another function that (usually) returns one of the windows in a
+frame is `minibuffer-window'. *Note Minibuffer Misc::.
+
+\1f
+File: lispref.info, Node: Minibuffers and Frames, Next: Input Focus, Prev: Frames and Windows, Up: Frames
+
+Minibuffers and Frames
+======================
+
+Normally, each frame has its own minibuffer window at the bottom, which
+is used whenever that frame is selected. If the frame has a minibuffer,
+you can get it with `minibuffer-window' (*note Minibuffer Misc::).
+
+ However, you can also create a frame with no minibuffer. Such a
+frame must use the minibuffer window of some other frame. When you
+create the frame, you can specify explicitly the minibuffer window to
+use (in some other frame). If you don't, then the minibuffer is found
+in the frame which is the value of the variable
+`default-minibuffer-frame'. Its value should be a frame which does
+have a minibuffer.
+
+ - Variable: default-minibuffer-frame
+ This variable specifies the frame to use for the minibuffer
+ window, by default.
+
+\1f
+File: lispref.info, Node: Input Focus, Next: Visibility of Frames, Prev: Minibuffers and Frames, Up: Frames
+
+Input Focus
+===========
+
+At any time, one frame in XEmacs is the "selected frame". The selected
+window always resides on the selected frame. As the focus moves from
+device to device, the selected frame on each device is remembered and
+restored when the focus moves back to that device.
+
+ - Function: selected-frame &optional device
+ This function returns the selected frame on DEVICE. If DEVICE is
+ not specified, the selected device will be used. If no frames
+ exist on the device, `nil' is returned.
+
+ The X server normally directs keyboard input to the X window that the
+mouse is in. Some window managers use mouse clicks or keyboard events
+to "shift the focus" to various X windows, overriding the normal
+behavior of the server.
+
+ Lisp programs can switch frames "temporarily" by calling the
+function `select-frame'. This does not override the window manager;
+rather, it escapes from the window manager's control until that control
+is somehow reasserted.
+
+ When using a text-only terminal, there is no window manager;
+therefore, `select-frame' is the only way to switch frames, and the
+effect lasts until overridden by a subsequent call to `select-frame'.
+Only the selected terminal frame is actually displayed on the terminal.
+Each terminal screen except for the initial one has a number, and the
+number of the selected frame appears in the mode line after the word
+`XEmacs' (*note Modeline Variables::).
+
+ - Function: select-frame frame
+ This function selects frame FRAME, temporarily disregarding the
+ focus of the X server if any. The selection of FRAME lasts until
+ the next time the user does something to select a different frame,
+ or until the next time this function is called.
+
+ Note that `select-frame' does not actually cause the window-system
+ focus to be set to this frame, or the `select-frame-hook' or
+ `deselect-frame-hook' to be run, until the next time that XEmacs is
+ waiting for an event.
+
+ Also note that when the variable `focus-follows-mouse' is
+ non-`nil', the frame selection is temporary and is reverted when
+ the current command terminates, much like the buffer selected by
+ `set-buffer'. In order to effect a permanent focus change use
+ `focus-frame'.
+
+ - Function: focus-frame frame
+ This function selects FRAME and gives it the window system focus.
+ The operation of `focus-frame' is not affected by the value of
+ `focus-follows-mouse'.
+
+ - Special Form: save-selected-frame forms...
+ This special form records the selected frame, executes FORMS in
+ sequence, then restores the earlier selected frame. The value
+ returned is the value of the last form.
+
+ - Special Form: with-selected-frame frame forms...
+ This special form records the selected frame, then selects FRAME
+ and executes FORMS in sequence. After the last form is finished,
+ the earlier selected frame is restored. The value returned is the
+ value of the last form.
+
+\1f
+File: lispref.info, Node: Visibility of Frames, Next: Raising and Lowering, Prev: Input Focus, Up: Frames
+
+Visibility of Frames
+====================
+
+An frame on a window system may be "visible", "invisible", or
+"iconified". If it is visible, you can see its contents. If it is
+iconified, the frame's contents do not appear on the screen, but an icon
+does. If the frame is invisible, it doesn't show on the screen, not
+even as an icon.
+
+ Visibility is meaningless for TTY frames, since only the selected
+one is actually displayed in any case.
+
+ - Function: make-frame-visible &optional frame
+ This function makes frame FRAME visible. If you omit FRAME, it
+ makes the selected frame visible.
+
+ - Function: make-frame-invisible &optional frame force
+ This function makes frame FRAME invisible.
+
+ - Command: iconify-frame &optional frame
+ This function iconifies frame FRAME.
+
+ - Function: Command deiconify-frame &optional frame
+ This function de-iconifies frame FRAME. Under a window system,
+ this is equivalent to `make-frame-visible'.
+
+ - Function: frame-visible-p &optional frame
+ This returns whether FRAME is currently "visible" (actually in use
+ for display). A frame that is not visible is not updated, and, if
+ it works through a window system, may not show at all.
+
+ - Function: frame-iconified-p &optional frame
+ This returns whether FRAME is iconified. Not all window managers
+ use icons; some merely unmap the window, so this function is not
+ the inverse of `frame-visible-p'. It is possible for a frame to
+ not be visible and not be iconified either. However, if the frame
+ is iconified, it will not be visible. (Under FSF Emacs, the
+ functionality of this function is obtained through
+ `frame-visible-p'.)
+
+ - Function: frame-totally-visible-p &optional frame
+ This returns whether FRAME is not obscured by any other X windows.
+ On TTY frames, this is the same as `frame-visible-p'.
+
+\1f
+File: lispref.info, Node: Raising and Lowering, Next: Frame Configurations, Prev: Visibility of Frames, Up: Frames
+
+Raising and Lowering Frames
+===========================
+
+The X Window System uses a desktop metaphor. Part of this metaphor is
+the idea that windows are stacked in a notional third dimension
+perpendicular to the screen surface, and thus ordered from "highest" to
+"lowest". Where two windows overlap, the one higher up covers the one
+underneath. Even a window at the bottom of the stack can be seen if no
+other window overlaps it.
+
+ A window's place in this ordering is not fixed; in fact, users tend
+to change the order frequently. "Raising" a window means moving it
+"up", to the top of the stack. "Lowering" a window means moving it to
+the bottom of the stack. This motion is in the notional third
+dimension only, and does not change the position of the window on the
+screen.
+
+ You can raise and lower XEmacs's X windows with these functions:
+
+ - Command: raise-frame &optional frame
+ This function raises frame FRAME.
+
+ - Command: lower-frame &optional frame
+ This function lowers frame FRAME.
+
+ You can also specify auto-raise (raising automatically when a frame
+is selected) or auto-lower (lowering automatically when it is
+deselected). Under X, most ICCCM-compliant window managers will have
+an option to do this for you, but the following variables are provided
+in case you're using a broken WM. (Under FSF Emacs, the same
+functionality is provided through the `auto-raise' and `auto-lower'
+frame properties.)
+
+ - Variable: auto-raise-frame
+ This variable's value is `t' if frames will be raised to the top
+ when selected.
+
+ - Variable: auto-lower-frame
+ This variable's value is `t' if frames will be lowered to the
+ bottom when no longer selected.
+
+ Auto-raising and auto-lowering is implemented through functions
+attached to `select-frame-hook' and `deselect-frame-hook' (*note Frame
+Hooks::). Under normal circumstances, you should not call these
+functions directly.
+
+ - Function: default-select-frame-hook
+ This hook function implements the `auto-raise-frame' variable; it
+ is for use as the value of `select-frame-hook'.
+
+ - Function: default-deselect-frame-hook
+ This hook function implements the `auto-lower-frame' variable; it
+ is for use as the value of `deselect-frame-hook'.
+
+\1f
+File: lispref.info, Node: Frame Configurations, Next: Frame Hooks, Prev: Raising and Lowering, Up: Frames
+
+Frame Configurations
+====================
+
+A "frame configuration" records the current arrangement of frames, all
+their properties, and the window configuration of each one.
+
+ - Function: current-frame-configuration
+ This function returns a frame configuration list that describes
+ the current arrangement of frames and their contents.
+
+ - Function: set-frame-configuration configuration &optional nodelete
+ This function restores the state of frames described by
+ CONFIGURATION, which should be the return value from a previous
+ call to `current-frame-configuration'.
+
+ Each frame listed in CONFIGURATION has its position, size, window
+ configuration, and other properties set as specified in
+ CONFIGURATION.
+
+ Ordinarily, this function deletes all existing frames not listed in
+ CONFIGURATION. But if optional second argument NODELETE is
+ non-`nil', the unwanted frames are iconified instead.
+
+\1f
+File: lispref.info, Node: Frame Hooks, Prev: Frame Configurations, Up: Frames
+
+Hooks for Customizing Frame Behavior
+====================================
+
+XEmacs provides many hooks that are called at various times during a
+frame's lifetime. *Note Hooks::.
+
+ - Variable: create-frame-hook
+ This hook is called each time a frame is created. The functions
+ are called with one argument, the newly-created frame.
+
+ - Variable: delete-frame-hook
+ This hook is called each time a frame is deleted. The functions
+ are called with one argument, the about-to-be-deleted frame.
+
+ - Variable: select-frame-hook
+ This is a normal hook that is run just after a frame is selected.
+ The function `default-select-frame-hook', which implements
+ auto-raising (*note Raising and Lowering::), is normally attached
+ to this hook.
+
+ Note that calling `select-frame' does not necessarily set the
+ focus: The actual window-system focus will not be changed until
+ the next time that XEmacs is waiting for an event, and even then,
+ the window manager may refuse the focus-change request.
+
+ - Variable: deselect-frame-hook
+ This is a normal hook that is run just before a frame is deselected
+ (and another frame is selected). The function
+ `default-deselect-frame-hook', which implements auto-lowering
+ (*note Raising and Lowering::), is normally attached to this hook.
+
+ - Variable: map-frame-hook
+ This hook is called each time a frame is mapped (i.e. made
+ visible). The functions are called with one argument, the newly
+ mapped frame.
+
+ - Variable: unmap-frame-hook
+ This hook is called each time a frame is unmapped (i.e. made
+ invisible or iconified). The functions are called with one
+ argument, the newly unmapped frame.
+
+\1f
+File: lispref.info, Node: Consoles and Devices, Next: Positions, Prev: Frames, Up: Top
+
+Consoles and Devices
+********************
+
+A "console" is an object representing a single input connection to
+XEmacs, such as an X display or a TTY connection. It is possible for
+XEmacs to have frames on multiple consoles at once (even on
+heterogeneous types--you can simultaneously have a frame on an X
+display and a TTY connection). Normally, there is only one console in
+existence.
+
+ A "device" is an object representing a single output device, such as
+a particular screen on an X display. (Usually there is exactly one
+device per X console connection, but there may be more than one if you
+have a multi-headed X display. For TTY connections, there is always
+exactly one device per console.)
+
+ Each device has one or more "frames" in which text can be displayed.
+For X displays and the like, a frame corresponds to the normal
+window-system concept of a window. Frames can overlap, be displayed at
+various locations within the display, be resized, etc. For TTY, only
+one frame can be displayed at a time, and it occupies the entire TTY
+display area.
+
+ However, you can still define multiple frames and switch between
+them. Their contents are entirely separate from each other. These
+sorts of frames resemble the "virtual console" capability provided
+under Linux or the multiple screens provided by the multiplexing program
+`screen' under Unix.
+
+ When you start up XEmacs, an initial console and device are created
+to receive input and display frames on. This will either be an X
+display or a TTY connection, depending on what mode you started XEmacs
+in (this is determined by the `DISPLAY' environment variable, the
+`-nw', `-t' and `-display' command-line options, etc.).
+
+ You can connect to other X displays and TTY connections by creating
+new console objects, and to other X screens on an existing display by
+creating new device objects, as described below. Many functions (for
+example the frame-creation functions) take an optional device argument
+specifying which device the function pertains to. If the argument is
+omitted, it defaults to the selected device (see below).
+
+ - Function: consolep object
+ This returns non-`nil' if OBJECT is a console.
+
+ - Function: devicep object
+ This returns non-`nil' if OBJECT is a device.
+
+* Menu:
+
+* Basic Console Functions:: Functions for working with consoles.
+* Basic Device Functions:: Functions for working with devices.
+* Console Types and Device Classes::
+ I/O and color characteristics.
+* Connecting to a Console or Device::
+* The Selected Console and Device::
+* Console and Device I/O:: Controlling input and output.
+
+\1f
+File: lispref.info, Node: Basic Console Functions, Next: Basic Device Functions, Up: Consoles and Devices
+
+Basic Console Functions
+=======================
+
+ - Function: console-list
+ This function returns a list of all existing consoles.
+
+ - Function: console-device-list &optional console
+ This function returns a list of all devices on CONSOLE. If
+ CONSOLE is `nil', the selected console will be used.
+
+\1f
+File: lispref.info, Node: Basic Device Functions, Next: Console Types and Device Classes, Prev: Basic Console Functions, Up: Consoles and Devices
+
+Basic Device Functions
+======================
+
+ - Function: device-list
+ This function returns a list of all existing devices.
+
+ - Function: device-or-frame-p object
+ This function returns non-`nil' if OBJECT is a device or frame.
+ This function is useful because devices and frames are similar in
+ many respects and many functions can operate on either one.
+
+ - Function: device-frame-list &optional device
+ This function returns a list of all frames on DEVICE. DEVICE
+ defaults to the currently selected device.
+
+ - Function: frame-device &optional frame
+ This function returns the device that FRAME is on. FRAME defaults
+ to the currently selected frame.
+
+\1f
+File: lispref.info, Node: Console Types and Device Classes, Next: Connecting to a Console or Device, Prev: Basic Device Functions, Up: Consoles and Devices
+
+Console Types and Device Classes
+================================
+
+Every device is of a particular "type", which describes how the
+connection to that device is made and how the device operates, and a
+particular "class", which describes other characteristics of the device
+(currently, the color capabilities of the device).
+
+ The currently-defined device types are
+
+`x'
+ A connection to an X display (such as `willow:0').
+
+`tty'
+ A connection to a tty (such as `/dev/ttyp3').
+
+`stream'
+ A stdio connection. This describes a device for which input and
+ output is only possible in a stream-like fashion, such as when
+ XEmacs in running in batch mode. The very first device created by
+ XEmacs is a terminal device and is used to print out messages of
+ various sorts (for example, the help message when you use the
+ `-help' command-line option).
+
+ The currently-defined device classes are
+`color'
+ A color device.
+
+`grayscale'
+ A grayscale device (a device that can display multiple shades of
+ gray, but no color).
+
+`mono'
+ A device that can only display two colors (e.g. black and white).
+
+ - Function: device-type &optional device
+ This function returns the type of DEVICE. This is a symbol whose
+ name is one of the device types mentioned above. DEVICE defaults
+ to the selected device.
+
+ - Function: device-or-frame-type device-or-frame
+ This function returns the type of DEVICE-OR-FRAME.
+
+ - Function: device-class &optional device
+ This function returns the class (color behavior) of DEVICE. This
+ is a symbol whose name is one of the device classes mentioned
+ above.
+
+ - Function: valid-device-type-p device-type
+ This function returns whether DEVICE-TYPE (which should be a
+ symbol) specifies a valid device type.
+
+ - Function: valid-device-class-p device-class
+ This function returns whether DEVICE-CLASS (which should be a
+ symbol) specifies a valid device class.
+
+ - Variable: terminal-device
+ This variable holds the initial terminal device object, which
+ represents XEmacs's stdout.
+
+\1f
+File: lispref.info, Node: Connecting to a Console or Device, Next: The Selected Console and Device, Prev: Console Types and Device Classes, Up: Consoles and Devices
+
+Connecting to a Console or Device
+=================================
+
+ - Function: make-device type connection &optional props
+ This function creates a new device.
+
+ The following two functions create devices of specific types and are
+written in terms of `make-device'.
+
+ - Function: make-tty-device &optional tty terminal-type
+ This function creates a new tty device on TTY. This also creates
+ the tty's first frame. TTY should be a string giving the name of
+ a tty device file (e.g. `/dev/ttyp3' under SunOS et al.), as
+ returned by the `tty' command issued from the Unix shell. A value
+ of `nil' means use the stdin and stdout as passed to XEmacs from
+ the shell. If TERMINAL-TYPE is non-`nil', it should be a string
+ specifying the type of the terminal attached to the specified tty.
+ If it is `nil', the terminal type will be inferred from the
+ `TERM' environment variable.
+
+ - Function: make-x-device &optional display argv-list
+ This function creates a new device connected to DISPLAY. Optional
+ argument ARGV-LIST is a list of strings describing command line
+ options.
+
+ - Function: delete-device device &optional force
+ This function deletes DEVICE, permanently eliminating it from use.
+ This disconnects XEmacs's connection to the device.
+
+ - Variable: create-device-hook
+ This variable, if non-`nil', should contain a list of functions,
+ which are called when a device is created.
+
+ - Variable: delete-device-hook
+ This variable, if non-`nil', should contain a list of functions,
+ which are called when a device is deleted.
+
+ - Function: console-live-p object
+ This function returns non-`nil' if OBJECT is a console that has
+ not been deleted.
+
+ - Function: device-live-p object
+ This function returns non-`nil' if OBJECT is a device that has not
+ been deleted.
+
+ - Function: device-x-display device
+ This function returns the X display which DEVICE is connected to,
+ if DEVICE is an X device.
+
+\1f
+File: lispref.info, Node: The Selected Console and Device, Next: Console and Device I/O, Prev: Connecting to a Console or Device, Up: Consoles and Devices
+
+The Selected Console and Device
+===============================
+
+ - Function: select-console console
+ This function selects the console CONSOLE. Subsequent editing
+ commands apply to its selected device, selected frame, and selected
+ window. The selection of CONSOLE lasts until the next time the
+ user does something to select a different console, or until the
+ next time this function is called.
+
+ - Function: selected-console
+ This function returns the console which is currently active.
+
+ - Function: select-device device
+ This function selects the device DEVICE.
+
+ - Function: selected-device &optional console
+ This function returns the device which is currently active. If
+ optional CONSOLE is non-`nil', this function returns the device
+ that would be currently active if CONSOLE were the selected
+ console.
+
+\1f
+File: lispref.info, Node: Console and Device I/O, Prev: The Selected Console and Device, Up: Consoles and Devices
+
+Console and Device I/O
+======================
+
+ - Function: console-disable-input console
+ This function disables input on console CONSOLE.
+
+ - Function: console-enable-input console
+ This function enables input on console CONSOLE.
+
+ Each device has a "baud rate" value associated with it. On most
+systems, changing this value will affect the amount of padding and
+other strategic decisions made during redisplay.
+
+ - Function: device-baud-rate &optional device
+ This function returns the output baud rate of DEVICE.
+
+ - Function: set-device-baud-rate device rate
+ This function sets the output baud rate of DEVICE to RATE.
+
+\1f
+File: lispref.info, Node: Positions, Next: Markers, Prev: Consoles and Devices, Up: Top
+
+Positions
+*********
+
+A "position" is the index of a character in the text of a buffer. More
+precisely, a position identifies the place between two characters (or
+before the first character, or after the last character), so we can
+speak of the character before or after a given position. However, we
+often speak of the character "at" a position, meaning the character
+after that position.
+
+ Positions are usually represented as integers starting from 1, but
+can also be represented as "markers"--special objects that relocate
+automatically when text is inserted or deleted so they stay with the
+surrounding characters. *Note Markers::.
+
+* Menu:
+
+* Point:: The special position where editing takes place.
+* Motion:: Changing point.
+* Excursions:: Temporary motion and buffer changes.
+* Narrowing:: Restricting editing to a portion of the buffer.
+
+\1f
+File: lispref.info, Node: Point, Next: Motion, Up: Positions
+
+Point
+=====
+
+"Point" is a special buffer position used by many editing commands,
+including the self-inserting typed characters and text insertion
+functions. Other commands move point through the text to allow editing
+and insertion at different places.
+
+ Like other positions, point designates a place between two characters
+(or before the first character, or after the last character), rather
+than a particular character. Usually terminals display the cursor over
+the character that immediately follows point; point is actually before
+the character on which the cursor sits.
+
+ The value of point is a number between 1 and the buffer size plus 1.
+If narrowing is in effect (*note Narrowing::), then point is constrained
+to fall within the accessible portion of the buffer (possibly at one end
+of it).
+
+ Each buffer has its own value of point, which is independent of the
+value of point in other buffers. Each window also has a value of point,
+which is independent of the value of point in other windows on the same
+buffer. This is why point can have different values in various windows
+that display the same buffer. When a buffer appears in only one window,
+the buffer's point and the window's point normally have the same value,
+so the distinction is rarely important. *Note Window Point::, for more
+details.
+
+ - Function: point &optional buffer
+ This function returns the value of point in BUFFER, as an integer.
+ BUFFER defaults to the current buffer if omitted.
+
+ (point)
+ => 175
+
+ - Function: point-min &optional buffer
+ This function returns the minimum accessible value of point in
+ BUFFER. This is normally 1, but if narrowing is in effect, it is
+ the position of the start of the region that you narrowed to.
+ (*Note Narrowing::.) BUFFER defaults to the current buffer if
+ omitted.
+
+ - Function: point-max &optional buffer
+ This function returns the maximum accessible value of point in
+ BUFFER. This is `(1+ (buffer-size buffer))', unless narrowing is
+ in effect, in which case it is the position of the end of the
+ region that you narrowed to. (*note Narrowing::). BUFFER defaults
+ to the current buffer if omitted.
+
+ - Function: buffer-end flag &optional buffer
+ This function returns `(point-min buffer)' if FLAG is less than 1,
+ `(point-max buffer)' otherwise. The argument FLAG must be a
+ number. BUFFER defaults to the current buffer if omitted.
+
+ - Function: buffer-size &optional buffer
+ This function returns the total number of characters in BUFFER.
+ In the absence of any narrowing (*note Narrowing::), `point-max'
+ returns a value one larger than this. BUFFER defaults to the
+ current buffer if omitted.
+
+ (buffer-size)
+ => 35
+ (point-max)
+ => 36
+
+ - Variable: buffer-saved-size
+ The value of this buffer-local variable is the former length of the
+ current buffer, as of the last time it was read in, saved or
+ auto-saved.
+
+\1f
+File: lispref.info, Node: Motion, Next: Excursions, Prev: Point, Up: Positions
+
+Motion
+======
+
+Motion functions change the value of point, either relative to the
+current value of point, relative to the beginning or end of the buffer,
+or relative to the edges of the selected window. *Note Point::.
+
+* Menu:
+
+* Character Motion:: Moving in terms of characters.
+* Word Motion:: Moving in terms of words.
+* Buffer End Motion:: Moving to the beginning or end of the buffer.
+* Text Lines:: Moving in terms of lines of text.
+* Screen Lines:: Moving in terms of lines as displayed.
+* List Motion:: Moving by parsing lists and sexps.
+* Skipping Characters:: Skipping characters belonging to a certain set.
+
+\1f
+File: lispref.info, Node: Character Motion, Next: Word Motion, Up: Motion
+
+Motion by Characters
+--------------------
+
+These functions move point based on a count of characters. `goto-char'
+is the fundamental primitive; the other functions use that.
+
+ - Command: goto-char position &optional buffer
+ This function sets point in `buffer' to the value POSITION. If
+ POSITION is less than 1, it moves point to the beginning of the
+ buffer. If POSITION is greater than the length of the buffer, it
+ moves point to the end. BUFFER defaults to the current buffer if
+ omitted.
+
+ If narrowing is in effect, POSITION still counts from the
+ beginning of the buffer, but point cannot go outside the accessible
+ portion. If POSITION is out of range, `goto-char' moves point to
+ the beginning or the end of the accessible portion.
+
+ When this function is called interactively, POSITION is the
+ numeric prefix argument, if provided; otherwise it is read from the
+ minibuffer.
+
+ `goto-char' returns POSITION.
+
+ - Command: forward-char &optional count buffer
+ This function moves point COUNT characters forward, towards the
+ end of the buffer (or backward, towards the beginning of the
+ buffer, if COUNT is negative). If the function attempts to move
+ point past the beginning or end of the buffer (or the limits of
+ the accessible portion, when narrowing is in effect), an error is
+ signaled with error code `beginning-of-buffer' or `end-of-buffer'.
+ BUFFER defaults to the current buffer if omitted.
+
+ In an interactive call, COUNT is the numeric prefix argument.
+
+ - Command: backward-char &optional count buffer
+ This function moves point COUNT characters backward, towards the
+ beginning of the buffer (or forward, towards the end of the
+ buffer, if COUNT is negative). If the function attempts to move
+ point past the beginning or end of the buffer (or the limits of
+ the accessible portion, when narrowing is in effect), an error is
+ signaled with error code `beginning-of-buffer' or `end-of-buffer'.
+ BUFFER defaults to the current buffer if omitted.
+
+ In an interactive call, COUNT is the numeric prefix argument.
+
+\1f
+File: lispref.info, Node: Word Motion, Next: Buffer End Motion, Prev: Character Motion, Up: Motion
+
+Motion by Words
+---------------
+
+These functions for parsing words use the syntax table to decide
+whether a given character is part of a word. *Note Syntax Tables::.
+
+ - Command: forward-word &optional count buffer
+ This function moves point forward COUNT words (or backward if
+ COUNT is negative). Normally it returns `t'. If this motion
+ encounters the beginning or end of the buffer, or the limits of the
+ accessible portion when narrowing is in effect, point stops there
+ and the value is `nil'.
+
+ COUNT defaults to `1' and BUFFER defaults to the current buffer.
+
+ In an interactive call, COUNT is set to the numeric prefix
+ argument.
+
+ - Command: backward-word &optional count buffer
+ This function is just like `forward-word', except that it moves
+ backward until encountering the front of a word, rather than
+ forward. BUFFER defaults to the current buffer if omitted.
+
+ In an interactive call, COUNT is set to the numeric prefix
+ argument.
+
+ - Variable: words-include-escapes
+ This variable affects the behavior of `forward-word' and everything
+ that uses it. If it is non-`nil', then characters in the "escape"
+ and "character quote" syntax classes count as part of words.
+ Otherwise, they do not.
+
+\1f
+File: lispref.info, Node: Buffer End Motion, Next: Text Lines, Prev: Word Motion, Up: Motion
+
+Motion to an End of the Buffer
+------------------------------
+
+To move point to the beginning of the buffer, write:
+
+ (goto-char (point-min))
+
+Likewise, to move to the end of the buffer, use:
+
+ (goto-char (point-max))
+
+ Here are two commands that users use to do these things. They are
+documented here to warn you not to use them in Lisp programs, because
+they set the mark and display messages in the echo area.
+
+ - Command: beginning-of-buffer &optional count
+ This function moves point to the beginning of the buffer (or the
+ limits of the accessible portion, when narrowing is in effect),
+ setting the mark at the previous position. If COUNT is non-`nil',
+ then it puts point COUNT tenths of the way from the beginning of
+ the buffer.
+
+ In an interactive call, COUNT is the numeric prefix argument, if
+ provided; otherwise COUNT defaults to `nil'.
+
+ Don't use this function in Lisp programs!
+
+ - Command: end-of-buffer &optional count
+ This function moves point to the end of the buffer (or the limits
+ of the accessible portion, when narrowing is in effect), setting
+ the mark at the previous position. If COUNT is non-`nil', then it
+ puts point COUNT tenths of the way from the end of the buffer.
+
+ In an interactive call, COUNT is the numeric prefix argument, if
+ provided; otherwise COUNT defaults to `nil'.
+
+ Don't use this function in Lisp programs!
+
+\1f
+File: lispref.info, Node: Text Lines, Next: Screen Lines, Prev: Buffer End Motion, Up: Motion
+
+Motion by Text Lines
+--------------------
+
+Text lines are portions of the buffer delimited by newline characters,
+which are regarded as part of the previous line. The first text line
+begins at the beginning of the buffer, and the last text line ends at
+the end of the buffer whether or not the last character is a newline.
+The division of the buffer into text lines is not affected by the width
+of the window, by line continuation in display, or by how tabs and
+control characters are displayed.
+
+ - Command: goto-line line
+ This function moves point to the front of the LINEth line,
+ counting from line 1 at beginning of the buffer. If LINE is less
+ than 1, it moves point to the beginning of the buffer. If LINE is
+ greater than the number of lines in the buffer, it moves point to
+ the end of the buffer--that is, the _end of the last line_ of the
+ buffer. This is the only case in which `goto-line' does not
+ necessarily move to the beginning of a line.
+
+ If narrowing is in effect, then LINE still counts from the
+ beginning of the buffer, but point cannot go outside the accessible
+ portion. So `goto-line' moves point to the beginning or end of the
+ accessible portion, if the line number specifies an inaccessible
+ position.
+
+ The return value of `goto-line' is the difference between LINE and
+ the line number of the line to which point actually was able to
+ move (in the full buffer, before taking account of narrowing).
+ Thus, the value is positive if the scan encounters the real end of
+ the buffer. The value is zero if scan encounters the end of the
+ accessible portion but not the real end of the buffer.
+
+ In an interactive call, LINE is the numeric prefix argument if one
+ has been provided. Otherwise LINE is read in the minibuffer.
+
+ - Command: beginning-of-line &optional count buffer
+ This function moves point to the beginning of the current line.
+ With an argument COUNT not `nil' or 1, it moves forward COUNT-1
+ lines and then to the beginning of the line. BUFFER defaults to
+ the current buffer if omitted.
+
+ If this function reaches the end of the buffer (or of the
+ accessible portion, if narrowing is in effect), it positions point
+ there. No error is signaled.
+
+ - Command: end-of-line &optional count buffer
+ This function moves point to the end of the current line. With an
+ argument COUNT not `nil' or 1, it moves forward COUNT-1 lines and
+ then to the end of the line. BUFFER defaults to the current
+ buffer if omitted.
+
+ If this function reaches the end of the buffer (or of the
+ accessible portion, if narrowing is in effect), it positions point
+ there. No error is signaled.
+
+ - Command: forward-line &optional count buffer
+ This function moves point forward COUNT lines, to the beginning of
+ the line. If COUNT is negative, it moves point -COUNT lines
+ backward, to the beginning of a line. If COUNT is zero, it moves
+ point to the beginning of the current line. BUFFER defaults to
+ the current buffer if omitted.
+
+ If `forward-line' encounters the beginning or end of the buffer (or
+ of the accessible portion) before finding that many lines, it sets
+ point there. No error is signaled.
+
+ `forward-line' returns the difference between COUNT and the number
+ of lines actually moved. If you attempt to move down five lines
+ from the beginning of a buffer that has only three lines, point
+ stops at the end of the last line, and the value will be 2.
+
+ In an interactive call, COUNT is the numeric prefix argument.
+
+ - Function: count-lines start end &optional ignore-invisible-lines-flag
+ This function returns the number of lines between the positions
+ START and END in the current buffer. If START and END are equal,
+ then it returns 0. Otherwise it returns at least 1, even if START
+ and END are on the same line. This is because the text between
+ them, considered in isolation, must contain at least one line
+ unless it is empty.
+
+ With optional IGNORE-INVISIBLE-LINES-FLAG non-`nil', lines
+ collapsed with selective-display are excluded from the line count.
+
+ *Note:* The expression to return the current line number is not
+ obvious:
+
+ (1+ (count-lines 1 (point-at-bol)))
+
+ Here is an example of using `count-lines':
+
+ (defun current-line ()
+ "Return the vertical position of point..."
+ (+ (count-lines (window-start) (point))
+ (if (= (current-column) 0) 1 0)
+ -1))
+
+ Also see the functions `bolp' and `eolp' in *Note Near Point::.
+These functions do not move point, but test whether it is already at the
+beginning or end of a line.
+
+\1f
+File: lispref.info, Node: Screen Lines, Next: List Motion, Prev: Text Lines, Up: Motion
+
+Motion by Screen Lines
+----------------------
+
+The line functions in the previous section count text lines, delimited
+only by newline characters. By contrast, these functions count screen
+lines, which are defined by the way the text appears on the screen. A
+text line is a single screen line if it is short enough to fit the width
+of the selected window, but otherwise it may occupy several screen
+lines.
+
+ In some cases, text lines are truncated on the screen rather than
+continued onto additional screen lines. In these cases,
+`vertical-motion' moves point much like `forward-line'. *Note
+Truncation::.
+
+ Because the width of a given string depends on the flags that control
+the appearance of certain characters, `vertical-motion' behaves
+differently, for a given piece of text, depending on the buffer it is
+in, and even on the selected window (because the width, the truncation
+flag, and display table may vary between windows). *Note Usual
+Display::.
+
+ These functions scan text to determine where screen lines break, and
+thus take time proportional to the distance scanned. If you intend to
+use them heavily, Emacs provides caches which may improve the
+performance of your code. *Note cache-long-line-scans: Text Lines.
+
+ - Function: vertical-motion count &optional window pixels
+ This function moves point to the start of the frame line COUNT
+ frame lines down from the frame line containing point. If COUNT
+ is negative, it moves up instead. The optional second argument
+ WINDOW may be used to specify a window other than the selected
+ window in which to perform the motion.
+
+ Normally, `vertical-motion' returns the number of lines moved. The
+ value may be less in absolute value than COUNT if the beginning or
+ end of the buffer was reached. If the optional third argument,
+ PIXELS is non-`nil', the vertical pixel height of the motion which
+ took place is returned instead of the actual number of lines
+ moved. A motion of zero lines returns the height of the current
+ line.
+
+ Note that `vertical-motion' sets WINDOW's buffer's point, not
+ WINDOW's point. (This differs from FSF Emacs, which buggily always
+ sets current buffer's point, regardless of WINDOW.)
+
+ - Function: vertical-motion-pixels count &optional window how
+ This function moves point to the start of the frame line PIXELS
+ vertical pixels down from the frame line containing point, or up if
+ PIXELS is negative. The optional second argument WINDOW is the
+ window to move in, and defaults to the selected window. The
+ optional third argument HOW specifies the stopping condition. A
+ negative integer indicates that the motion should be no more than
+ PIXELS. A positive value indicates that the motion should be at
+ least PIXELS. Any other value indicates that the motion should be
+ as close as possible to PIXELS.
+
+ - Command: move-to-window-line count &optional window
+ This function moves point with respect to the text currently
+ displayed in WINDOW, which defaults to the selected window. It
+ moves point to the beginning of the screen line COUNT screen lines
+ from the top of the window. If COUNT is negative, that specifies a
+ position -COUNT lines from the bottom (or the last line of the
+ buffer, if the buffer ends above the specified screen position).
+
+ If COUNT is `nil', then point moves to the beginning of the line
+ in the middle of the window. If the absolute value of COUNT is
+ greater than the size of the window, then point moves to the place
+ that would appear on that screen line if the window were tall
+ enough. This will probably cause the next redisplay to scroll to
+ bring that location onto the screen.
+
+ In an interactive call, COUNT is the numeric prefix argument.
+
+ The value returned is the window line number point has moved to,
+ with the top line in the window numbered 0.
+
+\1f
+File: lispref.info, Node: List Motion, Next: Skipping Characters, Prev: Screen Lines, Up: Motion
+
+Moving over Balanced Expressions
+--------------------------------
+
+Here are several functions concerned with balanced-parenthesis
+expressions (also called "sexps" in connection with moving across them
+in XEmacs). The syntax table controls how these functions interpret
+various characters; see *Note Syntax Tables::. *Note Parsing
+Expressions::, for lower-level primitives for scanning sexps or parts of
+sexps. For user-level commands, see *Note Lists and Sexps:
+(xemacs)Lists and Sexps.
+
+ - Command: forward-list &optional arg
+ This function moves forward across ARG balanced groups of
+ parentheses. (Other syntactic entities such as words or paired
+ string quotes are ignored.) ARG defaults to 1 if omitted. If ARG
+ is negative, move backward across that many groups of parentheses.
+
+ - Command: backward-list &optional count
+ This function moves backward across COUNT balanced groups of
+ parentheses. (Other syntactic entities such as words or paired
+ string quotes are ignored.) COUNT defaults to 1 if omitted. If
+ COUNT is negative, move forward across that many groups of
+ parentheses.
+
+ - Command: up-list &optional count
+ This function moves forward out of COUNT levels of parentheses. A
+ negative argument means move backward but still to a less deep
+ spot.
+
+ - Command: down-list &optional count
+ This function moves forward into COUNT levels of parentheses. A
+ negative argument means move backward but still go deeper in
+ parentheses (-COUNT levels).
+
+ - Command: forward-sexp &optional count
+ This function moves forward across COUNT balanced expressions.
+ Balanced expressions include both those delimited by parentheses
+ and other kinds, such as words and string constants. COUNT
+ defaults to 1 if omitted. If COUNT is negative, move backward
+ across that many balanced expressions. For example,
+
+ ---------- Buffer: foo ----------
+ (concat-!- "foo " (car x) y z)
+ ---------- Buffer: foo ----------
+
+ (forward-sexp 3)
+ => nil
+
+ ---------- Buffer: foo ----------
+ (concat "foo " (car x) y-!- z)
+ ---------- Buffer: foo ----------
+
+ - Command: backward-sexp &optional count
+ This function moves backward across COUNT balanced expressions.
+ COUNT defaults to 1 if omitted. If COUNT is negative, move
+ forward across that many balanced expressions.
+
+ - Command: beginning-of-defun &optional count
+ This function moves back to the COUNTth beginning of a defun. If
+ COUNT is negative, this actually moves forward, but it still moves
+ to the beginning of a defun, not to the end of one. COUNT
+ defaults to 1 if omitted.
+
+ - Command: end-of-defun &optional count
+ This function moves forward to the COUNTth end of a defun. If
+ COUNT is negative, this actually moves backward, but it still
+ moves to the end of a defun, not to the beginning of one. COUNT
+ defaults to 1 if omitted.
+
+ - User Option: defun-prompt-regexp
+ If non-`nil', this variable holds a regular expression that
+ specifies what text can appear before the open-parenthesis that
+ starts a defun. That is to say, a defun begins on a line that
+ starts with a match for this regular expression, followed by a
+ character with open-parenthesis syntax.
+
+\1f
+File: lispref.info, Node: Skipping Characters, Prev: List Motion, Up: Motion
+
+Skipping Characters
+-------------------
+
+The following two functions move point over a specified set of
+characters. For example, they are often used to skip whitespace. For
+related functions, see *Note Motion and Syntax::.
+
+ - Function: skip-chars-forward character-set &optional limit buffer
+ This function moves point in BUFFER forward, skipping over a given
+ set of characters. It examines the character following point,
+ then advances point if the character matches CHARACTER-SET. This
+ continues until it reaches a character that does not match. The
+ function returns `nil'. BUFFER defaults to the current buffer if
+ omitted.
+
+ The argument CHARACTER-SET is like the inside of a `[...]' in a
+ regular expression except that `]' is never special and `\' quotes
+ `^', `-' or `\'. Thus, `"a-zA-Z"' skips over all letters,
+ stopping before the first non-letter, and `"^a-zA-Z'" skips
+ non-letters stopping before the first letter. *Note Regular
+ Expressions::.
+
+ If LIMIT is supplied (it must be a number or a marker), it
+ specifies the maximum position in the buffer that point can be
+ skipped to. Point will stop at or before LIMIT.
+
+ In the following example, point is initially located directly
+ before the `T'. After the form is evaluated, point is located at
+ the end of that line (between the `t' of `hat' and the newline).
+ The function skips all letters and spaces, but not newlines.
+
+ ---------- Buffer: foo ----------
+ I read "-!-The cat in the hat
+ comes back" twice.
+ ---------- Buffer: foo ----------
+
+ (skip-chars-forward "a-zA-Z ")
+ => nil
+
+ ---------- Buffer: foo ----------
+ I read "The cat in the hat-!-
+ comes back" twice.
+ ---------- Buffer: foo ----------
+
+ - Function: skip-chars-backward character-set &optional limit buffer
+ This function moves point backward, skipping characters that match
+ CHARACTER-SET, until LIMIT. It just like `skip-chars-forward'
+ except for the direction of motion.
+
+\1f
+File: lispref.info, Node: Excursions, Next: Narrowing, Prev: Motion, Up: Positions
+
+Excursions
+==========
+
+It is often useful to move point "temporarily" within a localized
+portion of the program, or to switch buffers temporarily. This is
+called an "excursion", and it is done with the `save-excursion' special
+form. This construct saves the current buffer and its values of point
+and the mark so they can be restored after the completion of the
+excursion.
+
+ The forms for saving and restoring the configuration of windows are
+described elsewhere (see *Note Window Configurations:: and *note Frame
+Configurations::).
+
+ - Special Form: save-excursion forms...
+ The `save-excursion' special form saves the identity of the current
+ buffer and the values of point and the mark in it, evaluates
+ FORMS, and finally restores the buffer and its saved values of
+ point and the mark. All three saved values are restored even in
+ case of an abnormal exit via `throw' or error (*note Nonlocal
+ Exits::).
+
+ The `save-excursion' special form is the standard way to switch
+ buffers or move point within one part of a program and avoid
+ affecting the rest of the program. It is used more than 500 times
+ in the Lisp sources of XEmacs.
+
+ `save-excursion' does not save the values of point and the mark for
+ other buffers, so changes in other buffers remain in effect after
+ `save-excursion' exits.
+
+ Likewise, `save-excursion' does not restore window-buffer
+ correspondences altered by functions such as `switch-to-buffer'.
+ One way to restore these correspondences, and the selected window,
+ is to use `save-window-excursion' inside `save-excursion' (*note
+ Window Configurations::).
+
+ The value returned by `save-excursion' is the result of the last of
+ FORMS, or `nil' if no FORMS are given.
+
+ (save-excursion
+ FORMS)
+ ==
+ (let ((old-buf (current-buffer))
+ (old-pnt (point-marker))
+ (old-mark (copy-marker (mark-marker))))
+ (unwind-protect
+ (progn FORMS)
+ (set-buffer old-buf)
+ (goto-char old-pnt)
+ (set-marker (mark-marker) old-mark)))
+
+ - Special Form: save-current-buffer forms...
+ This special form is similar to `save-excursion' but it only saves
+ and restores the current buffer. Beginning with XEmacs 20.3,
+ `save-current-buffer' is a primitive.
+
+ - Special Form: with-current-buffer buffer forms...
+ This special form evaluates FORMS with BUFFER as the current
+ buffer. It returns the value of the last form.
+
+ - Special Form: with-temp-file filename forms...
+ This special form creates a new buffer, evaluates FORMS there, and
+ writes the buffer to FILENAME. It returns the value of the last
+ form evaluated.
+
+ - Special Form: save-selected-window forms...
+ This special form is similar to `save-excursion' but it saves and
+ restores the selected window and nothing else.
+
+\1f
+File: lispref.info, Node: Narrowing, Prev: Excursions, Up: Positions
+
+Narrowing
+=========
+
+"Narrowing" means limiting the text addressable by XEmacs editing
+commands to a limited range of characters in a buffer. The text that
+remains addressable is called the "accessible portion" of the buffer.
+
+ Narrowing is specified with two buffer positions which become the
+beginning and end of the accessible portion. For most editing commands
+and most Emacs primitives, these positions replace the values of the
+beginning and end of the buffer. While narrowing is in effect, no text
+outside the accessible portion is displayed, and point cannot move
+outside the accessible portion.
+
+ Values such as positions or line numbers, which usually count from
+the beginning of the buffer, do so despite narrowing, but the functions
+which use them refuse to operate on text that is inaccessible.
+
+ The commands for saving buffers are unaffected by narrowing; they
+save the entire buffer regardless of any narrowing.
+
+ - Command: narrow-to-region start end &optional buffer
+ This function sets the accessible portion of BUFFER to start at
+ START and end at END. Both arguments should be character
+ positions. BUFFER defaults to the current buffer if omitted.
+
+ In an interactive call, START and END are set to the bounds of the
+ current region (point and the mark, with the smallest first).
+
+ - Command: narrow-to-page &optional move-count
+ This function sets the accessible portion of the current buffer to
+ include just the current page. An optional first argument
+ MOVE-COUNT non-`nil' means to move forward or backward by
+ MOVE-COUNT pages and then narrow. The variable `page-delimiter'
+ specifies where pages start and end (*note Standard Regexps::).
+
+ In an interactive call, MOVE-COUNT is set to the numeric prefix
+ argument.
+
+ - Command: widen &optional buffer
+ This function cancels any narrowing in BUFFER, so that the entire
+ contents are accessible. This is called "widening". It is
+ equivalent to the following expression:
+
+ (narrow-to-region 1 (1+ (buffer-size)))
+
+ BUFFER defaults to the current buffer if omitted.
+
+ - Special Form: save-restriction body...
+ This special form saves the current bounds of the accessible
+ portion, evaluates the BODY forms, and finally restores the saved
+ bounds, thus restoring the same state of narrowing (or absence
+ thereof) formerly in effect. The state of narrowing is restored
+ even in the event of an abnormal exit via `throw' or error (*note
+ Nonlocal Exits::). Therefore, this construct is a clean way to
+ narrow a buffer temporarily.
+
+ The value returned by `save-restriction' is that returned by the
+ last form in BODY, or `nil' if no body forms were given.
+
+ *Caution:* it is easy to make a mistake when using the
+ `save-restriction' construct. Read the entire description here
+ before you try it.
+
+ If BODY changes the current buffer, `save-restriction' still
+ restores the restrictions on the original buffer (the buffer whose
+ restrictions it saved from), but it does not restore the identity
+ of the current buffer.
+
+ `save-restriction' does _not_ restore point and the mark; use
+ `save-excursion' for that. If you use both `save-restriction' and
+ `save-excursion' together, `save-excursion' should come first (on
+ the outside). Otherwise, the old point value would be restored
+ with temporary narrowing still in effect. If the old point value
+ were outside the limits of the temporary narrowing, this would
+ fail to restore it accurately.
+
+ The `save-restriction' special form records the values of the
+ beginning and end of the accessible portion as distances from the
+ beginning and end of the buffer. In other words, it records the
+ amount of inaccessible text before and after the accessible
+ portion.
+
+ This method yields correct results if BODY does further narrowing.
+ However, `save-restriction' can become confused if the body widens
+ and then make changes outside the range of the saved narrowing.
+ When this is what you want to do, `save-restriction' is not the
+ right tool for the job. Here is what you must use instead:
+
+ (let ((start (point-min-marker))
+ (end (point-max-marker)))
+ (unwind-protect
+ (progn BODY)
+ (save-excursion
+ (set-buffer (marker-buffer start))
+ (narrow-to-region start end))))
+
+ Here is a simple example of correct use of `save-restriction':
+
+ ---------- Buffer: foo ----------
+ This is the contents of foo
+ This is the contents of foo
+ This is the contents of foo-!-
+ ---------- Buffer: foo ----------
+
+ (save-excursion
+ (save-restriction
+ (goto-char 1)
+ (forward-line 2)
+ (narrow-to-region 1 (point))
+ (goto-char (point-min))
+ (replace-string "foo" "bar")))
+
+ ---------- Buffer: foo ----------
+ This is the contents of bar
+ This is the contents of bar
+ This is the contents of foo-!-
+ ---------- Buffer: foo ----------
+
+\1f
+File: lispref.info, Node: Markers, Next: Text, Prev: Positions, Up: Top
+
+Markers
+*******
+
+A "marker" is a Lisp object used to specify a position in a buffer
+relative to the surrounding text. A marker changes its offset from the
+beginning of the buffer automatically whenever text is inserted or
+deleted, so that it stays with the two characters on either side of it.
+
+* Menu:
+
+* Overview of Markers:: The components of a marker, and how it relocates.
+* Predicates on Markers:: Testing whether an object is a marker.
+* Creating Markers:: Making empty markers or markers at certain places.
+* Information from Markers:: Finding the marker's buffer or character position.
+* Changing Markers:: Moving the marker to a new buffer or position.
+* The Mark:: How ``the mark'' is implemented with a marker.
+* The Region:: How to access ``the region''.
+
+\1f
+File: lispref.info, Node: Overview of Markers, Next: Predicates on Markers, Up: Markers
+
+Overview of Markers
+===================
+
+A marker specifies a buffer and a position in that buffer. The marker
+can be used to represent a position in the functions that require one,
+just as an integer could be used. *Note Positions::, for a complete
+description of positions.
+
+ A marker has two attributes: the marker position, and the marker
+buffer. The marker position is an integer that is equivalent (at a
+given time) to the marker as a position in that buffer. But the
+marker's position value can change often during the life of the marker.
+Insertion and deletion of text in the buffer relocate the marker. The
+idea is that a marker positioned between two characters remains between
+those two characters despite insertion and deletion elsewhere in the
+buffer. Relocation changes the integer equivalent of the marker.
+
+ Deleting text around a marker's position leaves the marker between
+the characters immediately before and after the deleted text. Inserting
+text at the position of a marker normally leaves the marker in front of
+the new text--unless it is inserted with `insert-before-markers' (*note
+Insertion::).
+
+ Insertion and deletion in a buffer must check all the markers and
+relocate them if necessary. This slows processing in a buffer with a
+large number of markers. For this reason, it is a good idea to make a
+marker point nowhere if you are sure you don't need it any more.
+Unreferenced markers are garbage collected eventually, but until then
+will continue to use time if they do point somewhere.
+
+ Because it is common to perform arithmetic operations on a marker
+position, most of the arithmetic operations (including `+' and `-')
+accept markers as arguments. In such cases, the marker stands for its
+current position.
+
+ Note that you can use extents to achieve the same functionality, and
+more, as markers. (Markers were defined before extents, which is why
+they both continue to exist.) A zero-length extent with the
+`detachable' property removed is almost identical to a marker. (*Note
+Extent Endpoints::, for more information on zero-length extents.)
+
+ In particular:
+
+ * In order to get marker-like behavior in a zero-length extent, the
+ `detachable' property must be removed (otherwise, the extent will
+ disappear when text near it is deleted) and exactly one endpoint
+ must be closed (if both endpoints are closed, the extent will
+ expand to contain text inserted where it is located).
+
+ * If a zero-length extent has the `end-open' property but not the
+ `start-open' property (this is the default), text inserted at the
+ extent's location causes the extent to move forward, just like a
+ marker.
+
+ * If a zero-length extent has the `start-open' property but not the
+ `end-open' property, text inserted at the extent's location causes
+ the extent to remain before the text, like what happens to markers
+ when `insert-before-markers' is used.
+
+ * Markers end up after or before inserted text depending on whether
+ `insert' or `insert-before-markers' was called. These functions
+ do not affect zero-length extents differently; instead, the
+ presence or absence of the `start-open' and `end-open' extent
+ properties determines this, as just described.
+
+ * Markers are automatically removed from a buffer when they are no
+ longer in use. Extents remain around until explicitly removed
+ from a buffer.
+
+ * Many functions are provided for listing the extents in a buffer or
+ in a region of a buffer. No such functions exist for markers.
+
+ Here are examples of creating markers, setting markers, and moving
+point to markers:
+
+ ;; Make a new marker that initially does not point anywhere:
+ (setq m1 (make-marker))
+ => #<marker in no buffer>
+
+ ;; Set `m1' to point between the 99th and 100th characters
+ ;; in the current buffer:
+ (set-marker m1 100)
+ => #<marker at 100 in markers.texi>
+
+ ;; Now insert one character at the beginning of the buffer:
+ (goto-char (point-min))
+ => 1
+ (insert "Q")
+ => nil
+
+ ;; `m1' is updated appropriately.
+ m1
+ => #<marker at 101 in markers.texi>
+
+ ;; Two markers that point to the same position
+ ;; are not `eq', but they are `equal'.
+ (setq m2 (copy-marker m1))
+ => #<marker at 101 in markers.texi>
+ (eq m1 m2)
+ => nil
+ (equal m1 m2)
+ => t
+
+ ;; When you are finished using a marker, make it point nowhere.
+ (set-marker m1 nil)
+ => #<marker in no buffer>
+
+\1f
+File: lispref.info, Node: Predicates on Markers, Next: Creating Markers, Prev: Overview of Markers, Up: Markers
+
+Predicates on Markers
+=====================
+
+You can test an object to see whether it is a marker, or whether it is
+either an integer or a marker or either an integer, a character, or a
+marker. The latter tests are useful in connection with the arithmetic
+functions that work with any of markers, integers, or characters.
+
+ - Function: markerp object
+ This function returns `t' if OBJECT is a marker, `nil' otherwise.
+ Note that integers are not markers, even though many functions
+ will accept either a marker or an integer.
+
+ - Function: integer-or-marker-p object
+ This function returns `t' if OBJECT is an integer or a marker,
+ `nil' otherwise.
+
+ - Function: integer-char-or-marker-p object
+ This function returns `t' if OBJECT is an integer, a character, or
+ a marker, `nil' otherwise.
+
+ - Function: number-or-marker-p object
+ This function returns `t' if OBJECT is a number (either kind) or a
+ marker, `nil' otherwise.
+
+ - Function: number-char-or-marker-p object
+ This function returns `t' if OBJECT is a number (either kind), a
+ character, or a marker, `nil' otherwise.
+
+\1f
+File: lispref.info, Node: Creating Markers, Next: Information from Markers, Prev: Predicates on Markers, Up: Markers
+
+Functions That Create Markers
+=============================
+
+When you create a new marker, you can make it point nowhere, or point
+to the present position of point, or to the beginning or end of the
+accessible portion of the buffer, or to the same place as another given
+marker.
+
+ - Function: make-marker
+ This functions returns a newly created marker that does not point
+ anywhere.
+
+ (make-marker)
+ => #<marker in no buffer>
+
+ - Function: point-marker &optional dont-copy-p buffer
+ This function returns a marker that points to the present position
+ of point in BUFFER, which defaults to the current buffer. *Note
+ Point::. For an example, see `copy-marker', below.
+
+ Internally, a marker corresponding to point is always maintained.
+ Normally the marker returned by `point-marker' is a copy; you may
+ modify it with reckless abandon. However, if optional argument
+ DONT-COPY-P is non-`nil', then the real point-marker is returned;
+ modifying the position of this marker will move point. It is
+ illegal to change the buffer of it, or make it point nowhere.
+
+ - Function: point-min-marker &optional buffer
+ This function returns a new marker that points to the beginning of
+ the accessible portion of BUFFER, which defaults to the current
+ buffer. This will be the beginning of the buffer unless narrowing
+ is in effect. *Note Narrowing::.
+
+ - Function: point-max-marker &optional buffer
+ This function returns a new marker that points to the end of the
+ accessible portion of BUFFER, which defaults to the current
+ buffer. This will be the end of the buffer unless narrowing is in
+ effect. *Note Narrowing::.
+
+ Here are examples of this function and `point-min-marker', shown in
+ a buffer containing a version of the source file for the text of
+ this chapter.
+
+ (point-min-marker)
+ => #<marker at 1 in markers.texi>
+ (point-max-marker)
+ => #<marker at 15573 in markers.texi>
+
+ (narrow-to-region 100 200)
+ => nil
+ (point-min-marker)
+ => #<marker at 100 in markers.texi>
+ (point-max-marker)
+ => #<marker at 200 in markers.texi>
+
+ - Function: copy-marker marker-or-integer &optional marker-type
+ If passed a marker as its argument, `copy-marker' returns a new
+ marker that points to the same place and the same buffer as does
+ MARKER-OR-INTEGER. If passed an integer as its argument,
+ `copy-marker' returns a new marker that points to position
+ MARKER-OR-INTEGER in the current buffer.
+
+ If passed an integer argument less than 1, `copy-marker' returns a
+ new marker that points to the beginning of the current buffer. If
+ passed an integer argument greater than the length of the buffer,
+ `copy-marker' returns a new marker that points to the end of the
+ buffer.
+
+ An error is signaled if MARKER-OR-INTEGER is neither a marker nor
+ an integer.
+
+ Optional second argument MARKER-TYPE specifies the insertion type
+ of the new marker; see `marker-insertion-type'.
+
+ (setq p (point-marker))
+ => #<marker at 2139 in markers.texi>
+
+ (setq q (copy-marker p))
+ => #<marker at 2139 in markers.texi>
+
+ (eq p q)
+ => nil
+
+ (equal p q)
=> t
+
+ (point)
+ => 2139
+
+ (set-marker p 3000)
+ => #<marker at 3000 in markers.texi>
+
+ (point)
+ => 2139
+
+ (setq p (point-marker t))
+ => #<marker at 2139 in markers.texi>
+
+ (set-marker p 3000)
+ => #<marker at 3000 in markers.texi>
+
+ (point)
+ => 3000
+
+ (copy-marker 0)
+ => #<marker at 1 in markers.texi>
+
+ (copy-marker 20000)
+ => #<marker at 7572 in markers.texi>
+
+\1f
+File: lispref.info, Node: Information from Markers, Next: Changing Markers, Prev: Creating Markers, Up: Markers
+
+Information from Markers
+========================
+
+This section describes the functions for accessing the components of a
+marker object.
+
+ - Function: marker-position marker
+ This function returns the position that MARKER points to, or `nil'
+ if it points nowhere.
+
+ - Function: marker-buffer marker
+ This function returns the buffer that MARKER points into, or `nil'
+ if it points nowhere.
+
+ (setq m (make-marker))
+ => #<marker in no buffer>
+ (marker-position m)
+ => nil
+ (marker-buffer m)
+ => nil
+
+ (set-marker m 3770 (current-buffer))
+ => #<marker at 3770 in markers.texi>
+ (marker-buffer m)
+ => #<buffer markers.texi>
+ (marker-position m)
+ => 3770
+
+ Two distinct markers are considered `equal' (even though not `eq')
+to each other if they have the same position and buffer, or if they
+both point nowhere.
+
+\1f
+File: lispref.info, Node: Changing Markers, Next: The Mark, Prev: Information from Markers, Up: Markers
+
+Changing Marker Positions
+=========================
+
+This section describes how to change the position of an existing
+marker. When you do this, be sure you know whether the marker is used
+outside of your program, and, if so, what effects will result from
+moving it--otherwise, confusing things may happen in other parts of
+Emacs.
+
+ - Function: set-marker marker position &optional buffer
+ This function moves MARKER to POSITION in BUFFER. If BUFFER is
+ not provided, it defaults to the current buffer.
+
+ POSITION can be a marker, an integer or `nil'. If POSITION is an
+ integer, `set-marker' moves MARKER to point before the POSITIONth
+ character in BUFFER. If POSITION is `nil', MARKER is made to
+ point nowhere. Then it no longer slows down editing in any
+ buffer. If POSITION is less than 1, MARKER is moved to the
+ beginning of BUFFER. If POSITION is greater than the size of
+ BUFFER, MARKER is moved to the end of BUFFER.
+
+ The value returned is MARKER.
+
+ (setq m (point-marker))
+ => #<marker at 4714 in markers.texi>
+ (set-marker m 55)
+ => #<marker at 55 in markers.texi>
+ (setq b (get-buffer "foo"))
+ => #<buffer foo>
+ (set-marker m 0 b)
+ => #<marker at 1 in foo>
+
+ - Function: move-marker marker position &optional buffer
+ This is another name for `set-marker'.
+
+\1f
+File: lispref.info, Node: The Mark, Next: The Region, Prev: Changing Markers, Up: Markers
+
+The Mark
+========
+
+One special marker in each buffer is designated "the mark". It records
+a position for the user for the sake of commands such as `C-w' and `C-x
+<TAB>'. Lisp programs should set the mark only to values that have a
+potential use to the user, and never for their own internal purposes.
+For example, the `replace-regexp' command sets the mark to the value of
+point before doing any replacements, because this enables the user to
+move back there conveniently after the replace is finished.
+
+ Once the mark "exists" in a buffer, it normally never ceases to
+exist. However, it may become "inactive", and usually does so after
+each command (other than simple motion commands and some commands that
+explicitly activate the mark). When the mark is active, the region
+between point and the mark is called the "active region" and is
+highlighted specially.
+
+ Many commands are designed so that when called interactively they
+operate on the text between point and the mark. Such commands work
+only when an active region exists, i.e. when the mark is active. (The
+reason for this is to prevent you from accidentally deleting or
+changing large chunks of your text.) If you are writing such a command,
+don't examine the mark directly; instead, use `interactive' with the
+`r' specification. This provides the values of point and the mark as
+arguments to the command in an interactive call, but permits other Lisp
+programs to specify arguments explicitly, and automatically signals an
+error if the command is called interactively when no active region
+exists. *Note Interactive Codes::.
+
+ Each buffer has its own value of the mark that is independent of the
+value of the mark in other buffers. (When a buffer is created, the mark
+exists but does not point anywhere. We consider this state as "the
+absence of a mark in that buffer.") However, only one active region can
+exist at a time. Activating the mark in one buffer automatically
+deactivates an active mark in any other buffer. Note that the user can
+explicitly activate a mark at any time by using the command
+`activate-region' (normally bound to `M-C-z') or by using the command
+`exchange-point-and-mark' (normally bound to `C-x C-x'), which has the
+side effect of activating the mark.
+
+ Some people do not like active regions, so they disable this behavior
+by setting the variable `zmacs-regions' to `nil'. This makes the mark
+always active (except when a buffer is just created and the mark points
+nowhere), and turns off the highlighting of the region between point
+and the mark. Commands that explicitly retrieve the value of the mark
+should make sure that they behave correctly and consistently
+irrespective of the setting of `zmacs-regions'; some primitives are
+provided to ensure this behavior.
+
+ In addition to the mark, each buffer has a "mark ring" which is a
+list of markers containing previous values of the mark. When editing
+commands change the mark, they should normally save the old value of the
+mark on the mark ring. The variable `mark-ring-max' specifies the
+maximum number of entries in the mark ring; once the list becomes this
+long, adding a new element deletes the last element.
+
+ - Function: mark &optional force buffer
+ This function returns BUFFER's mark position as an integer.
+ BUFFER defaults to the current buffer if omitted.
+
+ If the mark is inactive, `mark' normally returns `nil'. However,
+ if FORCE is non-`nil', then `mark' returns the mark position
+ anyway--or `nil', if the mark is not yet set for the buffer.
+
+ (Remember that if `zmacs-regions' is `nil', the mark is always
+ active as long as it exists, and the FORCE argument will have no
+ effect.)
+
+ If you are using this in an editing command, you are most likely
+ making a mistake; see the documentation of `set-mark' below.
+
+ - Function: mark-marker &optional force buffer
+ This function returns BUFFER's mark. BUFFER defaults to the
+ current buffer if omitted. This is the very marker that records
+ the mark location inside XEmacs, not a copy. Therefore, changing
+ this marker's position will directly affect the position of the
+ mark. Don't do it unless that is the effect you want.
+
+ If the mark is inactive, `mark-marker' normally returns `nil'.
+ However, if FORCE is non-`nil', then `mark-marker' returns the
+ mark anyway.
+ (setq m (mark-marker))
+ => #<marker at 3420 in markers.texi>
+ (set-marker m 100)
+ => #<marker at 100 in markers.texi>
+ (mark-marker)
+ => #<marker at 100 in markers.texi>
+
+ Like any marker, this marker can be set to point at any buffer you
+ like. We don't recommend that you make it point at any buffer
+ other than the one of which it is the mark. If you do, it will
+ yield perfectly consistent, but rather odd, results.
+
+ - Function: set-mark position &optional buffer
+ This function sets `buffer''s mark to POSITION, and activates the
+ mark. BUFFER defaults to the current buffer if omitted. The old
+ value of the mark is _not_ pushed onto the mark ring.
+
+ *Please note:* Use this function only if you want the user to see
+ that the mark has moved, and you want the previous mark position to
+ be lost. Normally, when a new mark is set, the old one should go
+ on the `mark-ring'. For this reason, most applications should use
+ `push-mark' and `pop-mark', not `set-mark'.
+
+ Novice XEmacs Lisp programmers often try to use the mark for the
+ wrong purposes. The mark saves a location for the user's
+ convenience. An editing command should not alter the mark unless
+ altering the mark is part of the user-level functionality of the
+ command. (And, in that case, this effect should be documented.)
+ To remember a location for internal use in the Lisp program, store
+ it in a Lisp variable. For example:
+
+ (let ((start (point)))
+ (forward-line 1)
+ (delete-region start (point))).
+
+ - Command: exchange-point-and-mark &optional dont-activate-region
+ This function exchanges the positions of point and the mark. It
+ is intended for interactive use. The mark is also activated
+ unless DONT-ACTIVATE-REGION is non-`nil'.
+
+ - Function: push-mark &optional position nomsg activate buffer
+ This function sets BUFFER's mark to POSITION, and pushes a copy of
+ the previous mark onto `mark-ring'. BUFFER defaults to the
+ current buffer if omitted. If POSITION is `nil', then the value
+ of point is used. `push-mark' returns `nil'.
+
+ If the last global mark pushed was not in BUFFER, also push
+ POSITION on the global mark ring (see below).
+
+ The function `push-mark' normally _does not_ activate the mark.
+ To do that, specify `t' for the argument ACTIVATE.
+
+ A `Mark set' message is displayed unless NOMSG is non-`nil'.
+
+ - Function: pop-mark
+ This function pops off the top element of `mark-ring' and makes
+ that mark become the buffer's actual mark. This does not move
+ point in the buffer, and it does nothing if `mark-ring' is empty.
+ It deactivates the mark.
+
+ The return value is not meaningful.
+
+ - Variable: mark-ring
+ The value of this buffer-local variable is the list of saved former
+ marks of the current buffer, most recent first.
+
+ mark-ring
+ => (#<marker at 11050 in markers.texi>
+ #<marker at 10832 in markers.texi>
+ ...)
+
+ - User Option: mark-ring-max
+ The value of this variable is the maximum size of `mark-ring'. If
+ more marks than this are pushed onto the `mark-ring', `push-mark'
+ discards an old mark when it adds a new one.
+
+ In additional to a per-buffer mark ring, there is a "global mark
+ring". Marks are pushed onto the global mark ring the first time you
+set a mark after switching buffers.
+
+ - Variable: global-mark-ring
+ The value of this variable is the list of saved former global
+ marks, most recent first.
+
+ - User Option: mark-ring-max
+ The value of this variable is the maximum size of
+ `global-mark-ring'. If more marks than this are pushed onto the
+ `global-mark-ring', `push-mark' discards an old mark when it adds
+ a new one.
+
+ - Command: pop-global-mark
+ This function pops a mark off the global mark ring and jumps to
+ that location.
+
+\1f
+File: lispref.info, Node: The Region, Prev: The Mark, Up: Markers
+
+The Region
+==========
+
+The text between point and the mark is known as "the region". Various
+functions operate on text delimited by point and the mark, but only
+those functions specifically related to the region itself are described
+here.
+
+ When `zmacs-regions' is non-`nil' (this is the default), the concept
+of an "active region" exists. The region is active when the
+corresponding mark is active. Note that only one active region at a
+time can exist--i.e. only one buffer's region is active at a time.
+*Note The Mark::, for more information about active regions.
+
+ - User Option: zmacs-regions
+ If non-`nil' (the default), active regions are used. *Note The
+ Mark::, for a detailed explanation of what this means.
+
+ A number of functions are provided for explicitly determining the
+bounds of the region and whether it is active. Few programs need to use
+these functions, however. A command designed to operate on a region
+should normally use `interactive' with the `r' specification to find
+the beginning and end of the region. This lets other Lisp programs
+specify the bounds explicitly as arguments and automatically respects
+the user's setting for `zmacs-regions'. (*Note Interactive Codes::.)
+
+ - Function: region-beginning &optional buffer
+ This function returns the position of the beginning of BUFFER's
+ region (as an integer). This is the position of either point or
+ the mark, whichever is smaller. BUFFER defaults to the current
+ buffer if omitted.
+
+ If the mark does not point anywhere, an error is signaled. Note
+ that this function ignores whether the region is active.
+
+ - Function: region-end &optional buffer
+ This function returns the position of the end of BUFFER's region
+ (as an integer). This is the position of either point or the mark,
+ whichever is larger. BUFFER defaults to the current buffer if
+ omitted.
+
+ If the mark does not point anywhere, an error is signaled. Note
+ that this function ignores whether the region is active.
+
+ - Function: region-exists-p
+ This function is non-`nil' if the region exists. If active regions
+ are in use (i.e. `zmacs-regions' is true), this means that the
+ region is active. Otherwise, this means that the user has pushed
+ a mark in this buffer at some point in the past. If this function
+ returns `nil', a function that uses the `r' interactive
+ specification will cause an error when called interactively.
+
+ - Function: region-active-p
+ If `zmacs-regions' is true, this is equivalent to
+ `region-exists-p'. Otherwise, this function always returns false.
+ This function is used by commands such as
+ `fill-paragraph-or-region' and `capitalize-region-or-word', which
+ operate either on the active region or on something else (e.g. the
+ word or paragraph at point).
+
+ - Variable: zmacs-region-stays
+ If a command sets this variable to true, the currently active
+ region will remain activated when the command finishes. (Normally
+ the region is deactivated when each command terminates.) If
+ `zmacs-regions' is false, however, this has no effect. Under
+ normal circumstances, you do not need to set this; use the
+ interactive specification `_' instead, if you want the region to
+ remain active.
+
+ - Function: zmacs-activate-region
+ This function activates the region in the current buffer (this is
+ equivalent to activating the current buffer's mark). This will
+ normally also highlight the text in the active region and set
+ `zmacs-region-stays' to `t'. (If `zmacs-regions' is false,
+ however, this function has no effect.)
+
+ - Function: zmacs-deactivate-region
+ This function deactivates the region in the current buffer (this is
+ equivalent to deactivating the current buffer's mark). This will
+ normally also unhighlight the text in the active region and set
+ `zmacs-region-stays' to `nil'. (If `zmacs-regions' is false,
+ however, this function has no effect.)
+
+ - Function: zmacs-update-region
+ This function updates the active region, if it's currently active.
+ (If there is no active region, this function does nothing.) This
+ has the effect of updating the highlighting on the text in the
+ region; but you should never need to call this except under rather
+ strange circumstances. The command loop automatically calls it
+ when appropriate. Calling this function will call the hook
+ `zmacs-update-region-hook', if the region is active.
+
+ - Variable: zmacs-activate-region-hook
+ This normal hook is called when a region becomes active. (Usually
+ this happens as a result of a command that activates the region,
+ such as `set-mark-command', `activate-region', or
+ `exchange-point-and-mark'.) Note that calling
+ `zmacs-activate-region' will call this hook, even if the region is
+ already active. If `zmacs-regions' is false, however, this hook
+ will never get called under any circumstances.
+
+ - Variable: zmacs-deactivate-region-hook
+ This normal hook is called when an active region becomes inactive.
+ (Calling `zmacs-deactivate-region' when the region is inactive will
+ _not_ cause this hook to be called.) If `zmacs-regions' is false,
+ this hook will never get called.
+
+ - Variable: zmacs-update-region-hook
+ This normal hook is called when an active region is "updated" by
+ `zmacs-update-region'. This normally gets called at the end of
+ each command that sets `zmacs-region-stays' to `t', indicating
+ that the region should remain activated. The motion commands do
+ this.
+
+\1f
+File: lispref.info, Node: Text, Next: Searching and Matching, Prev: Markers, Up: Top
+
+Text
+****
+
+This chapter describes the functions that deal with the text in a
+buffer. Most examine, insert, or delete text in the current buffer,
+often in the vicinity of point. Many are interactive. All the
+functions that change the text provide for undoing the changes (*note
+Undo::).
+
+ Many text-related functions operate on a region of text defined by
+two buffer positions passed in arguments named START and END. These
+arguments should be either markers (*note Markers::) or numeric
+character positions (*note Positions::). The order of these arguments
+does not matter; it is all right for START to be the end of the region
+and END the beginning. For example, `(delete-region 1 10)' and
+`(delete-region 10 1)' are equivalent. An `args-out-of-range' error is
+signaled if either START or END is outside the accessible portion of
+the buffer. In an interactive call, point and the mark are used for
+these arguments.
+
+ Throughout this chapter, "text" refers to the characters in the
+buffer, together with their properties (when relevant).
+
+* Menu:
+
+* Near Point:: Examining text in the vicinity of point.
+* Buffer Contents:: Examining text in a general fashion.
+* Comparing Text:: Comparing substrings of buffers.
+* Insertion:: Adding new text to a buffer.
+* Commands for Insertion:: User-level commands to insert text.
+* Deletion:: Removing text from a buffer.
+* User-Level Deletion:: User-level commands to delete text.
+* The Kill Ring:: Where removed text sometimes is saved for later use.
+* Undo:: Undoing changes to the text of a buffer.
+* Maintaining Undo:: How to enable and disable undo information.
+ How to control how much information is kept.
+* Filling:: Functions for explicit filling.
+* Margins:: How to specify margins for filling commands.
+* Auto Filling:: How auto-fill mode is implemented to break lines.
+* Sorting:: Functions for sorting parts of the buffer.
+* Columns:: Computing horizontal positions, and using them.
+* Indentation:: Functions to insert or adjust indentation.
+* Case Changes:: Case conversion of parts of the buffer.
+* Text Properties:: Assigning Lisp property lists to text characters.
+* Substitution:: Replacing a given character wherever it appears.
+* Registers:: How registers are implemented. Accessing the text or
+ position stored in a register.
+* Transposition:: Swapping two portions of a buffer.
+* Change Hooks:: Supplying functions to be run when text is changed.
+* Transformations:: MD5 and base64 support.
+
+\1f
+File: lispref.info, Node: Near Point, Next: Buffer Contents, Up: Text
+
+Examining Text Near Point
+=========================
+
+Many functions are provided to look at the characters around point.
+Several simple functions are described here. See also `looking-at' in
+*Note Regexp Search::.
+
+ Many of these functions take an optional BUFFER argument. In all
+such cases, the current buffer will be used if this argument is
+omitted. (In FSF Emacs, and earlier versions of XEmacs, these functions
+usually did not have these optional BUFFER arguments and always
+operated on the current buffer.)
+
+ - Function: char-after &optional position buffer
+ This function returns the character in the buffer at (i.e.,
+ immediately after) position POSITION. If POSITION is out of range
+ for this purpose, either before the beginning of the buffer, or at
+ or beyond the end, then the value is `nil'. The default for
+ POSITION is point. If optional argument BUFFER is `nil', the
+ current buffer is assumed.
+
+ In the following example, assume that the first character in the
+ buffer is `@':
+
+ (char-to-string (char-after 1))
+ => "@"
+
+ - Function: char-before &optional position buffer
+ This function returns the character in the current buffer
+ immediately before position POSITION. If POSITION is out of range
+ for this purpose, either at or before the beginning of the buffer,
+ or beyond the end, then the value is `nil'. The default for
+ POSITION is point. If optional argument BUFFER is `nil', the
+ current buffer is assumed.
+
+ - Function: following-char &optional buffer
+ This function returns the character following point in the buffer.
+ This is similar to `(char-after (point))'. However, if point is at
+ the end of the buffer, then the result of `following-char' is 0.
+ If optional argument BUFFER is `nil', the current buffer is
+ assumed.
+
+ Remember that point is always between characters, and the terminal
+ cursor normally appears over the character following point.
+ Therefore, the character returned by `following-char' is the
+ character the cursor is over.
+
+ In this example, point is between the `a' and the `c'.
+
+ ---------- Buffer: foo ----------
+ Gentlemen may cry ``Pea-!-ce! Peace!,''
+ but there is no peace.
+ ---------- Buffer: foo ----------
+
+ (char-to-string (preceding-char))
+ => "a"
+ (char-to-string (following-char))
+ => "c"
+
+ - Function: preceding-char &optional buffer
+ This function returns the character preceding point in the buffer.
+ See above, under `following-char', for an example. If point is at
+ the beginning of the buffer, `preceding-char' returns 0. If
+ optional argument BUFFER is `nil', the current buffer is assumed.
+
+ - Function: bobp &optional buffer
+ This function returns `t' if point is at the beginning of the
+ buffer. If narrowing is in effect, this means the beginning of the
+ accessible portion of the text. If optional argument BUFFER is
+ `nil', the current buffer is assumed. See also `point-min' in
+ *Note Point::.
+
+ - Function: eobp &optional buffer
+ This function returns `t' if point is at the end of the buffer.
+ If narrowing is in effect, this means the end of accessible
+ portion of the text. If optional argument BUFFER is `nil', the
+ current buffer is assumed. See also `point-max' in *Note Point::.
+
+ - Function: bolp &optional buffer
+ This function returns `t' if point is at the beginning of a line.
+ If optional argument BUFFER is `nil', the current buffer is
+ assumed. *Note Text Lines::. The beginning of the buffer (or its
+ accessible portion) always counts as the beginning of a line.
+
+ - Function: eolp &optional buffer
+ This function returns `t' if point is at the end of a line. The
+ end of the buffer is always considered the end of a line. If
+ optional argument BUFFER is `nil', the current buffer is assumed.
+ The end of the buffer (or of its accessible portion) is always
+ considered the end of a line.
+
+\1f
+File: lispref.info, Node: Buffer Contents, Next: Comparing Text, Prev: Near Point, Up: Text
+
+Examining Buffer Contents
+=========================
+
+This section describes two functions that allow a Lisp program to
+convert any portion of the text in the buffer into a string.
+
+ - Function: buffer-substring start end &optional buffer
+ - Function: buffer-string start end &optional buffer
+ These functions are equivalent and return a string containing a
+ copy of the text of the region defined by positions START and END
+ in the buffer. If the arguments are not positions in the
+ accessible portion of the buffer, `buffer-substring' signals an
+ `args-out-of-range' error. If optional argument BUFFER is `nil',
+ the current buffer is assumed.
+
+ If the region delineated by START and END contains duplicable
+ extents, they will be remembered in the string. *Note Duplicable
+ Extents::.
+
+ It is not necessary for START to be less than END; the arguments
+ can be given in either order. But most often the smaller argument
+ is written first.
+
+ ---------- Buffer: foo ----------
+ This is the contents of buffer foo
+
+ ---------- Buffer: foo ----------
+
+ (buffer-substring 1 10)
+ => "This is t"
+ (buffer-substring (point-max) 10)
+ => "he contents of buffer foo
+ "
+
+\1f
+File: lispref.info, Node: Comparing Text, Next: Insertion, Prev: Buffer Contents, Up: Text
+
+Comparing Text
+==============
+
+This function lets you compare portions of the text in a buffer, without
+copying them into strings first.
+
+ - Function: compare-buffer-substrings buffer1 start1 end1 buffer2
+ start2 end2
+ This function lets you compare two substrings of the same buffer
+ or two different buffers. The first three arguments specify one
+ substring, giving a buffer and two positions within the buffer.
+ The last three arguments specify the other substring in the same
+ way. You can use `nil' for BUFFER1, BUFFER2, or both to stand for
+ the current buffer.
+
+ The value is negative if the first substring is less, positive if
+ the first is greater, and zero if they are equal. The absolute
+ value of the result is one plus the index of the first differing
+ characters within the substrings.
+
+ This function ignores case when comparing characters if
+ `case-fold-search' is non-`nil'. It always ignores text
+ properties.
+
+ Suppose the current buffer contains the text `foobarbar
+ haha!rara!'; then in this example the two substrings are `rbar '
+ and `rara!'. The value is 2 because the first substring is greater
+ at the second character.
+
+ (compare-buffer-substring nil 6 11 nil 16 21)
+ => 2
+
+\1f
+File: lispref.info, Node: Insertion, Next: Commands for Insertion, Prev: Comparing Text, Up: Text
+
+Inserting Text
+==============
+
+"Insertion" means adding new text to a buffer. The inserted text goes
+at point--between the character before point and the character after
+point.
+
+ Insertion relocates markers that point at positions after the
+insertion point, so that they stay with the surrounding text (*note
+Markers::). When a marker points at the place of insertion, insertion
+normally doesn't relocate the marker, so that it points to the
+beginning of the inserted text; however, certain special functions such
+as `insert-before-markers' relocate such markers to point after the
+inserted text.
+
+ Some insertion functions leave point before the inserted text, while
+other functions leave it after. We call the former insertion "after
+point" and the latter insertion "before point".
+
+ If a string with non-`nil' extent data is inserted, the remembered
+extents will also be inserted. *Note Duplicable Extents::.
+
+ Insertion functions signal an error if the current buffer is
+read-only.
+
+ These functions copy text characters from strings and buffers along
+with their properties. The inserted characters have exactly the same
+properties as the characters they were copied from. By contrast,
+characters specified as separate arguments, not part of a string or
+buffer, inherit their text properties from the neighboring text.
+
+ - Function: insert &rest args
+ This function inserts the strings and/or characters ARGS into the
+ current buffer, at point, moving point forward. In other words, it
+ inserts the text before point. An error is signaled unless all
+ ARGS are either strings or characters. The value is `nil'.
+
+ - Function: insert-before-markers &rest args
+ This function inserts the strings and/or characters ARGS into the
+ current buffer, at point, moving point forward. An error is
+ signaled unless all ARGS are either strings or characters. The
+ value is `nil'.
+
+ This function is unlike the other insertion functions in that it
+ relocates markers initially pointing at the insertion point, to
+ point after the inserted text.
+
+ - Function: insert-string string &optional buffer
+ This function inserts STRING into BUFFER before point. BUFFER
+ defaults to the current buffer if omitted. This function is
+ chiefly useful if you want to insert a string in a buffer other
+ than the current one (otherwise you could just use `insert').
+
+ - Function: insert-char character &optional count ignored buffer
+ This function inserts COUNT instances of CHARACTER into BUFFER
+ before point. COUNT must be a number, and CHARACTER must be a
+ character.
+
+ If optional argument BUFFER is `nil', the current buffer is
+ assumed. (In FSF Emacs, the third argument is called INHERIT and
+ refers to text properties. In XEmacs, it is always ignored.)
+
+ This function always returns `nil'.
+
+ - Function: insert-buffer-substring from-buffer-or-name &optional
+ start end
+ This function inserts a portion of buffer FROM-BUFFER-OR-NAME
+ (which must already exist) into the current buffer before point.
+ The text inserted is the region from START and END. (These
+ arguments default to the beginning and end of the accessible
+ portion of that buffer.) This function returns `nil'.
+
+ In this example, the form is executed with buffer `bar' as the
+ current buffer. We assume that buffer `bar' is initially empty.
+
+ ---------- Buffer: foo ----------
+ We hold these truths to be self-evident, that all
+ ---------- Buffer: foo ----------
+
+ (insert-buffer-substring "foo" 1 20)
+ => nil
+
+ ---------- Buffer: bar ----------
+ We hold these truth-!-
+ ---------- Buffer: bar ----------
+
+\1f
+File: lispref.info, Node: Commands for Insertion, Next: Deletion, Prev: Insertion, Up: Text
+
+User-Level Insertion Commands
+=============================
+
+This section describes higher-level commands for inserting text,
+commands intended primarily for the user but useful also in Lisp
+programs.
+
+ - Command: insert-buffer from-buffer-or-name
+ This command inserts the entire contents of FROM-BUFFER-OR-NAME
+ (which must exist) into the current buffer after point. It leaves
+ the mark after the inserted text. The value is `nil'.
+
+ - Command: self-insert-command count
+ This command inserts the last character typed; it does so COUNT
+ times, before point, and returns `nil'. Most printing characters
+ are bound to this command. In routine use, `self-insert-command'
+ is the most frequently called function in XEmacs, but programs
+ rarely use it except to install it on a keymap.
+
+ In an interactive call, COUNT is the numeric prefix argument.
+
+ This command calls `auto-fill-function' whenever that is non-`nil'
+ and the character inserted is a space or a newline (*note Auto
+ Filling::).
+
+ This command performs abbrev expansion if Abbrev mode is enabled
+ and the inserted character does not have word-constituent syntax.
+ (*Note Abbrevs::, and *Note Syntax Class Table::.)
+
+ This is also responsible for calling `blink-paren-function' when
+ the inserted character has close parenthesis syntax (*note
+ Blinking::).
+
+ - Command: newline &optional count
+ This command inserts newlines into the current buffer before point.
+ If COUNT is supplied, that many newline characters are inserted.
+
+ This function calls `auto-fill-function' if the current column
+ number is greater than the value of `fill-column' and COUNT is
+ `nil'. Typically what `auto-fill-function' does is insert a
+ newline; thus, the overall result in this case is to insert two
+ newlines at different places: one at point, and another earlier in
+ the line. `newline' does not auto-fill if COUNT is non-`nil'.
+
+ This command indents to the left margin if that is not zero.
+ *Note Margins::.
+
+ The value returned is `nil'. In an interactive call, COUNT is the
+ numeric prefix argument.
+
+ - Command: split-line
+ This command splits the current line, moving the portion of the
+ line after point down vertically so that it is on the next line
+ directly below where it was before. Whitespace is inserted as
+ needed at the beginning of the lower line, using the `indent-to'
+ function. `split-line' returns the position of point.
+
+ Programs hardly ever use this function.
+
+ - Variable: overwrite-mode
+ This variable controls whether overwrite mode is in effect: a
+ non-`nil' value enables the mode. It is automatically made
+ buffer-local when set in any fashion.
+
+\1f
+File: lispref.info, Node: Deletion, Next: User-Level Deletion, Prev: Commands for Insertion, Up: Text
+
+Deleting Text
+=============
+
+Deletion means removing part of the text in a buffer, without saving it
+in the kill ring (*note The Kill Ring::). Deleted text can't be
+yanked, but can be reinserted using the undo mechanism (*note Undo::).
+Some deletion functions do save text in the kill ring in some special
+cases.
+
+ All of the deletion functions operate on the current buffer, and all
+return a value of `nil'.
+
+ - Command: erase-buffer &optional buffer
+ This function deletes the entire text of BUFFER, leaving it empty.
+ If the buffer is read-only, it signals a `buffer-read-only'
+ error. Otherwise, it deletes the text without asking for any
+ confirmation. It returns `nil'. BUFFER defaults to the current
+ buffer if omitted.
+
+ Normally, deleting a large amount of text from a buffer inhibits
+ further auto-saving of that buffer "because it has shrunk".
+ However, `erase-buffer' does not do this, the idea being that the
+ future text is not really related to the former text, and its size
+ should not be compared with that of the former text.
+
+ - Command: delete-region start end &optional buffer
+ This command deletes the text in BUFFER in the region defined by
+ START and END. The value is `nil'. If optional argument BUFFER
+ is `nil', the current buffer is assumed.
+
+ - Command: delete-char &optional count killp
+ This command deletes COUNT characters directly after point, or
+ before point if COUNT is negative. COUNT defaults to `1'. If
+ KILLP is non-`nil', then it saves the deleted characters in the
+ kill ring.
+
+ In an interactive call, COUNT is the numeric prefix argument, and
+ KILLP is the unprocessed prefix argument. Therefore, if a prefix
+ argument is supplied, the text is saved in the kill ring. If no
+ prefix argument is supplied, then one character is deleted, but
+ not saved in the kill ring.
+
+ The value returned is always `nil'.
+
+ - Command: delete-backward-char &optional count killp
+ This command deletes COUNT characters directly before point, or
+ after point if COUNT is negative. COUNT defaults to 1. If KILLP
+ is non-`nil', then it saves the deleted characters in the kill
+ ring.
+
+ In an interactive call, COUNT is the numeric prefix argument, and
+ KILLP is the unprocessed prefix argument. Therefore, if a prefix
+ argument is supplied, the text is saved in the kill ring. If no
+ prefix argument is supplied, then one character is deleted, but
+ not saved in the kill ring.
+
+ The value returned is always `nil'.
+
+ - Command: backward-delete-char-untabify count &optional killp
+ This command deletes COUNT characters backward, changing tabs into
+ spaces. When the next character to be deleted is a tab, it is
+ first replaced with the proper number of spaces to preserve
+ alignment and then one of those spaces is deleted instead of the
+ tab. If KILLP is non-`nil', then the command saves the deleted
+ characters in the kill ring.
+
+ Conversion of tabs to spaces happens only if COUNT is positive.
+ If it is negative, exactly -COUNT characters after point are
+ deleted.
+
+ In an interactive call, COUNT is the numeric prefix argument, and
+ KILLP is the unprocessed prefix argument. Therefore, if a prefix
+ argument is supplied, the text is saved in the kill ring. If no
+ prefix argument is supplied, then one character is deleted, but
+ not saved in the kill ring.
+
+ The value returned is always `nil'.
+
+\1f
+File: lispref.info, Node: User-Level Deletion, Next: The Kill Ring, Prev: Deletion, Up: Text
+
+User-Level Deletion Commands
+============================
+
+This section describes higher-level commands for deleting text,
+commands intended primarily for the user but useful also in Lisp
+programs.
+
+ - Command: delete-horizontal-space
+ This function deletes all spaces and tabs around point. It returns
+ `nil'.
+
+ In the following examples, we call `delete-horizontal-space' four
+ times, once on each line, with point between the second and third
+ characters on the line each time.
+
+ ---------- Buffer: foo ----------
+ I -!-thought
+ I -!- thought
+ We-!- thought
+ Yo-!-u thought
+ ---------- Buffer: foo ----------
+
+ (delete-horizontal-space) ; Four times.
+ => nil
+
+ ---------- Buffer: foo ----------
+ Ithought
+ Ithought
+ Wethought
+ You thought
+ ---------- Buffer: foo ----------
+
+ - Command: delete-indentation &optional join-following-p
+ This function joins the line point is on to the previous line,
+ deleting any whitespace at the join and in some cases replacing it
+ with one space. If JOIN-FOLLOWING-P is non-`nil',
+ `delete-indentation' joins this line to the following line
+ instead. The value is `nil'.
+
+ If there is a fill prefix, and the second of the lines being joined
+ starts with the prefix, then `delete-indentation' deletes the fill
+ prefix before joining the lines. *Note Margins::.
+
+ In the example below, point is located on the line starting
+ `events', and it makes no difference if there are trailing spaces
+ in the preceding line.
+
+ ---------- Buffer: foo ----------
+ When in the course of human
+ -!- events, it becomes necessary
+ ---------- Buffer: foo ----------
+
+ (delete-indentation)
+ => nil
+
+ ---------- Buffer: foo ----------
+ When in the course of human-!- events, it becomes necessary
+ ---------- Buffer: foo ----------
+
+ After the lines are joined, the function `fixup-whitespace' is
+ responsible for deciding whether to leave a space at the junction.
+
+ - Command: fixup-whitespace
+ This function replaces all the white space surrounding point with
+ either one space or no space, according to the context. It
+ returns `nil'.
+
+ At the beginning or end of a line, the appropriate amount of space
+ is none. Before a character with close parenthesis syntax, or
+ after a character with open parenthesis or expression-prefix
+ syntax, no space is also appropriate. Otherwise, one space is
+ appropriate. *Note Syntax Class Table::.
+
+ In the example below, `fixup-whitespace' is called the first time
+ with point before the word `spaces' in the first line. For the
+ second invocation, point is directly after the `('.
+
+ ---------- Buffer: foo ----------
+ This has too many -!-spaces
+ This has too many spaces at the start of (-!- this list)
+ ---------- Buffer: foo ----------
+
+ (fixup-whitespace)
+ => nil
+ (fixup-whitespace)
+ => nil
+
+ ---------- Buffer: foo ----------
+ This has too many spaces
+ This has too many spaces at the start of (this list)
+ ---------- Buffer: foo ----------
+
+ - Command: just-one-space
+ This command replaces any spaces and tabs around point with a
+ single space. It returns `nil'.
+
+ - Command: delete-blank-lines
+ This function deletes blank lines surrounding point. If point is
+ on a blank line with one or more blank lines before or after it,
+ then all but one of them are deleted. If point is on an isolated
+ blank line, then it is deleted. If point is on a nonblank line,
+ the command deletes all blank lines following it.
+
+ A blank line is defined as a line containing only tabs and spaces.
+
+ `delete-blank-lines' returns `nil'.
+
+\1f
+File: lispref.info, Node: The Kill Ring, Next: Undo, Prev: User-Level Deletion, Up: Text
+
+The Kill Ring
+=============
+
+"Kill" functions delete text like the deletion functions, but save it
+so that the user can reinsert it by "yanking". Most of these functions
+have `kill-' in their name. By contrast, the functions whose names
+start with `delete-' normally do not save text for yanking (though they
+can still be undone); these are "deletion" functions.
+
+ Most of the kill commands are primarily for interactive use, and are
+not described here. What we do describe are the functions provided for
+use in writing such commands. You can use these functions to write
+commands for killing text. When you need to delete text for internal
+purposes within a Lisp function, you should normally use deletion
+functions, so as not to disturb the kill ring contents. *Note
+Deletion::.
+
+ Killed text is saved for later yanking in the "kill ring". This is
+a list that holds a number of recent kills, not just the last text
+kill. We call this a "ring" because yanking treats it as having
+elements in a cyclic order. The list is kept in the variable
+`kill-ring', and can be operated on with the usual functions for lists;
+there are also specialized functions, described in this section, that
+treat it as a ring.
+
+ Some people think this use of the word "kill" is unfortunate, since
+it refers to operations that specifically _do not_ destroy the entities
+"killed". This is in sharp contrast to ordinary life, in which death
+is permanent and "killed" entities do not come back to life.
+Therefore, other metaphors have been proposed. For example, the term
+"cut ring" makes sense to people who, in pre-computer days, used
+scissors and paste to cut up and rearrange manuscripts. However, it
+would be difficult to change the terminology now.
+
+* Menu:
+
+* Kill Ring Concepts:: What text looks like in the kill ring.
+* Kill Functions:: Functions that kill text.
+* Yank Commands:: Commands that access the kill ring.
+* Low-Level Kill Ring:: Functions and variables for kill ring access.
+* Internals of Kill Ring:: Variables that hold kill-ring data.
+
+\1f
+File: lispref.info, Node: Kill Ring Concepts, Next: Kill Functions, Up: The Kill Ring
+
+Kill Ring Concepts
+------------------
+
+The kill ring records killed text as strings in a list, most recent
+first. A short kill ring, for example, might look like this:
+
+ ("some text" "a different piece of text" "even older text")
+
+When the list reaches `kill-ring-max' entries in length, adding a new
+entry automatically deletes the last entry.
+
+ When kill commands are interwoven with other commands, each kill
+command makes a new entry in the kill ring. Multiple kill commands in
+succession build up a single entry in the kill ring, which would be
+yanked as a unit; the second and subsequent consecutive kill commands
+add text to the entry made by the first one.
+
+ For yanking, one entry in the kill ring is designated the "front" of
+the ring. Some yank commands "rotate" the ring by designating a
+different element as the "front." But this virtual rotation doesn't
+change the list itself--the most recent entry always comes first in the
+list.
+
+\1f
+File: lispref.info, Node: Kill Functions, Next: Yank Commands, Prev: Kill Ring Concepts, Up: The Kill Ring
+
+Functions for Killing
+---------------------
+
+`kill-region' is the usual subroutine for killing text. Any command
+that calls this function is a "kill command" (and should probably have
+`kill' in its name). `kill-region' puts the newly killed text in a new
+element at the beginning of the kill ring or adds it to the most recent
+element. It uses the `last-command' variable to determine whether the
+previous command was a kill command, and if so appends the killed text
+to the most recent entry.
+
+ - Command: kill-region start end &optional verbose
+ This function kills the text in the region defined by START and
+ END. The text is deleted but saved in the kill ring, along with
+ its text properties. The value is always `nil'.
+
+ In an interactive call, START and END are point and the mark.
+
+ If the buffer is read-only, `kill-region' modifies the kill ring
+ just the same, then signals an error without modifying the buffer.
+ This is convenient because it lets the user use all the kill
+ commands to copy text into the kill ring from a read-only buffer.
+
+ - Command: copy-region-as-kill start end
+ This command saves the region defined by START and END on the kill
+ ring (including text properties), but does not delete the text
+ from the buffer. It returns `nil'. It also indicates the extent
+ of the text copied by moving the cursor momentarily, or by
+ displaying a message in the echo area.
+
+ The command does not set `this-command' to `kill-region', so a
+ subsequent kill command does not append to the same kill ring
+ entry.
+
+ Don't call `copy-region-as-kill' in Lisp programs unless you aim to
+ support Emacs 18. For Emacs 19, it is better to use `kill-new' or
+ `kill-append' instead. *Note Low-Level Kill Ring::.
+
+\1f
+File: lispref.info, Node: Yank Commands, Next: Low-Level Kill Ring, Prev: Kill Functions, Up: The Kill Ring
+
+Functions for Yanking
+---------------------
+
+"Yanking" means reinserting an entry of previously killed text from the
+kill ring. The text properties are copied too.
+
+ - Command: yank &optional arg
+ This command inserts before point the text in the first entry in
+ the kill ring. It positions the mark at the beginning of that
+ text, and point at the end.
+
+ If ARG is a list (which occurs interactively when the user types
+ `C-u' with no digits), then `yank' inserts the text as described
+ above, but puts point before the yanked text and puts the mark
+ after it.
+
+ If ARG is a number, then `yank' inserts the ARGth most recently
+ killed text--the ARGth element of the kill ring list.
+
+ `yank' does not alter the contents of the kill ring or rotate it.
+ It returns `nil'.
+
+ - Command: yank-pop arg
+ This command replaces the just-yanked entry from the kill ring
+ with a different entry from the kill ring.
+
+ This is allowed only immediately after a `yank' or another
+ `yank-pop'. At such a time, the region contains text that was just
+ inserted by yanking. `yank-pop' deletes that text and inserts in
+ its place a different piece of killed text. It does not add the
+ deleted text to the kill ring, since it is already in the kill
+ ring somewhere.
+
+ If ARG is `nil', then the replacement text is the previous element
+ of the kill ring. If ARG is numeric, the replacement is the ARGth
+ previous kill. If ARG is negative, a more recent kill is the
+ replacement.
+
+ The sequence of kills in the kill ring wraps around, so that after
+ the oldest one comes the newest one, and before the newest one
+ goes the oldest.
+
+ The value is always `nil'.
+
+\1f
+File: lispref.info, Node: Low-Level Kill Ring, Next: Internals of Kill Ring, Prev: Yank Commands, Up: The Kill Ring
+
+Low-Level Kill Ring
+-------------------
+
+These functions and variables provide access to the kill ring at a lower
+level, but still convenient for use in Lisp programs. They take care of
+interaction with X Window selections. They do not exist in Emacs
+version 18.
+
+ - Function: current-kill count &optional do-not-move
+ The function `current-kill' rotates the yanking pointer which
+ designates the "front" of the kill ring by COUNT places (from newer
+ kills to older ones), and returns the text at that place in the
+ ring.
+
+ If the optional second argument DO-NOT-MOVE is non-`nil', then
+ `current-kill' doesn't alter the yanking pointer; it just returns
+ the COUNTth kill, counting from the current yanking pointer.
+
+ If COUNT is zero, indicating a request for the latest kill,
+ `current-kill' calls the value of `interprogram-paste-function'
+ (documented below) before consulting the kill ring.
+
+ - Function: kill-new string &optional replace
+ This function makes the text STRING the latest entry in the kill
+ ring, and sets `kill-ring-yank-pointer' to point to it.
+
+ Normally, STRING is added to the front of the kill ring as a new
+ entry. However, if optional argument REPLACE is non-`nil', the
+ entry previously at the front of the kill ring is discarded, and
+ STRING replaces it.
+
+ This function runs the functions on `kill-hooks', and also invokes
+ the value of `interprogram-cut-function' (see below).
+
+ - Function: kill-append string before-p
+ This function appends the text STRING to the first entry in the
+ kill ring. Normally STRING goes at the end of the entry, but if
+ BEFORE-P is non-`nil', it goes at the beginning. This function
+ also invokes the value of `interprogram-cut-function' (see below).
+
+ - Variable: interprogram-paste-function
+ This variable provides a way of transferring killed text from other
+ programs, when you are using a window system. Its value should be
+ `nil' or a function of no arguments.
+
+ If the value is a function, `current-kill' calls it to get the
+ "most recent kill". If the function returns a non-`nil' value,
+ then that value is used as the "most recent kill". If it returns
+ `nil', then the first element of `kill-ring' is used.
+
+ The normal use of this hook is to get the X server's primary
+ selection as the most recent kill, even if the selection belongs
+ to another X client. *Note X Selections::.
+
+ - Variable: interprogram-cut-function
+ This variable provides a way of communicating killed text to other
+ programs, when you are using a window system. Its value should be
+ `nil' or a function of one argument.
+
+ If the value is a function, `kill-new' and `kill-append' call it
+ with the new first element of the kill ring as an argument.
+
+ The normal use of this hook is to set the X server's primary
+ selection to the newly killed text.
+
+\1f
+File: lispref.info, Node: Internals of Kill Ring, Prev: Low-Level Kill Ring, Up: The Kill Ring
+
+Internals of the Kill Ring
+--------------------------
+
+The variable `kill-ring' holds the kill ring contents, in the form of a
+list of strings. The most recent kill is always at the front of the
+list.
+
+ The `kill-ring-yank-pointer' variable points to a link in the kill
+ring list, whose CAR is the text to yank next. We say it identifies
+the "front" of the ring. Moving `kill-ring-yank-pointer' to a
+different link is called "rotating the kill ring". We call the kill
+ring a "ring" because the functions that move the yank pointer wrap
+around from the end of the list to the beginning, or vice-versa.
+Rotation of the kill ring is virtual; it does not change the value of
+`kill-ring'.
+
+ Both `kill-ring' and `kill-ring-yank-pointer' are Lisp variables
+whose values are normally lists. The word "pointer" in the name of the
+`kill-ring-yank-pointer' indicates that the variable's purpose is to
+identify one element of the list for use by the next yank command.
+
+ The value of `kill-ring-yank-pointer' is always `eq' to one of the
+links in the kill ring list. The element it identifies is the CAR of
+that link. Kill commands, which change the kill ring, also set this
+variable to the value of `kill-ring'. The effect is to rotate the ring
+so that the newly killed text is at the front.
+
+ Here is a diagram that shows the variable `kill-ring-yank-pointer'
+pointing to the second entry in the kill ring `("some text" "a
+different piece of text" "yet older text")'.
+
+ kill-ring kill-ring-yank-pointer
+ | |
+ | ___ ___ ---> ___ ___ ___ ___
+ --> |___|___|------> |___|___|--> |___|___|--> nil
+ | | |
+ | | |
+ | | -->"yet older text"
+ | |
+ | --> "a different piece of text"
+ |
+ --> "some text"
+
+This state of affairs might occur after `C-y' (`yank') immediately
+followed by `M-y' (`yank-pop').
+
+ - Variable: kill-ring
+ This variable holds the list of killed text sequences, most
+ recently killed first.
+
+ - Variable: kill-ring-yank-pointer
+ This variable's value indicates which element of the kill ring is
+ at the "front" of the ring for yanking. More precisely, the value
+ is a tail of the value of `kill-ring', and its CAR is the kill
+ string that `C-y' should yank.
+
+ - User Option: kill-ring-max
+ The value of this variable is the maximum length to which the kill
+ ring can grow, before elements are thrown away at the end. The
+ default value for `kill-ring-max' is 30.
+
+\1f
+File: lispref.info, Node: Undo, Next: Maintaining Undo, Prev: The Kill Ring, Up: Text
+
+Undo
+====
+
+Most buffers have an "undo list", which records all changes made to the
+buffer's text so that they can be undone. (The buffers that don't have
+one are usually special-purpose buffers for which XEmacs assumes that
+undoing is not useful.) All the primitives that modify the text in the
+buffer automatically add elements to the front of the undo list, which
+is in the variable `buffer-undo-list'.
+
+ - Variable: buffer-undo-list
+ This variable's value is the undo list of the current buffer. A
+ value of `t' disables the recording of undo information.
+
+ Here are the kinds of elements an undo list can have:
+
+`INTEGER'
+ This kind of element records a previous value of point. Ordinary
+ cursor motion does not get any sort of undo record, but deletion
+ commands use these entries to record where point was before the
+ command.
+
+`(START . END)'
+ This kind of element indicates how to delete text that was
+ inserted. Upon insertion, the text occupied the range START-END
+ in the buffer.
+
+`(TEXT . POSITION)'
+ This kind of element indicates how to reinsert text that was
+ deleted. The deleted text itself is the string TEXT. The place to
+ reinsert it is `(abs POSITION)'.
+
+`(t HIGH . LOW)'
+ This kind of element indicates that an unmodified buffer became
+ modified. The elements HIGH and LOW are two integers, each
+ recording 16 bits of the visited file's modification time as of
+ when it was previously visited or saved. `primitive-undo' uses
+ those values to determine whether to mark the buffer as unmodified
+ once again; it does so only if the file's modification time
+ matches those numbers.
+
+`(nil PROPERTY VALUE START . END)'
+ This kind of element records a change in a text property. Here's
+ how you might undo the change:
+
+ (put-text-property START END PROPERTY VALUE)
+
+`POSITION'
+ This element indicates where point was at an earlier time.
+ Undoing this element sets point to POSITION. Deletion normally
+ creates an element of this kind as well as a reinsertion element.
+
+`nil'
+ This element is a boundary. The elements between two boundaries
+ are called a "change group"; normally, each change group
+ corresponds to one keyboard command, and undo commands normally
+ undo an entire group as a unit.
+
+ - Function: undo-boundary
+ This function places a boundary element in the undo list. The undo
+ command stops at such a boundary, and successive undo commands undo
+ to earlier and earlier boundaries. This function returns `nil'.
+
+ The editor command loop automatically creates an undo boundary
+ before each key sequence is executed. Thus, each undo normally
+ undoes the effects of one command. Self-inserting input
+ characters are an exception. The command loop makes a boundary
+ for the first such character; the next 19 consecutive
+ self-inserting input characters do not make boundaries, and then
+ the 20th does, and so on as long as self-inserting characters
+ continue.
+
+ All buffer modifications add a boundary whenever the previous
+ undoable change was made in some other buffer. This way, a
+ command that modifies several buffers makes a boundary in each
+ buffer it changes.
+
+ Calling this function explicitly is useful for splitting the
+ effects of a command into more than one unit. For example,
+ `query-replace' calls `undo-boundary' after each replacement, so
+ that the user can undo individual replacements one by one.
+
+ - Function: primitive-undo count list
+ This is the basic function for undoing elements of an undo list.
+ It undoes the first COUNT elements of LIST, returning the rest of
+ LIST. You could write this function in Lisp, but it is convenient
+ to have it in C.
+
+ `primitive-undo' adds elements to the buffer's undo list when it
+ changes the buffer. Undo commands avoid confusion by saving the
+ undo list value at the beginning of a sequence of undo operations.
+ Then the undo operations use and update the saved value. The new
+ elements added by undoing are not part of this saved value, so
+ they don't interfere with continuing to undo.
projects / chise / xemacs-chise.git.1 / blobdiff