XEmacs 21.4.15
[chise/xemacs-chise.git.1] / info / lispref.info-5
1 This is ../info/lispref.info, produced by makeinfo version 4.6 from
2 lispref/lispref.texi.
3
4 INFO-DIR-SECTION XEmacs Editor
5 START-INFO-DIR-ENTRY
6 * Lispref: (lispref).           XEmacs Lisp Reference Manual.
7 END-INFO-DIR-ENTRY
8
9    Edition History:
10
11    GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993 GNU
12 Emacs Lisp Reference Manual Further Revised (v2.02), August 1993 Lucid
13 Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994
14 XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995
15 GNU Emacs Lisp Reference Manual v2.4, June 1995 XEmacs Lisp
16 Programmer's Manual (for 19.13) Third Edition, July 1995 XEmacs Lisp
17 Reference Manual (for 19.14 and 20.0) v3.1, March 1996 XEmacs Lisp
18 Reference Manual (for 19.15 and 20.1, 20.2, 20.3) v3.2, April, May,
19 November 1997 XEmacs Lisp Reference Manual (for 21.0) v3.3, April 1998
20
21    Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software
22 Foundation, Inc.  Copyright (C) 1994, 1995 Sun Microsystems, Inc.
23 Copyright (C) 1995, 1996 Ben Wing.
24
25    Permission is granted to make and distribute verbatim copies of this
26 manual provided the copyright notice and this permission notice are
27 preserved on all copies.
28
29    Permission is granted to copy and distribute modified versions of
30 this manual under the conditions for verbatim copying, provided that the
31 entire resulting derived work is distributed under the terms of a
32 permission notice identical to this one.
33
34    Permission is granted to copy and distribute translations of this
35 manual into another language, under the above conditions for modified
36 versions, except that this permission notice may be stated in a
37 translation approved by the Foundation.
38
39    Permission is granted to copy and distribute modified versions of
40 this manual under the conditions for verbatim copying, provided also
41 that the section entitled "GNU General Public License" is included
42 exactly as in the original, and provided that the entire resulting
43 derived work is distributed under the terms of a permission notice
44 identical to this one.
45
46    Permission is granted to copy and distribute translations of this
47 manual into another language, under the above conditions for modified
48 versions, except that the section entitled "GNU General Public License"
49 may be included in a translation approved by the Free Software
50 Foundation instead of in the original English.
51
52 \1f
53 File: lispref.info,  Node: Create/Delete Dirs,  Next: Magic File Names,  Prev: Contents of Directories,  Up: Files
54
55 Creating and Deleting Directories
56 =================================
57
58 Most XEmacs Lisp file-manipulation functions get errors when used on
59 files that are directories.  For example, you cannot delete a directory
60 with `delete-file'.  These special functions exist to create and delete
61 directories.
62
63  - Command: make-directory dirname &optional parents
64      This function creates a directory named DIRNAME.  Interactively,
65      the default choice of directory to create is the current default
66      directory for file names.  That is useful when you have visited a
67      file in a nonexistent directory.
68
69      Non-interactively, optional argument PARENTS says whether to
70      create parent directories if they don't exist. (Interactively, this
71      always happens.)
72
73  - Command: delete-directory dirname
74      This function deletes the directory named DIRNAME.  The function
75      `delete-file' does not work for files that are directories; you
76      must use `delete-directory' in that case.
77
78 \1f
79 File: lispref.info,  Node: Magic File Names,  Next: Partial Files,  Prev: Create/Delete Dirs,  Up: Files
80
81 Making Certain File Names "Magic"
82 =================================
83
84 You can implement special handling for certain file names.  This is
85 called making those names "magic".  You must supply a regular
86 expression to define the class of names (all those that match the
87 regular expression), plus a handler that implements all the primitive
88 XEmacs file operations for file names that do match.
89
90    The variable `file-name-handler-alist' holds a list of handlers,
91 together with regular expressions that determine when to apply each
92 handler.  Each element has this form:
93
94      (REGEXP . HANDLER)
95
96 All the XEmacs primitives for file access and file name transformation
97 check the given file name against `file-name-handler-alist'.  If the
98 file name matches REGEXP, the primitives handle that file by calling
99 HANDLER.
100
101    The first argument given to HANDLER is the name of the primitive;
102 the remaining arguments are the arguments that were passed to that
103 operation.  (The first of these arguments is typically the file name
104 itself.)  For example, if you do this:
105
106      (file-exists-p FILENAME)
107
108 and FILENAME has handler HANDLER, then HANDLER is called like this:
109
110      (funcall HANDLER 'file-exists-p FILENAME)
111
112    Here are the operations that a magic file name handler gets to
113 handle:
114
115 `add-name-to-file', `copy-file', `delete-directory', `delete-file',
116 `diff-latest-backup-file', `directory-file-name', `directory-files',
117 `dired-compress-file', `dired-uncache', `expand-file-name',
118 `file-accessible-directory-p', `file-attributes', `file-directory-p',
119 `file-executable-p', `file-exists-p', `file-local-copy', `file-modes',
120 `file-name-all-completions', `file-name-as-directory',
121 `file-name-completion', `file-name-directory', `file-name-nondirectory',
122 `file-name-sans-versions', `file-newer-than-file-p', `file-readable-p',
123 `file-regular-p', `file-symlink-p', `file-truename', `file-writable-p',
124 `get-file-buffer', `insert-directory', `insert-file-contents', `load',
125 `make-directory', `make-symbolic-link', `rename-file', `set-file-modes',
126 `set-visited-file-modtime', `unhandled-file-name-directory',
127 `verify-visited-file-modtime', `write-region'.
128
129    Handlers for `insert-file-contents' typically need to clear the
130 buffer's modified flag, with `(set-buffer-modified-p nil)', if the
131 VISIT argument is non-`nil'.  This also has the effect of unlocking the
132 buffer if it is locked.
133
134    The handler function must handle all of the above operations, and
135 possibly others to be added in the future.  It need not implement all
136 these operations itself--when it has nothing special to do for a
137 certain operation, it can reinvoke the primitive, to handle the
138 operation "in the usual way".  It should always reinvoke the primitive
139 for an operation it does not recognize.  Here's one way to do this:
140
141      (defun my-file-handler (operation &rest args)
142        ;; First check for the specific operations
143        ;; that we have special handling for.
144        (cond ((eq operation 'insert-file-contents) ...)
145              ((eq operation 'write-region) ...)
146              ...
147              ;; Handle any operation we don't know about.
148              (t (let ((inhibit-file-name-handlers
149                       (cons 'my-file-handler
150                             (and (eq inhibit-file-name-operation operation)
151                                  inhibit-file-name-handlers)))
152                      (inhibit-file-name-operation operation))
153                   (apply operation args)))))
154
155    When a handler function decides to call the ordinary Emacs primitive
156 for the operation at hand, it needs to prevent the primitive from
157 calling the same handler once again, thus leading to an infinite
158 recursion.  The example above shows how to do this, with the variables
159 `inhibit-file-name-handlers' and `inhibit-file-name-operation'.  Be
160 careful to use them exactly as shown above; the details are crucial for
161 proper behavior in the case of multiple handlers, and for operations
162 that have two file names that may each have handlers.
163
164  - Variable: inhibit-file-name-handlers
165      This variable holds a list of handlers whose use is presently
166      inhibited for a certain operation.
167
168  - Variable: inhibit-file-name-operation
169      The operation for which certain handlers are presently inhibited.
170
171  - Function: find-file-name-handler filename &optional operation
172      This function returns the handler function for file name FILENAME,
173      or `nil' if there is none.  The argument OPERATION should be the
174      operation to be performed on the file--the value you will pass to
175      the handler as its first argument when you call it.  The operation
176      is needed for comparison with `inhibit-file-name-operation'.
177
178  - Function: file-local-copy filename
179      This function copies file FILENAME to an ordinary non-magic file,
180      if it isn't one already.
181
182      If FILENAME specifies a "magic" file name, which programs outside
183      Emacs cannot directly read or write, this copies the contents to
184      an ordinary file and returns that file's name.
185
186      If FILENAME is an ordinary file name, not magic, then this function
187      does nothing and returns `nil'.
188
189  - Function: unhandled-file-name-directory filename
190      This function returns the name of a directory that is not magic.
191      It uses the directory part of FILENAME if that is not magic.
192      Otherwise, it asks the handler what to do.
193
194      This is useful for running a subprocess; every subprocess must
195      have a non-magic directory to serve as its current directory, and
196      this function is a good way to come up with one.
197
198 \1f
199 File: lispref.info,  Node: Partial Files,  Next: Format Conversion,  Prev: Magic File Names,  Up: Files
200
201 Partial Files
202 =============
203
204 * Menu:
205
206 * Intro to Partial Files::
207 * Creating a Partial File::
208 * Detached Partial Files::
209
210 \1f
211 File: lispref.info,  Node: Intro to Partial Files,  Next: Creating a Partial File,  Up: Partial Files
212
213 Intro to Partial Files
214 ----------------------
215
216 A "partial file" is a section of a buffer (called the "master buffer")
217 that is placed in its own buffer and treated as its own file.  Changes
218 made to the partial file are not reflected in the master buffer until
219 the partial file is "saved" using the standard buffer save commands.
220 Partial files can be "reverted" (from the master buffer) just like
221 normal files.  When a file part is active on a master buffer, that
222 section of the master buffer is marked as read-only.  Two file parts on
223 the same master buffer are not allowed to overlap.  Partial file
224 buffers are indicated by the words `File Part' in the modeline.
225
226    The master buffer knows about all the partial files that are active
227 on it, and thus killing or reverting the master buffer will be handled
228 properly.  When the master buffer is saved, if there are any unsaved
229 partial files active on it then the user will be given the opportunity
230 to first save these files.
231
232    When a partial file buffer is first modified, the master buffer is
233 automatically marked as modified so that saving the master buffer will
234 work correctly.
235
236 \1f
237 File: lispref.info,  Node: Creating a Partial File,  Next: Detached Partial Files,  Prev: Intro to Partial Files,  Up: Partial Files
238
239 Creating a Partial File
240 -----------------------
241
242  - Command: make-file-part &optional start end name buffer
243      Make a file part on buffer BUFFER out of the region.  Call it
244      NAME.  This command creates a new buffer containing the contents
245      of the region and marks the buffer as referring to the specified
246      buffer, called the "master buffer".  When the file-part buffer is
247      saved, its changes are integrated back into the master buffer.
248      When the master buffer is deleted, all file parts are deleted with
249      it.
250
251      When called from a function, expects four arguments, START, END,
252      NAME, and BUFFER, all of which are optional and default to the
253      beginning of BUFFER, the end of BUFFER, a name generated from
254      BUFFER's name, and the current buffer, respectively.
255
256 \1f
257 File: lispref.info,  Node: Detached Partial Files,  Prev: Creating a Partial File,  Up: Partial Files
258
259 Detached Partial Files
260 ----------------------
261
262 Every partial file has an extent in the master buffer associated with it
263 (called the "master extent"), marking where in the master buffer the
264 partial file begins and ends.  If the text in master buffer that is
265 contained by the extent is deleted, then the extent becomes "detached",
266 meaning that it no longer refers to a specific region of the master
267 buffer.  This can happen either when the text is deleted directly or
268 when the master buffer is reverted.  Neither of these should happen in
269 normal usage because the master buffer should generally not be edited
270 directly.
271
272    Before doing any operation that references a partial file's master
273 extent, XEmacs checks to make sure that the extent is not detached.  If
274 this is the case, XEmacs warns the user of this and the master extent is
275 deleted out of the master buffer, disconnecting the file part.  The file
276 part's filename is cleared and thus must be explicitly specified if the
277 detached file part is to be saved.
278
279 \1f
280 File: lispref.info,  Node: Format Conversion,  Next: Files and MS-DOS,  Prev: Partial Files,  Up: Files
281
282 File Format Conversion
283 ======================
284
285 The variable `format-alist' defines a list of "file formats", which
286 describe textual representations used in files for the data (text,
287 text-properties, and possibly other information) in an Emacs buffer.
288 Emacs performs format conversion if appropriate when reading and writing
289 files.
290
291  - Variable: format-alist
292      This list contains one format definition for each defined file
293      format.
294
295    Each format definition is a list of this form:
296
297      (NAME DOC-STRING REGEXP FROM-FN TO-FN MODIFY MODE-FN)
298
299    Here is what the elements in a format definition mean:
300
301 NAME
302      The name of this format.
303
304 DOC-STRING
305      A documentation string for the format.
306
307 REGEXP
308      A regular expression which is used to recognize files represented
309      in this format.
310
311 FROM-FN
312      A function to call to decode data in this format (to convert file
313      data into the usual Emacs data representation).
314
315      The FROM-FN is called with two args, BEGIN and END, which specify
316      the part of the buffer it should convert.  It should convert the
317      text by editing it in place.  Since this can change the length of
318      the text, FROM-FN should return the modified end position.
319
320      One responsibility of FROM-FN is to make sure that the beginning
321      of the file no longer matches REGEXP.  Otherwise it is likely to
322      get called again.
323
324 TO-FN
325      A function to call to encode data in this format (to convert the
326      usual Emacs data representation into this format).
327
328      The TO-FN is called with two args, BEGIN and END, which specify
329      the part of the buffer it should convert.  There are two ways it
330      can do the conversion:
331
332         * By editing the buffer in place.  In this case, TO-FN should
333           return the end-position of the range of text, as modified.
334
335         * By returning a list of annotations.  This is a list of
336           elements of the form `(POSITION . STRING)', where POSITION is
337           an integer specifying the relative position in the text to be
338           written, and STRING is the annotation to add there.  The list
339           must be sorted in order of position when TO-FN returns it.
340
341           When `write-region' actually writes the text from the buffer
342           to the file, it intermixes the specified annotations at the
343           corresponding positions.  All this takes place without
344           modifying the buffer.
345
346 MODIFY
347      A flag, `t' if the encoding function modifies the buffer, and
348      `nil' if it works by returning a list of annotations.
349
350 MODE
351      A mode function to call after visiting a file converted from this
352      format.
353
354    The function `insert-file-contents' automatically recognizes file
355 formats when it reads the specified file.  It checks the text of the
356 beginning of the file against the regular expressions of the format
357 definitions, and if it finds a match, it calls the decoding function for
358 that format.  Then it checks all the known formats over again.  It
359 keeps checking them until none of them is applicable.
360
361    Visiting a file, with `find-file-noselect' or the commands that use
362 it, performs conversion likewise (because it calls
363 `insert-file-contents'); it also calls the mode function for each
364 format that it decodes.  It stores a list of the format names in the
365 buffer-local variable `buffer-file-format'.
366
367  - Variable: buffer-file-format
368      This variable states the format of the visited file.  More
369      precisely, this is a list of the file format names that were
370      decoded in the course of visiting the current buffer's file.  It
371      is always local in all buffers.
372
373    When `write-region' writes data into a file, it first calls the
374 encoding functions for the formats listed in `buffer-file-format', in
375 the order of appearance in the list.
376
377  - Command: format-write-file file format
378      This command writes the current buffer contents into the file FILE
379      in format FORMAT, and makes that format the default for future
380      saves of the buffer.  The argument FORMAT is a list of format
381      names.
382
383  - Command: format-find-file file format
384      This command finds the file FILE, converting it according to
385      format FORMAT.  It also makes FORMAT the default if the buffer is
386      saved later.
387
388      The argument FORMAT is a list of format names.  If FORMAT is
389      `nil', no conversion takes place.  Interactively, typing just
390      <RET> for FORMAT specifies `nil'.
391
392  - Command: format-insert-file file format &optional start end
393      This command inserts the contents of file FILE, converting it
394      according to format FORMAT.  If START and END are non-`nil', they
395      specify which part of the file to read, as in
396      `insert-file-contents' (*note Reading from Files::).
397
398      The return value is like what `insert-file-contents' returns: a
399      list of the absolute file name and the length of the data inserted
400      (after conversion).
401
402      The argument FORMAT is a list of format names.  If FORMAT is
403      `nil', no conversion takes place.  Interactively, typing just
404      <RET> for FORMAT specifies `nil'.
405
406  - Variable: auto-save-file-format
407      This variable specifies the format to use for auto-saving.  Its
408      value is a list of format names, just like the value of
409      `buffer-file-format'; but it is used instead of
410      `buffer-file-format' for writing auto-save files.  This variable
411      is always local in all buffers.
412
413 \1f
414 File: lispref.info,  Node: Files and MS-DOS,  Prev: Format Conversion,  Up: Files
415
416 Files and MS-DOS
417 ================
418
419 Emacs on MS-DOS makes a distinction between text files and binary
420 files.  This is necessary because ordinary text files on MS-DOS use a
421 two character sequence between lines: carriage-return and linefeed
422 (CRLF).  Emacs expects just a newline character (a linefeed) between
423 lines.  When Emacs reads or writes a text file on MS-DOS, it needs to
424 convert the line separators.  This means it needs to know which files
425 are text files and which are binary.  It makes this decision when
426 visiting a file, and records the decision in the variable
427 `buffer-file-type' for use when the file is saved.
428
429    *Note MS-DOS Subprocesses::, for a related feature for subprocesses.
430
431  - Variable: buffer-file-type
432      This variable, automatically local in each buffer, records the
433      file type of the buffer's visited file.  The value is `nil' for
434      text, `t' for binary.
435
436  - Function: find-buffer-file-type filename
437      This function determines whether file FILENAME is a text file or a
438      binary file.  It returns `nil' for text, `t' for binary.
439
440  - User Option: file-name-buffer-file-type-alist
441      This variable holds an alist for distinguishing text files from
442      binary files.  Each element has the form (REGEXP . TYPE), where
443      REGEXP is matched against the file name, and TYPE may be is `nil'
444      for text, `t' for binary, or a function to call to compute which.
445      If it is a function, then it is called with a single argument (the
446      file name) and should return `t' or `nil'.
447
448  - User Option: default-buffer-file-type
449      This variable specifies the default file type for files whose names
450      don't indicate anything in particular.  Its value should be `nil'
451      for text, or `t' for binary.
452
453  - Command: find-file-text filename
454      Like `find-file', but treat the file as text regardless of its
455      name.
456
457  - Command: find-file-binary filename
458      Like `find-file', but treat the file as binary regardless of its
459      name.
460
461 \1f
462 File: lispref.info,  Node: Backups and Auto-Saving,  Next: Buffers,  Prev: Files,  Up: Top
463
464 Backups and Auto-Saving
465 ***********************
466
467 Backup files and auto-save files are two methods by which XEmacs tries
468 to protect the user from the consequences of crashes or of the user's
469 own errors.  Auto-saving preserves the text from earlier in the current
470 editing session; backup files preserve file contents prior to the
471 current session.
472
473 * Menu:
474
475 * Backup Files::   How backup files are made; how their names are chosen.
476 * Auto-Saving::    How auto-save files are made; how their names are chosen.
477 * Reverting::      `revert-buffer', and how to customize what it does.
478
479 \1f
480 File: lispref.info,  Node: Backup Files,  Next: Auto-Saving,  Up: Backups and Auto-Saving
481
482 Backup Files
483 ============
484
485 A "backup file" is a copy of the old contents of a file you are
486 editing.  XEmacs makes a backup file the first time you save a buffer
487 into its visited file.  Normally, this means that the backup file
488 contains the contents of the file as it was before the current editing
489 session.  The contents of the backup file normally remain unchanged once
490 it exists.
491
492    Backups are usually made by renaming the visited file to a new name.
493 Optionally, you can specify that backup files should be made by copying
494 the visited file.  This choice makes a difference for files with
495 multiple names; it also can affect whether the edited file remains owned
496 by the original owner or becomes owned by the user editing it.
497
498    By default, XEmacs makes a single backup file for each file edited.
499 You can alternatively request numbered backups; then each new backup
500 file gets a new name.  You can delete old numbered backups when you
501 don't want them any more, or XEmacs can delete them automatically.
502
503 * Menu:
504
505 * Making Backups::     How XEmacs makes backup files, and when.
506 * Rename or Copy::     Two alternatives: renaming the old file or copying it.
507 * Numbered Backups::   Keeping multiple backups for each source file.
508 * Backup Names::       How backup file names are computed; customization.
509
510 \1f
511 File: lispref.info,  Node: Making Backups,  Next: Rename or Copy,  Up: Backup Files
512
513 Making Backup Files
514 -------------------
515
516  - Function: backup-buffer
517      This function makes a backup of the file visited by the current
518      buffer, if appropriate.  It is called by `save-buffer' before
519      saving the buffer the first time.
520
521  - Variable: buffer-backed-up
522      This buffer-local variable indicates whether this buffer's file has
523      been backed up on account of this buffer.  If it is non-`nil', then
524      the backup file has been written.  Otherwise, the file should be
525      backed up when it is next saved (if backups are enabled).  This is
526      a permanent local; `kill-local-variables' does not alter it.
527
528  - User Option: make-backup-files
529      This variable determines whether or not to make backup files.  If
530      it is non-`nil', then XEmacs creates a backup of each file when it
531      is saved for the first time--provided that `backup-inhibited' is
532      `nil' (see below).
533
534      The following example shows how to change the `make-backup-files'
535      variable only in the `RMAIL' buffer and not elsewhere.  Setting it
536      `nil' stops XEmacs from making backups of the `RMAIL' file, which
537      may save disk space.  (You would put this code in your `.emacs'
538      file.)
539
540           (add-hook 'rmail-mode-hook
541                     (function (lambda ()
542                                 (make-local-variable
543                                  'make-backup-files)
544                                 (setq make-backup-files nil))))
545
546  - Variable: backup-enable-predicate
547      This variable's value is a function to be called on certain
548      occasions to decide whether a file should have backup files.  The
549      function receives one argument, a file name to consider.  If the
550      function returns `nil', backups are disabled for that file.
551      Otherwise, the other variables in this section say whether and how
552      to make backups.
553
554      The default value is this:
555
556           (lambda (name)
557             (or (< (length name) 5)
558                 (not (string-equal "/tmp/"
559                                    (substring name 0 5)))))
560
561  - Variable: backup-inhibited
562      If this variable is non-`nil', backups are inhibited.  It records
563      the result of testing `backup-enable-predicate' on the visited file
564      name.  It can also coherently be used by other mechanisms that
565      inhibit backups based on which file is visited.  For example, VC
566      sets this variable non-`nil' to prevent making backups for files
567      managed with a version control system.
568
569      This is a permanent local, so that changing the major mode does
570      not lose its value.  Major modes should not set this
571      variable--they should set `make-backup-files' instead.
572
573 \1f
574 File: lispref.info,  Node: Rename or Copy,  Next: Numbered Backups,  Prev: Making Backups,  Up: Backup Files
575
576 Backup by Renaming or by Copying?
577 ---------------------------------
578
579 There are two ways that XEmacs can make a backup file:
580
581    * XEmacs can rename the original file so that it becomes a backup
582      file, and then write the buffer being saved into a new file.
583      After this procedure, any other names (i.e., hard links) of the
584      original file now refer to the backup file.  The new file is owned
585      by the user doing the editing, and its group is the default for
586      new files written by the user in that directory.
587
588    * XEmacs can copy the original file into a backup file, and then
589      overwrite the original file with new contents.  After this
590      procedure, any other names (i.e., hard links) of the original file
591      still refer to the current version of the file.  The file's owner
592      and group will be unchanged.
593
594    The first method, renaming, is the default.
595
596    The variable `backup-by-copying', if non-`nil', says to use the
597 second method, which is to copy the original file and overwrite it with
598 the new buffer contents.  The variable `file-precious-flag', if
599 non-`nil', also has this effect (as a sideline of its main
600 significance).  *Note Saving Buffers::.
601
602  - Variable: backup-by-copying
603      If this variable is non-`nil', XEmacs always makes backup files by
604      copying.
605
606    The following two variables, when non-`nil', cause the second method
607 to be used in certain special cases.  They have no effect on the
608 treatment of files that don't fall into the special cases.
609
610  - Variable: backup-by-copying-when-linked
611      If this variable is non-`nil', XEmacs makes backups by copying for
612      files with multiple names (hard links).
613
614      This variable is significant only if `backup-by-copying' is `nil',
615      since copying is always used when that variable is non-`nil'.
616
617  - Variable: backup-by-copying-when-mismatch
618      If this variable is non-`nil', XEmacs makes backups by copying in
619      cases where renaming would change either the owner or the group of
620      the file.
621
622      The value has no effect when renaming would not alter the owner or
623      group of the file; that is, for files which are owned by the user
624      and whose group matches the default for a new file created there
625      by the user.
626
627      This variable is significant only if `backup-by-copying' is `nil',
628      since copying is always used when that variable is non-`nil'.
629
630 \1f
631 File: lispref.info,  Node: Numbered Backups,  Next: Backup Names,  Prev: Rename or Copy,  Up: Backup Files
632
633 Making and Deleting Numbered Backup Files
634 -----------------------------------------
635
636 If a file's name is `foo', the names of its numbered backup versions
637 are `foo.~V~', for various integers V, like this: `foo.~1~', `foo.~2~',
638 `foo.~3~', ..., `foo.~259~', and so on.
639
640  - User Option: version-control
641      This variable controls whether to make a single non-numbered backup
642      file or multiple numbered backups.
643
644     `nil'
645           Make numbered backups if the visited file already has
646           numbered backups; otherwise, do not.
647
648     `never'
649           Do not make numbered backups.
650
651     ANYTHING ELSE
652           Make numbered backups.
653
654    The use of numbered backups ultimately leads to a large number of
655 backup versions, which must then be deleted.  XEmacs can do this
656 automatically or it can ask the user whether to delete them.
657
658  - User Option: kept-new-versions
659      The value of this variable is the number of newest versions to keep
660      when a new numbered backup is made.  The newly made backup is
661      included in the count.  The default value is 2.
662
663  - User Option: kept-old-versions
664      The value of this variable is the number of oldest versions to keep
665      when a new numbered backup is made.  The default value is 2.
666
667    If there are backups numbered 1, 2, 3, 5, and 7, and both of these
668 variables have the value 2, then the backups numbered 1 and 2 are kept
669 as old versions and those numbered 5 and 7 are kept as new versions;
670 backup version 3 is excess.  The function `find-backup-file-name'
671 (*note Backup Names::) is responsible for determining which backup
672 versions to delete, but does not delete them itself.
673
674  - User Option: delete-old-versions
675      If this variable is non-`nil', then saving a file deletes excess
676      backup versions silently.  Otherwise, it asks the user whether to
677      delete them.
678
679  - User Option: dired-kept-versions
680      This variable specifies how many of the newest backup versions to
681      keep in the Dired command `.' (`dired-clean-directory').  That's
682      the same thing `kept-new-versions' specifies when you make a new
683      backup file.  The default value is 2.
684
685 \1f
686 File: lispref.info,  Node: Backup Names,  Prev: Numbered Backups,  Up: Backup Files
687
688 Naming Backup Files
689 -------------------
690
691 The functions in this section are documented mainly because you can
692 customize the naming conventions for backup files by redefining them.
693 If you change one, you probably need to change the rest.
694
695  - Function: backup-file-name-p filename
696      This function returns a non-`nil' value if FILENAME is a possible
697      name for a backup file.  A file with the name FILENAME need not
698      exist; the function just checks the name.
699
700           (backup-file-name-p "foo")
701                => nil
702           (backup-file-name-p "foo~")
703                => 3
704
705      The standard definition of this function is as follows:
706
707           (defun backup-file-name-p (file)
708             "Return non-nil if FILE is a backup file \
709           name (numeric or not)..."
710             (string-match "~$" file))
711
712      Thus, the function returns a non-`nil' value if the file name ends
713      with a `~'.  (We use a backslash to split the documentation
714      string's first line into two lines in the text, but produce just
715      one line in the string itself.)
716
717      This simple expression is placed in a separate function to make it
718      easy to redefine for customization.
719
720  - Function: make-backup-file-name filename
721      This function returns a string that is the name to use for a
722      non-numbered backup file for file FILENAME.  On Unix, this is just
723      FILENAME with a tilde appended.
724
725      The standard definition of this function is as follows:
726
727           (defun make-backup-file-name (file)
728             "Create the non-numeric backup file name for FILE.
729           ..."
730             (concat file "~"))
731
732      You can change the backup-file naming convention by redefining this
733      function.  The following example redefines `make-backup-file-name'
734      to prepend a `.' in addition to appending a tilde:
735
736           (defun make-backup-file-name (filename)
737             (concat "." filename "~"))
738           
739           (make-backup-file-name "backups.texi")
740                => ".backups.texi~"
741
742  - Function: find-backup-file-name filename
743      This function computes the file name for a new backup file for
744      FILENAME.  It may also propose certain existing backup files for
745      deletion.  `find-backup-file-name' returns a list whose CAR is the
746      name for the new backup file and whose CDR is a list of backup
747      files whose deletion is proposed.
748
749      Two variables, `kept-old-versions' and `kept-new-versions',
750      determine which backup versions should be kept.  This function
751      keeps those versions by excluding them from the CDR of the value.
752      *Note Numbered Backups::.
753
754      In this example, the value says that `~rms/foo.~5~' is the name to
755      use for the new backup file, and `~rms/foo.~3~' is an "excess"
756      version that the caller should consider deleting now.
757
758           (find-backup-file-name "~rms/foo")
759                => ("~rms/foo.~5~" "~rms/foo.~3~")
760
761  - Function: file-newest-backup filename
762      This function returns the name of the most recent backup file for
763      FILENAME, or `nil' if that file has no backup files.
764
765      Some file comparison commands use this function so that they can
766      automatically compare a file with its most recent backup.
767
768 \1f
769 File: lispref.info,  Node: Auto-Saving,  Next: Reverting,  Prev: Backup Files,  Up: Backups and Auto-Saving
770
771 Auto-Saving
772 ===========
773
774 XEmacs periodically saves all files that you are visiting; this is
775 called "auto-saving".  Auto-saving prevents you from losing more than a
776 limited amount of work if the system crashes.  By default, auto-saves
777 happen every 300 keystrokes, or after around 30 seconds of idle time.
778 *Note Auto-Save: (xemacs)Auto Save, for information on auto-save for
779 users.  Here we describe the functions used to implement auto-saving
780 and the variables that control them.
781
782  - Variable: buffer-auto-save-file-name
783      This buffer-local variable is the name of the file used for
784      auto-saving the current buffer.  It is `nil' if the buffer should
785      not be auto-saved.
786
787           buffer-auto-save-file-name
788           => "/xcssun/users/rms/lewis/#files.texi#"
789
790  - Command: auto-save-mode arg
791      When used interactively without an argument, this command is a
792      toggle switch: it turns on auto-saving of the current buffer if it
793      is off, and vice-versa.  With an argument ARG, the command turns
794      auto-saving on if the value of ARG is `t', a nonempty list, or a
795      positive integer.  Otherwise, it turns auto-saving off.
796
797  - Function: auto-save-file-name-p filename
798      This function returns a non-`nil' value if FILENAME is a string
799      that could be the name of an auto-save file.  It works based on
800      knowledge of the naming convention for auto-save files: a name that
801      begins and ends with hash marks (`#') is a possible auto-save file
802      name.  The argument FILENAME should not contain a directory part.
803
804           (make-auto-save-file-name)
805                => "/xcssun/users/rms/lewis/#files.texi#"
806           (auto-save-file-name-p "#files.texi#")
807                => 0
808           (auto-save-file-name-p "files.texi")
809                => nil
810
811      The standard definition of this function is as follows:
812
813           (defun auto-save-file-name-p (filename)
814             "Return non-nil if FILENAME can be yielded by..."
815             (string-match "^#.*#$" filename))
816
817      This function exists so that you can customize it if you wish to
818      change the naming convention for auto-save files.  If you redefine
819      it, be sure to redefine the function `make-auto-save-file-name'
820      correspondingly.
821
822  - Function: make-auto-save-file-name &optional filename
823      This function returns the file name to use for auto-saving the
824      current buffer.  This is just the file name with hash marks (`#')
825      appended and prepended to it.  This function does not look at the
826      variable `auto-save-visited-file-name' (described below); you
827      should check that before calling this function.
828
829           (make-auto-save-file-name)
830                => "/xcssun/users/rms/lewis/#backup.texi#"
831
832      The standard definition of this function is as follows:
833
834           (defun make-auto-save-file-name ()
835             "Return file name to use for auto-saves \
836           of current buffer.
837           ..."
838             (if buffer-file-name
839                 (concat
840                  (file-name-directory buffer-file-name)
841                  "#"
842                  (file-name-nondirectory buffer-file-name)
843                  "#")
844               (expand-file-name
845                (concat "#%" (buffer-name) "#"))))
846
847      This exists as a separate function so that you can redefine it to
848      customize the naming convention for auto-save files.  Be sure to
849      change `auto-save-file-name-p' in a corresponding way.
850
851  - Variable: auto-save-visited-file-name
852      If this variable is non-`nil', XEmacs auto-saves buffers in the
853      files they are visiting.  That is, the auto-save is done in the
854      same file that you are editing.  Normally, this variable is `nil',
855      so auto-save files have distinct names that are created by
856      `make-auto-save-file-name'.
857
858      When you change the value of this variable, the value does not take
859      effect until the next time auto-save mode is reenabled in any given
860      buffer.  If auto-save mode is already enabled, auto-saves continue
861      to go in the same file name until `auto-save-mode' is called again.
862
863  - Function: recent-auto-save-p
864      This function returns `t' if the current buffer has been
865      auto-saved since the last time it was read in or saved.
866
867  - Function: set-buffer-auto-saved
868      This function marks the current buffer as auto-saved.  The buffer
869      will not be auto-saved again until the buffer text is changed
870      again.  The function returns `nil'.
871
872  - User Option: auto-save-interval
873      The value of this variable is the number of characters that XEmacs
874      reads from the keyboard between auto-saves.  Each time this many
875      more characters are read, auto-saving is done for all buffers in
876      which it is enabled.
877
878  - User Option: auto-save-timeout
879      The value of this variable is the number of seconds of idle time
880      that should cause auto-saving.  Each time the user pauses for this
881      long, XEmacs auto-saves any buffers that need it.  (Actually, the
882      specified timeout is multiplied by a factor depending on the size
883      of the current buffer.)
884
885  - Variable: auto-save-hook
886      This normal hook is run whenever an auto-save is about to happen.
887
888  - User Option: auto-save-default
889      If this variable is non-`nil', buffers that are visiting files
890      have auto-saving enabled by default.  Otherwise, they do not.
891
892  - Command: do-auto-save &optional no-message current-only
893      This function auto-saves all buffers that need to be auto-saved.
894      It saves all buffers for which auto-saving is enabled and that
895      have been changed since the previous auto-save.
896
897      Normally, if any buffers are auto-saved, a message that says
898      `Auto-saving...' is displayed in the echo area while auto-saving is
899      going on.  However, if NO-MESSAGE is non-`nil', the message is
900      inhibited.
901
902      If CURRENT-ONLY is non-`nil', only the current buffer is
903      auto-saved.
904
905  - Function: delete-auto-save-file-if-necessary
906      This function deletes the current buffer's auto-save file if
907      `delete-auto-save-files' is non-`nil'.  It is called every time a
908      buffer is saved.
909
910  - Variable: delete-auto-save-files
911      This variable is used by the function
912      `delete-auto-save-file-if-necessary'.  If it is non-`nil', Emacs
913      deletes auto-save files when a true save is done (in the visited
914      file).  This saves disk space and unclutters your directory.
915
916  - Function: rename-auto-save-file
917      This function adjusts the current buffer's auto-save file name if
918      the visited file name has changed.  It also renames an existing
919      auto-save file.  If the visited file name has not changed, this
920      function does nothing.
921
922  - Variable: buffer-saved-size
923      The value of this buffer-local variable is the length of the
924      current buffer as of the last time it was read in, saved, or
925      auto-saved.  This is used to detect a substantial decrease in
926      size, and turn off auto-saving in response.
927
928      If it is -1, that means auto-saving is temporarily shut off in this
929      buffer due to a substantial deletion.  Explicitly saving the buffer
930      stores a positive value in this variable, thus reenabling
931      auto-saving.  Turning auto-save mode off or on also alters this
932      variable.
933
934  - Variable: auto-save-list-file-name
935      This variable (if non-`nil') specifies a file for recording the
936      names of all the auto-save files.  Each time XEmacs does
937      auto-saving, it writes two lines into this file for each buffer
938      that has auto-saving enabled.  The first line gives the name of
939      the visited file (it's empty if the buffer has none), and the
940      second gives the name of the auto-save file.
941
942      If XEmacs exits normally, it deletes this file.  If XEmacs
943      crashes, you can look in the file to find all the auto-save files
944      that might contain work that was otherwise lost.  The
945      `recover-session' command uses these files.
946
947      The default name for this file is in your home directory and
948      starts with `.saves-'.  It also contains the XEmacs process ID and
949      the host name.
950
951 \1f
952 File: lispref.info,  Node: Reverting,  Prev: Auto-Saving,  Up: Backups and Auto-Saving
953
954 Reverting
955 =========
956
957 If you have made extensive changes to a file and then change your mind
958 about them, you can get rid of them by reading in the previous version
959 of the file with the `revert-buffer' command.  *Note Reverting a
960 Buffer: (xemacs)Reverting.
961
962  - Command: revert-buffer &optional check-auto-save noconfirm
963           preserve-modes
964      This command replaces the buffer text with the text of the visited
965      file on disk.  This action undoes all changes since the file was
966      visited or saved.
967
968      If the argument CHECK-AUTO-SAVE is non-`nil', and the latest
969      auto-save file is more recent than the visited file,
970      `revert-buffer' asks the user whether to use that instead.
971      Otherwise, it always uses the text of the visited file itself.
972      Interactively, CHECK-AUTO-SAVE is set if there is a numeric prefix
973      argument.
974
975      Normally, `revert-buffer' asks for confirmation before it changes
976      the buffer; but if the argument NOCONFIRM is non-`nil',
977      `revert-buffer' does not ask for confirmation.
978
979      Optional third argument PRESERVE-MODES non-`nil' means don't alter
980      the files modes.  Normally we reinitialize them using
981      `normal-mode'.
982
983      Reverting tries to preserve marker positions in the buffer by
984      using the replacement feature of `insert-file-contents'.  If the
985      buffer contents and the file contents are identical before the
986      revert operation, reverting preserves all the markers.  If they
987      are not identical, reverting does change the buffer; then it
988      preserves the markers in the unchanged text (if any) at the
989      beginning and end of the buffer.  Preserving any additional
990      markers would be problematical.
991
992    You can customize how `revert-buffer' does its work by setting these
993 variables--typically, as buffer-local variables.
994
995  - Variable: revert-buffer-function
996      The value of this variable is the function to use to revert this
997      buffer.  If non-`nil', it is called as a function with no
998      arguments to do the work of reverting.  If the value is `nil',
999      reverting works the usual way.
1000
1001      Modes such as Dired mode, in which the text being edited does not
1002      consist of a file's contents but can be regenerated in some other
1003      fashion, give this variable a buffer-local value that is a
1004      function to regenerate the contents.
1005
1006  - Variable: revert-buffer-insert-file-contents-function
1007      The value of this variable, if non-`nil', is the function to use to
1008      insert the updated contents when reverting this buffer.  The
1009      function receives two arguments: first the file name to use;
1010      second, `t' if the user has asked to read the auto-save file.
1011
1012  - Variable: before-revert-hook
1013      This normal hook is run by `revert-buffer' before actually
1014      inserting the modified contents--but only if
1015      `revert-buffer-function' is `nil'.
1016
1017      Font Lock mode uses this hook to record that the buffer contents
1018      are no longer fontified.
1019
1020  - Variable: after-revert-hook
1021      This normal hook is run by `revert-buffer' after actually inserting
1022      the modified contents--but only if `revert-buffer-function' is
1023      `nil'.
1024
1025      Font Lock mode uses this hook to recompute the fonts for the
1026      updated buffer contents.
1027
1028 \1f
1029 File: lispref.info,  Node: Buffers,  Next: Windows,  Prev: Backups and Auto-Saving,  Up: Top
1030
1031 Buffers
1032 *******
1033
1034 A "buffer" is a Lisp object containing text to be edited.  Buffers are
1035 used to hold the contents of files that are being visited; there may
1036 also be buffers that are not visiting files.  While several buffers may
1037 exist at one time, exactly one buffer is designated the "current
1038 buffer" at any time.  Most editing commands act on the contents of the
1039 current buffer.  Each buffer, including the current buffer, may or may
1040 not be displayed in any window.
1041
1042 * Menu:
1043
1044 * Buffer Basics::       What is a buffer?
1045 * Current Buffer::      Designating a buffer as current
1046                           so primitives will access its contents.
1047 * Buffer Names::        Accessing and changing buffer names.
1048 * Buffer File Name::    The buffer file name indicates which file is visited.
1049 * Buffer Modification:: A buffer is "modified" if it needs to be saved.
1050 * Modification Time::   Determining whether the visited file was changed
1051                          ``behind XEmacs's back''.
1052 * Read Only Buffers::   Modifying text is not allowed in a read-only buffer.
1053 * The Buffer List::     How to look at all the existing buffers.
1054 * Creating Buffers::    Functions that create buffers.
1055 * Killing Buffers::     Buffers exist until explicitly killed.
1056 * Indirect Buffers::    An indirect buffer shares text with some other buffer.
1057
1058 \1f
1059 File: lispref.info,  Node: Buffer Basics,  Next: Current Buffer,  Up: Buffers
1060
1061 Buffer Basics
1062 =============
1063
1064 A "buffer" is a Lisp object containing text to be edited.  Buffers are
1065 used to hold the contents of files that are being visited; there may
1066 also be buffers that are not visiting files.  While several buffers may
1067 exist at one time, exactly one buffer is designated the "current
1068 buffer" at any time.  Most editing commands act on the contents of the
1069 current buffer.  Each buffer, including the current buffer, may or may
1070 not be displayed in any windows.
1071
1072 Buffers in Emacs editing are objects that have distinct names and hold
1073 text that can be edited.  Buffers appear to Lisp programs as a special
1074 data type.  You can think of the contents of a buffer as an extendible
1075 string; insertions and deletions may occur in any part of the buffer.
1076 *Note Text::.
1077
1078    A Lisp buffer object contains numerous pieces of information.  Some
1079 of this information is directly accessible to the programmer through
1080 variables, while other information is accessible only through
1081 special-purpose functions.  For example, the visited file name is
1082 directly accessible through a variable, while the value of point is
1083 accessible only through a primitive function.
1084
1085    Buffer-specific information that is directly accessible is stored in
1086 "buffer-local" variable bindings, which are variable values that are
1087 effective only in a particular buffer.  This feature allows each buffer
1088 to override the values of certain variables.  Most major modes override
1089 variables such as `fill-column' or `comment-column' in this way.  For
1090 more information about buffer-local variables and functions related to
1091 them, see *Note Buffer-Local Variables::.
1092
1093    For functions and variables related to visiting files in buffers, see
1094 *Note Visiting Files:: and *Note Saving Buffers::.  For functions and
1095 variables related to the display of buffers in windows, see *Note
1096 Buffers and Windows::.
1097
1098  - Function: bufferp object
1099      This function returns `t' if OBJECT is a buffer, `nil' otherwise.
1100
1101 \1f
1102 File: lispref.info,  Node: Current Buffer,  Next: Buffer Names,  Prev: Buffer Basics,  Up: Buffers
1103
1104 The Current Buffer
1105 ==================
1106
1107 There are, in general, many buffers in an Emacs session.  At any time,
1108 one of them is designated as the "current buffer".  This is the buffer
1109 in which most editing takes place, because most of the primitives for
1110 examining or changing text in a buffer operate implicitly on the
1111 current buffer (*note Text::).  Normally the buffer that is displayed on
1112 the screen in the selected window is the current buffer, but this is not
1113 always so: a Lisp program can designate any buffer as current
1114 temporarily in order to operate on its contents, without changing what
1115 is displayed on the screen.
1116
1117    The way to designate a current buffer in a Lisp program is by calling
1118 `set-buffer'.  The specified buffer remains current until a new one is
1119 designated.
1120
1121    When an editing command returns to the editor command loop, the
1122 command loop designates the buffer displayed in the selected window as
1123 current, to prevent confusion: the buffer that the cursor is in when
1124 Emacs reads a command is the buffer that the command will apply to.
1125 (*Note Command Loop::.)  Therefore, `set-buffer' is not the way to
1126 switch visibly to a different buffer so that the user can edit it.  For
1127 this, you must use the functions described in *Note Displaying
1128 Buffers::.
1129
1130    However, Lisp functions that change to a different current buffer
1131 should not depend on the command loop to set it back afterwards.
1132 Editing commands written in XEmacs Lisp can be called from other
1133 programs as well as from the command loop.  It is convenient for the
1134 caller if the subroutine does not change which buffer is current
1135 (unless, of course, that is the subroutine's purpose).  Therefore, you
1136 should normally use `set-buffer' within a `save-excursion' that will
1137 restore the current buffer when your function is done (*note
1138 Excursions::).  Here is an example, the code for the command
1139 `append-to-buffer' (with the documentation string abridged):
1140
1141      (defun append-to-buffer (buffer start end)
1142        "Append to specified buffer the text of the region.
1143      ..."
1144        (interactive "BAppend to buffer: \nr")
1145        (let ((oldbuf (current-buffer)))
1146          (save-excursion
1147            (set-buffer (get-buffer-create buffer))
1148            (insert-buffer-substring oldbuf start end))))
1149
1150 This function binds a local variable to the current buffer, and then
1151 `save-excursion' records the values of point, the mark, and the
1152 original buffer.  Next, `set-buffer' makes another buffer current.
1153 Finally, `insert-buffer-substring' copies the string from the original
1154 current buffer to the new current buffer.
1155
1156    If the buffer appended to happens to be displayed in some window,
1157 the next redisplay will show how its text has changed.  Otherwise, you
1158 will not see the change immediately on the screen.  The buffer becomes
1159 current temporarily during the execution of the command, but this does
1160 not cause it to be displayed.
1161
1162    If you make local bindings (with `let' or function arguments) for a
1163 variable that may also have buffer-local bindings, make sure that the
1164 same buffer is current at the beginning and at the end of the local
1165 binding's scope.  Otherwise you might bind it in one buffer and unbind
1166 it in another!  There are two ways to do this.  In simple cases, you may
1167 see that nothing ever changes the current buffer within the scope of the
1168 binding.  Otherwise, use `save-excursion' to make sure that the buffer
1169 current at the beginning is current again whenever the variable is
1170 unbound.
1171
1172    It is not reliable to change the current buffer back with
1173 `set-buffer', because that won't do the job if a quit happens while the
1174 wrong buffer is current.  Here is what _not_ to do:
1175
1176      (let (buffer-read-only
1177            (obuf (current-buffer)))
1178        (set-buffer ...)
1179        ...
1180        (set-buffer obuf))
1181
1182 Using `save-excursion', as shown below, handles quitting, errors, and
1183 `throw', as well as ordinary evaluation.
1184
1185      (let (buffer-read-only)
1186        (save-excursion
1187          (set-buffer ...)
1188          ...))
1189
1190  - Function: current-buffer
1191      This function returns the current buffer.
1192
1193           (current-buffer)
1194                => #<buffer buffers.texi>
1195
1196  - Function: set-buffer buffer-or-name
1197      This function makes BUFFER-OR-NAME the current buffer.  It does
1198      not display the buffer in the currently selected window or in any
1199      other window, so the user cannot necessarily see the buffer.  But
1200      Lisp programs can in any case work on it.
1201
1202      BUFFER-OR-NAME must be a buffer or the name of an existing
1203      buffer-else an error is signaled.  This function returns the buffer
1204      identified by BUFFER-OR-NAME.
1205
1206 \1f
1207 File: lispref.info,  Node: Buffer Names,  Next: Buffer File Name,  Prev: Current Buffer,  Up: Buffers
1208
1209 Buffer Names
1210 ============
1211
1212 Each buffer has a unique name, which is a string.  Many of the
1213 functions that work on buffers accept either a buffer or a buffer name
1214 as an argument.  Any argument called BUFFER-OR-NAME is of this sort,
1215 and an error is signaled if it is neither a string nor a buffer.  Any
1216 argument called BUFFER must be an actual buffer object, not a name.
1217
1218    Buffers that are ephemeral and generally uninteresting to the user
1219 have names starting with a space, so that the `list-buffers' and
1220 `buffer-menu' commands don't mention them.  A name starting with space
1221 also initially disables recording undo information; see *Note Undo::.
1222
1223  - Function: buffer-name &optional buffer
1224      This function returns the name of BUFFER as a string.  If BUFFER
1225      is not supplied, it defaults to the current buffer.
1226
1227      If `buffer-name' returns `nil', it means that BUFFER has been
1228      killed.  *Note Killing Buffers::.
1229
1230           (buffer-name)
1231                => "buffers.texi"
1232           
1233           (setq foo (get-buffer "temp"))
1234                => #<buffer temp>
1235           (kill-buffer foo)
1236                => nil
1237           (buffer-name foo)
1238                => nil
1239           foo
1240                => #<killed buffer>
1241
1242  - Command: rename-buffer newname &optional unique
1243      This function renames the current buffer to NEWNAME.  An error is
1244      signaled if NEWNAME is not a string, or if there is already a
1245      buffer with that name.  The function returns `nil'.
1246
1247      Ordinarily, `rename-buffer' signals an error if NEWNAME is already
1248      in use.  However, if UNIQUE is non-`nil', it modifies NEWNAME to
1249      make a name that is not in use.  Interactively, you can make
1250      UNIQUE non-`nil' with a numeric prefix argument.
1251
1252      One application of this command is to rename the `*shell*' buffer
1253      to some other name, thus making it possible to create a second
1254      shell buffer under the name `*shell*'.
1255
1256  - Function: get-buffer buffer-or-name
1257      This function returns the buffer named BUFFER-OR-NAME.  If
1258      BUFFER-OR-NAME is a string and there is no buffer with that name,
1259      the value is `nil'.  If BUFFER-OR-NAME is actually a buffer, it is
1260      returned as given.  (That is not very useful, so the argument is
1261      usually a name.)  For example:
1262
1263           (setq b (get-buffer "lewis"))
1264                => #<buffer lewis>
1265           (get-buffer b)
1266                => #<buffer lewis>
1267           (get-buffer "Frazzle-nots")
1268                => nil
1269
1270      See also the function `get-buffer-create' in *Note Creating
1271      Buffers::.
1272
1273  - Function: generate-new-buffer-name starting-name &optional ignore
1274      This function returns a name that would be unique for a new
1275      buffer--but does not create the buffer.  It starts with
1276      STARTING-NAME, and produces a name not currently in use for any
1277      buffer by appending a number inside of `<...>'.
1278
1279      If IGNORE is given, it specifies a name that is okay to use (if it
1280      is in the sequence to be tried), even if a buffer with that name
1281      exists.
1282
1283      See the related function `generate-new-buffer' in *Note Creating
1284      Buffers::.
1285
1286 \1f
1287 File: lispref.info,  Node: Buffer File Name,  Next: Buffer Modification,  Prev: Buffer Names,  Up: Buffers
1288
1289 Buffer File Name
1290 ================
1291
1292 The "buffer file name" is the name of the file that is visited in that
1293 buffer.  When a buffer is not visiting a file, its buffer file name is
1294 `nil'.  Most of the time, the buffer name is the same as the
1295 nondirectory part of the buffer file name, but the buffer file name and
1296 the buffer name are distinct and can be set independently.  *Note
1297 Visiting Files::.
1298
1299  - Function: buffer-file-name &optional buffer
1300      This function returns the absolute file name of the file that
1301      BUFFER is visiting.  If BUFFER is not visiting any file,
1302      `buffer-file-name' returns `nil'.  If BUFFER is not supplied, it
1303      defaults to the current buffer.
1304
1305           (buffer-file-name (other-buffer))
1306                => "/usr/user/lewis/manual/files.texi"
1307
1308  - Variable: buffer-file-name
1309      This buffer-local variable contains the name of the file being
1310      visited in the current buffer, or `nil' if it is not visiting a
1311      file.  It is a permanent local, unaffected by
1312      `kill-local-variables'.
1313
1314           buffer-file-name
1315                => "/usr/user/lewis/manual/buffers.texi"
1316
1317      It is risky to change this variable's value without doing various
1318      other things.  See the definition of `set-visited-file-name' in
1319      `files.el'; some of the things done there, such as changing the
1320      buffer name, are not strictly necessary, but others are essential
1321      to avoid confusing XEmacs.
1322
1323  - Variable: buffer-file-truename
1324      This buffer-local variable holds the truename of the file visited
1325      in the current buffer, or `nil' if no file is visited.  It is a
1326      permanent local, unaffected by `kill-local-variables'.  *Note
1327      Truenames::.
1328
1329  - Variable: buffer-file-number
1330      This buffer-local variable holds the file number and directory
1331      device number of the file visited in the current buffer, or `nil'
1332      if no file or a nonexistent file is visited.  It is a permanent
1333      local, unaffected by `kill-local-variables'.  *Note Truenames::.
1334
1335      The value is normally a list of the form `(FILENUM DEVNUM)'.  This
1336      pair of numbers uniquely identifies the file among all files
1337      accessible on the system.  See the function `file-attributes', in
1338      *Note File Attributes::, for more information about them.
1339
1340  - Function: get-file-buffer filename
1341      This function returns the buffer visiting file FILENAME.  If there
1342      is no such buffer, it returns `nil'.  The argument FILENAME, which
1343      must be a string, is expanded (*note File Name Expansion::), then
1344      compared against the visited file names of all live buffers.
1345
1346           (get-file-buffer "buffers.texi")
1347               => #<buffer buffers.texi>
1348
1349      In unusual circumstances, there can be more than one buffer
1350      visiting the same file name.  In such cases, this function returns
1351      the first such buffer in the buffer list.
1352
1353  - Command: set-visited-file-name filename
1354      If FILENAME is a non-empty string, this function changes the name
1355      of the file visited in current buffer to FILENAME.  (If the buffer
1356      had no visited file, this gives it one.)  The _next time_ the
1357      buffer is saved it will go in the newly-specified file.  This
1358      command marks the buffer as modified, since it does not (as far as
1359      XEmacs knows) match the contents of FILENAME, even if it matched
1360      the former visited file.
1361
1362      If FILENAME is `nil' or the empty string, that stands for "no
1363      visited file".  In this case, `set-visited-file-name' marks the
1364      buffer as having no visited file.
1365
1366      When the function `set-visited-file-name' is called interactively,
1367      it prompts for FILENAME in the minibuffer.
1368
1369      See also `clear-visited-file-modtime' and
1370      `verify-visited-file-modtime' in *Note Buffer Modification::.
1371
1372  - Variable: list-buffers-directory
1373      This buffer-local variable records a string to display in a buffer
1374      listing in place of the visited file name, for buffers that don't
1375      have a visited file name.  Dired buffers use this variable.
1376
1377 \1f
1378 File: lispref.info,  Node: Buffer Modification,  Next: Modification Time,  Prev: Buffer File Name,  Up: Buffers
1379
1380 Buffer Modification
1381 ===================
1382
1383 XEmacs keeps a flag called the "modified flag" for each buffer, to
1384 record whether you have changed the text of the buffer.  This flag is
1385 set to `t' whenever you alter the contents of the buffer, and cleared
1386 to `nil' when you save it.  Thus, the flag shows whether there are
1387 unsaved changes.  The flag value is normally shown in the modeline
1388 (*note Modeline Variables::), and controls saving (*note Saving
1389 Buffers::) and auto-saving (*note Auto-Saving::).
1390
1391    Some Lisp programs set the flag explicitly.  For example, the
1392 function `set-visited-file-name' sets the flag to `t', because the text
1393 does not match the newly-visited file, even if it is unchanged from the
1394 file formerly visited.
1395
1396    The functions that modify the contents of buffers are described in
1397 *Note Text::.
1398
1399  - Function: buffer-modified-p &optional buffer
1400      This function returns `t' if the buffer BUFFER has been modified
1401      since it was last read in from a file or saved, or `nil'
1402      otherwise.  If BUFFER is not supplied, the current buffer is
1403      tested.
1404
1405  - Function: set-buffer-modified-p flag &optional buffer
1406      This function marks BUFFER as modified if FLAG is non-`nil', or as
1407      unmodified if the flag is `nil'.  BUFFER defaults to the current
1408      buffer.
1409
1410      Another effect of calling this function is to cause unconditional
1411      redisplay of the modeline for the current buffer.  In fact, the
1412      function `redraw-modeline' works by doing this:
1413
1414           (set-buffer-modified-p (buffer-modified-p))
1415
1416  - Command: not-modified &optional arg
1417      This command marks the current buffer as unmodified, and not
1418      needing to be saved. (If ARG is non-`nil', the buffer is instead
1419      marked as modified.) Don't use this function in programs, since it
1420      prints a message in the echo area; use `set-buffer-modified-p'
1421      (above) instead.
1422
1423  - Function: buffer-modified-tick &optional buffer
1424      This function returns BUFFER`s modification-count.  This is a
1425      counter that increments every time the buffer is modified.  If
1426      BUFFER is `nil' (or omitted), the current buffer is used.
1427
1428 \1f
1429 File: lispref.info,  Node: Modification Time,  Next: Read Only Buffers,  Prev: Buffer Modification,  Up: Buffers
1430
1431 Comparison of Modification Time
1432 ===============================
1433
1434 Suppose that you visit a file and make changes in its buffer, and
1435 meanwhile the file itself is changed on disk.  At this point, saving the
1436 buffer would overwrite the changes in the file.  Occasionally this may
1437 be what you want, but usually it would lose valuable information.
1438 XEmacs therefore checks the file's modification time using the functions
1439 described below before saving the file.
1440
1441  - Function: verify-visited-file-modtime buffer
1442      This function compares what BUFFER has recorded for the
1443      modification time of its visited file against the actual
1444      modification time of the file as recorded by the operating system.
1445      The two should be the same unless some other process has written
1446      the file since XEmacs visited or saved it.
1447
1448      The function returns `t' if the last actual modification time and
1449      XEmacs's recorded modification time are the same, `nil' otherwise.
1450
1451  - Function: clear-visited-file-modtime
1452      This function clears out the record of the last modification time
1453      of the file being visited by the current buffer.  As a result, the
1454      next attempt to save this buffer will not complain of a
1455      discrepancy in file modification times.
1456
1457      This function is called in `set-visited-file-name' and other
1458      exceptional places where the usual test to avoid overwriting a
1459      changed file should not be done.
1460
1461  - Function: visited-file-modtime
1462      This function returns the buffer's recorded last file modification
1463      time, as a list of the form `(HIGH . LOW)'.  (This is the same
1464      format that `file-attributes' uses to return time values; see
1465      *Note File Attributes::.)
1466
1467  - Function: set-visited-file-modtime &optional time
1468      This function updates the buffer's record of the last modification
1469      time of the visited file, to the value specified by TIME if TIME
1470      is not `nil', and otherwise to the last modification time of the
1471      visited file.
1472
1473      If TIME is not `nil', it should have the form `(HIGH . LOW)' or
1474      `(HIGH LOW)', in either case containing two integers, each of
1475      which holds 16 bits of the time.
1476
1477      This function is useful if the buffer was not read from the file
1478      normally, or if the file itself has been changed for some known
1479      benign reason.
1480
1481  - Function: ask-user-about-supersession-threat filename
1482      This function is used to ask a user how to proceed after an
1483      attempt to modify an obsolete buffer visiting file FILENAME.  An
1484      "obsolete buffer" is an unmodified buffer for which the associated
1485      file on disk is newer than the last save-time of the buffer.  This
1486      means some other program has probably altered the file.
1487
1488      Depending on the user's answer, the function may return normally,
1489      in which case the modification of the buffer proceeds, or it may
1490      signal a `file-supersession' error with data `(FILENAME)', in which
1491      case the proposed buffer modification is not allowed.
1492
1493      This function is called automatically by XEmacs on the proper
1494      occasions.  It exists so you can customize XEmacs by redefining it.
1495      See the file `userlock.el' for the standard definition.
1496
1497      See also the file locking mechanism in *Note File Locks::.
1498
1499 \1f
1500 File: lispref.info,  Node: Read Only Buffers,  Next: The Buffer List,  Prev: Modification Time,  Up: Buffers
1501
1502 Read-Only Buffers
1503 =================
1504
1505 If a buffer is "read-only", then you cannot change its contents,
1506 although you may change your view of the contents by scrolling and
1507 narrowing.
1508
1509    Read-only buffers are used in two kinds of situations:
1510
1511    * A buffer visiting a write-protected file is normally read-only.
1512
1513      Here, the purpose is to show the user that editing the buffer with
1514      the aim of saving it in the file may be futile or undesirable.
1515      The user who wants to change the buffer text despite this can do
1516      so after clearing the read-only flag with `C-x C-q'.
1517
1518    * Modes such as Dired and Rmail make buffers read-only when altering
1519      the contents with the usual editing commands is probably a mistake.
1520
1521      The special commands of these modes bind `buffer-read-only' to
1522      `nil' (with `let') or bind `inhibit-read-only' to `t' around the
1523      places where they change the text.
1524
1525  - Variable: buffer-read-only
1526      This buffer-local variable specifies whether the buffer is
1527      read-only.  The buffer is read-only if this variable is non-`nil'.
1528
1529  - Variable: inhibit-read-only
1530      If this variable is non-`nil', then read-only buffers and read-only
1531      characters may be modified.  Read-only characters in a buffer are
1532      those that have non-`nil' `read-only' properties (either text
1533      properties or extent properties).  *Note Extent Properties::, for
1534      more information about text properties and extent properties.
1535
1536      If `inhibit-read-only' is `t', all `read-only' character
1537      properties have no effect.  If `inhibit-read-only' is a list, then
1538      `read-only' character properties have no effect if they are members
1539      of the list (comparison is done with `eq').
1540
1541  - Command: toggle-read-only &optional arg
1542      This command changes whether the current buffer is read-only.
1543      Interactively, if a prefix arg ARG is supplied, set the current
1544      buffer read only if and only if ARG is positive.
1545
1546      This command is intended for interactive use only; don't use it in
1547      programs.  At any given point in a program, you should know
1548      whether you want the read-only flag on or off; so you can set
1549      `buffer-read-only' explicitly to the proper value, `t' or `nil'.
1550
1551  - Function: barf-if-buffer-read-only &optional buffer start end
1552      This function signals a `buffer-read-only' error if BUFFER is
1553      read-only.  BUFFER defaults to the current buffer.  *Note
1554      Interactive Call::, for another way to signal an error if the
1555      current buffer is read-only.
1556
1557      If optional argument START is non-`nil', all extents in the buffer
1558      which overlap that part of the buffer are checked to ensure none
1559      has a `read-only' property. (Extents that lie completely within the
1560      range, however, are not checked.)  END defaults to the value of
1561      START.
1562
1563      If START and END are equal, the range checked is [START, END]
1564      (i.e.  closed on both ends); otherwise, the range checked is
1565      (START, END) \(open on both ends), except that extents that lie
1566      completely within [START, END] are not checked.  See
1567      `extent-in-region-p' for a fuller discussion.
1568
1569 \1f
1570 File: lispref.info,  Node: The Buffer List,  Next: Creating Buffers,  Prev: Read Only Buffers,  Up: Buffers
1571
1572 The Buffer List
1573 ===============
1574
1575 The "buffer list" is a list of all live buffers.  Creating a buffer
1576 adds it to this list, and killing a buffer deletes it.  The order of
1577 the buffers in the list is based primarily on how recently each buffer
1578 has been displayed in the selected window.  Buffers move to the front
1579 of the list when they are selected and to the end when they are buried.
1580 Several functions, notably `other-buffer', use this ordering.  A
1581 buffer list displayed for the user also follows this order.
1582
1583    Every frame has its own order for the buffer list.  Switching to a
1584 new buffer inside of a particular frame changes the buffer list order
1585 for that frame, but does not affect the buffer list order of any other
1586 frames.  In addition, there is a global, non-frame buffer list order
1587 that is independent of the buffer list orders for any particular frame.
1588
1589    Note that the different buffer lists all contain the same elements.
1590 It is only the order of those elements that is different.
1591
1592  - Function: buffer-list &optional frame
1593      This function returns a list of all buffers, including those whose
1594      names begin with a space.  The elements are actual buffers, not
1595      their names.  The order of the list is specific to FRAME, which
1596      defaults to the current frame.  If FRAME is `t', the global,
1597      non-frame ordering is returned instead.
1598
1599           (buffer-list)
1600                => (#<buffer buffers.texi>
1601                    #<buffer  *Minibuf-1*> #<buffer buffer.c>
1602                    #<buffer *Help*> #<buffer TAGS>)
1603           
1604           ;; Note that the name of the minibuffer
1605           ;;   begins with a space!
1606           (mapcar (function buffer-name) (buffer-list))
1607               => ("buffers.texi" " *Minibuf-1*"
1608                   "buffer.c" "*Help*" "TAGS")
1609
1610      Buffers appear earlier in the list if they were current more
1611      recently.
1612
1613      This list is a copy of a list used inside XEmacs; modifying it has
1614      no effect on the buffers.
1615
1616  - Function: other-buffer &optional buffer-or-name frame visible-ok
1617      This function returns the first buffer in the buffer list other
1618      than BUFFER-OR-NAME, in FRAME's ordering for the buffer list.
1619      (FRAME defaults to the current frame.  If FRAME is `t', then the
1620      global, non-frame ordering is used.) Usually this is the buffer
1621      most recently shown in the selected window, aside from
1622      BUFFER-OR-NAME.  Buffers are moved to the front of the list when
1623      they are selected and to the end when they are buried.  Buffers
1624      whose names start with a space are not considered.
1625
1626      If BUFFER-OR-NAME is not supplied (or if it is not a buffer), then
1627      `other-buffer' returns the first buffer on the buffer list that is
1628      not visible in any window in a visible frame.
1629
1630      If the selected frame has a non-`nil' `buffer-predicate' property,
1631      then `other-buffer' uses that predicate to decide which buffers to
1632      consider.  It calls the predicate once for each buffer, and if the
1633      value is `nil', that buffer is ignored.  *Note X Frame
1634      Properties::.
1635
1636      If VISIBLE-OK is `nil', `other-buffer' avoids returning a buffer
1637      visible in any window on any visible frame, except as a last
1638      resort.   If VISIBLE-OK is non-`nil', then it does not matter
1639      whether a buffer is displayed somewhere or not.
1640
1641      If no suitable buffer exists, the buffer `*scratch*' is returned
1642      (and created, if necessary).
1643
1644      Note that in FSF Emacs 19, there is no FRAME argument, and
1645      VISIBLE-OK is the second argument instead of the third.
1646
1647  - Command: list-buffers &optional files-only
1648      This function displays a listing of the names of existing buffers.
1649      It clears the buffer `*Buffer List*', then inserts the listing
1650      into that buffer and displays it in a window.  `list-buffers' is
1651      intended for interactive use, and is described fully in `The XEmacs
1652      Reference Manual'.  It returns `nil'.
1653
1654  - Command: bury-buffer &optional buffer-or-name before
1655      This function puts BUFFER-OR-NAME at the end of the buffer list
1656      without changing the order of any of the other buffers on the list.
1657      This buffer therefore becomes the least desirable candidate for
1658      `other-buffer' to return.
1659
1660      If BUFFER-OR-NAME is `nil' or omitted, this means to bury the
1661      current buffer.  In addition, if the buffer is displayed in the
1662      selected window, this switches to some other buffer (obtained using
1663      `other-buffer') in the selected window.  But if the buffer is
1664      displayed in some other window, it remains displayed there.
1665
1666      If you wish to replace a buffer in all the windows that display
1667      it, use `replace-buffer-in-windows'.  *Note Buffers and Windows::.
1668
1669 \1f
1670 File: lispref.info,  Node: Creating Buffers,  Next: Killing Buffers,  Prev: The Buffer List,  Up: Buffers
1671
1672 Creating Buffers
1673 ================
1674
1675 This section describes the two primitives for creating buffers.
1676 `get-buffer-create' creates a buffer if it finds no existing buffer
1677 with the specified name; `generate-new-buffer' always creates a new
1678 buffer and gives it a unique name.
1679
1680    Other functions you can use to create buffers include
1681 `with-output-to-temp-buffer' (*note Temporary Displays::) and
1682 `create-file-buffer' (*note Visiting Files::).  Starting a subprocess
1683 can also create a buffer (*note Processes::).
1684
1685  - Function: get-buffer-create name
1686      This function returns a buffer named NAME.  It returns an existing
1687      buffer with that name, if one exists; otherwise, it creates a new
1688      buffer.  The buffer does not become the current buffer--this
1689      function does not change which buffer is current.
1690
1691      An error is signaled if NAME is not a string.
1692
1693           (get-buffer-create "foo")
1694                => #<buffer foo>
1695
1696      The major mode for the new buffer is set to Fundamental mode.  The
1697      variable `default-major-mode' is handled at a higher level.  *Note
1698      Auto Major Mode::.
1699
1700  - Function: generate-new-buffer name
1701      This function returns a newly created, empty buffer, but does not
1702      make it current.  If there is no buffer named NAME, then that is
1703      the name of the new buffer.  If that name is in use, this function
1704      adds suffixes of the form `<N>' to NAME, where N is an integer.
1705      It tries successive integers starting with 2 until it finds an
1706      available name.
1707
1708      An error is signaled if NAME is not a string.
1709
1710           (generate-new-buffer "bar")
1711                => #<buffer bar>
1712           (generate-new-buffer "bar")
1713                => #<buffer bar<2>>
1714           (generate-new-buffer "bar")
1715                => #<buffer bar<3>>
1716
1717      The major mode for the new buffer is set to Fundamental mode.  The
1718      variable `default-major-mode' is handled at a higher level.  *Note
1719      Auto Major Mode::.
1720
1721      See the related function `generate-new-buffer-name' in *Note
1722      Buffer Names::.
1723
1724 \1f
1725 File: lispref.info,  Node: Killing Buffers,  Next: Indirect Buffers,  Prev: Creating Buffers,  Up: Buffers
1726
1727 Killing Buffers
1728 ===============
1729
1730 "Killing a buffer" makes its name unknown to XEmacs and makes its text
1731 space available for other use.
1732
1733    The buffer object for the buffer that has been killed remains in
1734 existence as long as anything refers to it, but it is specially marked
1735 so that you cannot make it current or display it.  Killed buffers retain
1736 their identity, however; two distinct buffers, when killed, remain
1737 distinct according to `eq'.
1738
1739    If you kill a buffer that is current or displayed in a window, XEmacs
1740 automatically selects or displays some other buffer instead.  This means
1741 that killing a buffer can in general change the current buffer.
1742 Therefore, when you kill a buffer, you should also take the precautions
1743 associated with changing the current buffer (unless you happen to know
1744 that the buffer being killed isn't current).  *Note Current Buffer::.
1745
1746    If you kill a buffer that is the base buffer of one or more indirect
1747 buffers, the indirect buffers are automatically killed as well.
1748
1749    The `buffer-name' of a killed buffer is `nil'.  To test whether a
1750 buffer has been killed, you can either use this feature or the function
1751 `buffer-live-p'.
1752
1753  - Function: buffer-live-p object
1754      This function returns `t' if OBJECT is an editor buffer that has
1755      not been deleted, `nil' otherwise.
1756
1757  - Command: kill-buffer buffer-or-name
1758      This function kills the buffer BUFFER-OR-NAME, freeing all its
1759      memory for use as space for other buffers.  (Emacs version 18 and
1760      older was unable to return the memory to the operating system.)
1761      It returns `nil'.  The argument BUFFER-OR-NAME may be a buffer or
1762      the name of one.
1763
1764      Any processes that have this buffer as the `process-buffer' are
1765      sent the `SIGHUP' signal, which normally causes them to terminate.
1766      (The basic meaning of `SIGHUP' is that a dialup line has been
1767      disconnected.)  *Note Deleting Processes::.
1768
1769      If the buffer is visiting a file and contains unsaved changes,
1770      `kill-buffer' asks the user to confirm before the buffer is killed.
1771      It does this even if not called interactively.  To prevent the
1772      request for confirmation, clear the modified flag before calling
1773      `kill-buffer'.  *Note Buffer Modification::.
1774
1775      Killing a buffer that is already dead has no effect.
1776
1777           (kill-buffer "foo.unchanged")
1778                => nil
1779           (kill-buffer "foo.changed")
1780           
1781           ---------- Buffer: Minibuffer ----------
1782           Buffer foo.changed modified; kill anyway? (yes or no) yes
1783           ---------- Buffer: Minibuffer ----------
1784           
1785                => nil
1786
1787  - Variable: kill-buffer-query-functions
1788      After confirming unsaved changes, `kill-buffer' calls the functions
1789      in the list `kill-buffer-query-functions', in order of appearance,
1790      with no arguments.  The buffer being killed is the current buffer
1791      when they are called.  The idea is that these functions ask for
1792      confirmation from the user for various nonstandard reasons.  If
1793      any of them returns `nil', `kill-buffer' spares the buffer's life.
1794
1795  - Variable: kill-buffer-hook
1796      This is a normal hook run by `kill-buffer' after asking all the
1797      questions it is going to ask, just before actually killing the
1798      buffer.  The buffer to be killed is current when the hook
1799      functions run.  *Note Hooks::.
1800
1801  - Variable: buffer-offer-save
1802      This variable, if non-`nil' in a particular buffer, tells
1803      `save-buffers-kill-emacs' and `save-some-buffers' to offer to save
1804      that buffer, just as they offer to save file-visiting buffers.  The
1805      variable `buffer-offer-save' automatically becomes buffer-local
1806      when set for any reason.  *Note Buffer-Local Variables::.
1807
1808 \1f
1809 File: lispref.info,  Node: Indirect Buffers,  Prev: Killing Buffers,  Up: Buffers
1810
1811 Indirect Buffers
1812 ================
1813
1814 An "indirect buffer" shares the text of some other buffer, which is
1815 called the "base buffer" of the indirect buffer.  In some ways it is
1816 the analogue, for buffers, of a symbolic link among files.  The base
1817 buffer may not itself be an indirect buffer.  One base buffer may have
1818 several "indirect children".
1819
1820    The text of the indirect buffer is always identical to the text of
1821 its base buffer; changes made by editing either one are visible
1822 immediately in the other.
1823
1824    But in all other respects, the indirect buffer and its base buffer
1825 are completely separate.  They have different names, different values of
1826 point and mark, different narrowing, different markers and extents
1827 (though inserting or deleting text in either buffer relocates the
1828 markers and extents for both), different major modes, and different
1829 local variables.  Unlike in FSF Emacs, XEmacs indirect buffers do not
1830 automatically share text properties among themselves and their base
1831 buffer.
1832
1833    An indirect buffer cannot visit a file, but its base buffer can.  If
1834 you try to save the indirect buffer, that actually works by saving the
1835 base buffer.
1836
1837    Killing an indirect buffer has no effect on its base buffer.  Killing
1838 the base buffer kills all its indirect children.
1839
1840  - Command: make-indirect-buffer base-buffer name
1841      This creates an indirect buffer named NAME whose base buffer is
1842      BASE-BUFFER.  The argument BASE-BUFFER may be a buffer or a string.
1843
1844      If BASE-BUFFER is an indirect buffer, its base buffer is used as
1845      the base for the new buffer.
1846
1847           (make-indirect-buffer "*scratch*" "indirect")
1848                => #<buffer "indirect">
1849
1850  - Function: buffer-base-buffer &optional buffer
1851      This function returns the base buffer of BUFFER.  If BUFFER is not
1852      indirect, the value is `nil'.  Otherwise, the value is another
1853      buffer, which is never an indirect buffer.  If BUFFER is not
1854      supplied, it defaults to the current buffer.
1855
1856           (buffer-base-buffer (get-buffer "indirect"))
1857                => #<buffer "*scratch*">
1858
1859  - Function: buffer-indirect-children &optional buffer
1860      This function returns a list of all indirect buffers whose base
1861      buffer is BUFFER.  If BUFFER is indirect, the return value will
1862      always be `nil'; see `make-indirect-buffer'.  If BUFFER is not
1863      supplied, it defaults to the current buffer.
1864
1865           (buffer-indirect-children (get-buffer "*scratch*"))
1866                => (#<buffer "indirect">)
1867
1868 \1f
1869 File: lispref.info,  Node: Windows,  Next: Frames,  Prev: Buffers,  Up: Top
1870
1871 Windows
1872 *******
1873
1874 This chapter describes most of the functions and variables related to
1875 Emacs windows.  See *Note Display::, for information on how text is
1876 displayed in windows.
1877
1878 * Menu:
1879
1880 * Basic Windows::          Basic information on using windows.
1881 * Splitting Windows::      Splitting one window into two windows.
1882 * Deleting Windows::       Deleting a window gives its space to other windows.
1883 * Selecting Windows::      The selected window is the one that you edit in.
1884 * Cyclic Window Ordering:: Moving around the existing windows.
1885 * Buffers and Windows::    Each window displays the contents of a buffer.
1886 * Displaying Buffers::     Higher-lever functions for displaying a buffer
1887                              and choosing a window for it.
1888 * Choosing Window::        How to choose a window for displaying a buffer.
1889 * Window Point::           Each window has its own location of point.
1890 * Window Start::           The display-start position controls which text
1891                              is on-screen in the window.
1892 * Vertical Scrolling::     Moving text up and down in the window.
1893 * Horizontal Scrolling::   Moving text sideways on the window.
1894 * Size of Window::         Accessing the size of a window.
1895 * Position of Window::     Accessing the position of a window.
1896 * Resizing Windows::       Changing the size of a window.
1897 * Window Configurations::  Saving and restoring the state of the screen.
1898
1899 \1f
1900 File: lispref.info,  Node: Basic Windows,  Next: Splitting Windows,  Up: Windows
1901
1902 Basic Concepts of Emacs Windows
1903 ===============================
1904
1905 A "window" in XEmacs is the physical area of the screen in which a
1906 buffer is displayed.  The term is also used to refer to a Lisp object
1907 that represents that screen area in XEmacs Lisp.  It should be clear
1908 from the context which is meant.
1909
1910    XEmacs groups windows into frames.  A frame represents an area of
1911 screen available for XEmacs to use.  Each frame always contains at least
1912 one window, but you can subdivide it vertically or horizontally into
1913 multiple nonoverlapping Emacs windows.
1914
1915    In each frame, at any time, one and only one window is designated as
1916 "selected within the frame".  The frame's cursor appears in that
1917 window.  At ant time, one frame is the selected frame; and the window
1918 selected within that frame is "the selected window".  The selected
1919 window's buffer is usually the current buffer (except when `set-buffer'
1920 has been used).  *Note Current Buffer::.
1921
1922    For practical purposes, a window exists only while it is displayed in
1923 a frame.  Once removed from the frame, the window is effectively deleted
1924 and should not be used, _even though there may still be references to
1925 it_ from other Lisp objects.  Restoring a saved window configuration is
1926 the only way for a window no longer on the screen to come back to life.
1927 (*Note Deleting Windows::.)
1928
1929    Each window has the following attributes:
1930
1931    * containing frame
1932
1933    * window height
1934
1935    * window width
1936
1937    * window edges with respect to the frame or screen
1938
1939    * the buffer it displays
1940
1941    * position within the buffer at the upper left of the window
1942
1943    * amount of horizontal scrolling, in columns
1944
1945    * point
1946
1947    * the mark
1948
1949    * how recently the window was selected
1950
1951    Users create multiple windows so they can look at several buffers at
1952 once.  Lisp libraries use multiple windows for a variety of reasons, but
1953 most often to display related information.  In Rmail, for example, you
1954 can move through a summary buffer in one window while the other window
1955 shows messages one at a time as they are reached.
1956
1957    The meaning of "window" in XEmacs is similar to what it means in the
1958 context of general-purpose window systems such as X, but not identical.
1959 The X Window System places X windows on the screen; XEmacs uses one or
1960 more X windows as frames, and subdivides them into Emacs windows.  When
1961 you use XEmacs on a character-only terminal, XEmacs treats the whole
1962 terminal screen as one frame.
1963
1964    Most window systems support arbitrarily located overlapping windows.
1965 In contrast, Emacs windows are "tiled"; they never overlap, and
1966 together they fill the whole screen or frame.  Because of the way in
1967 which XEmacs creates new windows and resizes them, you can't create
1968 every conceivable tiling of windows on an Emacs frame.  *Note Splitting
1969 Windows::, and *Note Size of Window::.
1970
1971    *Note Display::, for information on how the contents of the window's
1972 buffer are displayed in the window.
1973
1974  - Function: windowp object
1975      This function returns `t' if OBJECT is a window.
1976
1977 \1f
1978 File: lispref.info,  Node: Splitting Windows,  Next: Deleting Windows,  Prev: Basic Windows,  Up: Windows
1979
1980 Splitting Windows
1981 =================
1982
1983 The functions described here are the primitives used to split a window
1984 into two windows.  Two higher level functions sometimes split a window,
1985 but not always: `pop-to-buffer' and `display-buffer' (*note Displaying
1986 Buffers::).
1987
1988    The functions described here do not accept a buffer as an argument.
1989 The two "halves" of the split window initially display the same buffer
1990 previously visible in the window that was split.
1991
1992  - Function: one-window-p &optional nomini which-frames which-devices
1993      This function returns non-`nil' if there is only one window.  The
1994      argument NOMINI, if non-`nil', means don't count the minibuffer
1995      even if it is active; otherwise, the minibuffer window is
1996      included, if active, in the total number of windows which is
1997      compared against one.
1998
1999      The remaining arguments controls which set of windows are counted,
2000      as with `next-window'.
2001
2002  - Command: split-window &optional window size horizontal
2003      This function splits WINDOW into two windows.  The original window
2004      WINDOW remains the selected window, but occupies only part of its
2005      former screen area.  The rest is occupied by a newly created
2006      window which is returned as the value of this function.
2007
2008      If HORIZONTAL is non-`nil', then WINDOW splits into two side by
2009      side windows.  The original window WINDOW keeps the leftmost SIZE
2010      columns, and gives the rest of the columns to the new window.
2011      Otherwise, it splits into windows one above the other, and WINDOW
2012      keeps the upper SIZE lines and gives the rest of the lines to the
2013      new window.  The original window is therefore the left-hand or
2014      upper of the two, and the new window is the right-hand or lower.
2015
2016      If WINDOW is omitted or `nil', then the selected window is split.
2017      If SIZE is omitted or `nil', then WINDOW is divided evenly into
2018      two parts.  (If there is an odd line, it is allocated to the new
2019      window.)  When `split-window' is called interactively, all its
2020      arguments are `nil'.
2021
2022      The following example starts with one window on a frame that is 50
2023      lines high by 80 columns wide; then the window is split.
2024
2025           (setq w (selected-window))
2026                => #<window 8 on windows.texi>
2027           (window-edges)          ; Edges in order:
2028                => (0 0 80 50)     ;   left-top-right-bottom
2029           
2030           ;; Returns window created
2031           (setq w2 (split-window w 15))
2032                => #<window 28 on windows.texi>
2033           (window-edges w2)
2034                => (0 15 80 50)    ; Bottom window;
2035                                   ;   top is line 15
2036           (window-edges w)
2037                => (0 0 80 15)     ; Top window
2038
2039      The frame looks like this:
2040
2041                    __________
2042                   |          |  line 0
2043                   |    w     |
2044                   |__________|
2045                   |          |  line 15
2046                   |    w2    |
2047                   |__________|
2048                                 line 50
2049            column 0   column 80
2050
2051      Next, the top window is split horizontally:
2052
2053           (setq w3 (split-window w 35 t))
2054                => #<window 32 on windows.texi>
2055           (window-edges w3)
2056                => (35 0 80 15)  ; Left edge at column 35
2057           (window-edges w)
2058                => (0 0 35 15)   ; Right edge at column 35
2059           (window-edges w2)
2060                => (0 15 80 50)  ; Bottom window unchanged
2061
2062      Now, the screen looks like this:
2063
2064                column 35
2065                    __________
2066                   |   |      |  line 0
2067                   | w |  w3  |
2068                   |___|______|
2069                   |          |  line 15
2070                   |    w2    |
2071                   |__________|
2072                                 line 50
2073            column 0   column 80
2074
2075      Normally, Emacs indicates the border between two side-by-side
2076      windows with a scroll bar (*note Scroll Bars: X Frame Properties.)
2077      or `|' characters.  The display table can specify alternative
2078      border characters; see *Note Display Tables::.
2079
2080  - Command: split-window-vertically &optional size
2081      This function splits the selected window into two windows, one
2082      above the other, leaving the selected window with SIZE lines.
2083
2084      This function is simply an interface to `split-window'.  Here is
2085      the complete function definition for it:
2086
2087           (defun split-window-vertically (&optional arg)
2088             "Split current window into two windows, one above the other."
2089             (interactive "P")
2090             (split-window nil (and arg (prefix-numeric-value arg))))
2091
2092  - Command: split-window-horizontally &optional size
2093      This function splits the selected window into two windows
2094      side-by-side, leaving the selected window with SIZE columns.
2095
2096      This function is simply an interface to `split-window'.  Here is
2097      the complete definition for `split-window-horizontally' (except for
2098      part of the documentation string):
2099
2100           (defun split-window-horizontally (&optional arg)
2101             "Split selected window into two windows, side by side..."
2102             (interactive "P")
2103             (split-window nil (and arg (prefix-numeric-value arg)) t))
2104
2105 \1f
2106 File: lispref.info,  Node: Deleting Windows,  Next: Selecting Windows,  Prev: Splitting Windows,  Up: Windows
2107
2108 Deleting Windows
2109 ================
2110
2111 A window remains visible on its frame unless you "delete" it by calling
2112 certain functions that delete windows.  A deleted window cannot appear
2113 on the screen, but continues to exist as a Lisp object until there are
2114 no references to it.  There is no way to cancel the deletion of a
2115 window aside from restoring a saved window configuration (*note Window
2116 Configurations::).  Restoring a window configuration also deletes any
2117 windows that aren't part of that configuration.
2118
2119    When you delete a window, the space it took up is given to one
2120 adjacent sibling.  (In Emacs version 18, the space was divided evenly
2121 among all the siblings.)
2122
2123  - Function: window-live-p window
2124      This function returns `nil' if WINDOW is deleted, and `t'
2125      otherwise.
2126
2127      *Warning:* Erroneous information or fatal errors may result from
2128      using a deleted window as if it were live.
2129
2130  - Command: delete-window &optional window force
2131      This function removes WINDOW from the display.  If WINDOW is
2132      omitted, then the selected window is deleted. If window is the
2133      only one on its frame, the frame is deleted as well.
2134
2135      Normally, you cannot delete the last non-minibuffer-only frame
2136      (you must use `save-buffers-kill-emacs' or `kill-emacs'); an error
2137      is signaled instead.  However, if optional second argument FORCE is
2138      non-`nil', you can delete the last frame. (This will automatically
2139      call `save-buffers-kill-emacs'.)
2140
2141      This function returns `nil'.
2142
2143      When `delete-window' is called interactively, the selected window
2144      is deleted.
2145
2146  - Command: delete-other-windows &optional window
2147      This function makes WINDOW the only window on its frame, by
2148      deleting the other windows in that frame.  If WINDOW is omitted or
2149      `nil', then the selected window is used by default.
2150
2151      The result is `nil'.
2152
2153  - Command: delete-windows-on buffer &optional which-frames
2154           which-devices
2155      This function deletes all windows showing BUFFER.  If there are no
2156      windows showing BUFFER, it does nothing.
2157
2158      `delete-windows-on' operates frame by frame.  If a frame has
2159      several windows showing different buffers, then those showing
2160      BUFFER are removed, and the others expand to fill the space.  If
2161      all windows in some frame are showing BUFFER (including the case
2162      where there is only one window), then the frame reverts to having a
2163      single window showing another buffer chosen with `other-buffer'.
2164      *Note The Buffer List::.
2165
2166      The argument WHICH-FRAMES controls which frames to operate on:
2167
2168     `nil'
2169           Delete all windows showing BUFFER in any frame.
2170
2171     `t'
2172           Delete only windows showing BUFFER in the selected frame.
2173
2174     `visible'
2175           Delete all windows showing BUFFER in any visible frame.
2176
2177     `0'
2178           Delete all windows showing BUFFER in any visible frame.
2179
2180     FRAME
2181           If it is a frame, delete all windows showing BUFFER in that
2182           frame.
2183
2184      *Warning:* This is similar to, but not identical to, the meaning
2185      of the WHICH-FRAMES argument to `next-window'; the meanings of
2186      `nil' and `t' are reversed.
2187
2188      The optional argument WHICH-DEVICES further clarifies on which
2189      devices to search for frames as specified by WHICH-FRAMES.  This
2190      value is only meaningful if WHICH-FRAMES is not `t'.
2191
2192     `nil'
2193           Consider all devices on the selected console.
2194
2195     DEVICE
2196           Consider only the one device DEVICE.
2197
2198     CONSOLE
2199           Consider all devices on CONSOLE.
2200
2201     DEVICE-TYPE
2202           Consider all devices with device type DEVICE-TYPE.
2203
2204     `window-system'
2205           Consider all devices on window system consoles.
2206
2207     anything else
2208           Consider all devices without restriction.
2209
2210      This function always returns `nil'.
2211
2212 \1f
2213 File: lispref.info,  Node: Selecting Windows,  Next: Cyclic Window Ordering,  Prev: Deleting Windows,  Up: Windows
2214
2215 Selecting Windows
2216 =================
2217
2218 When a window is selected, the buffer in the window becomes the current
2219 buffer, and the cursor will appear in it.
2220
2221  - Function: selected-window &optional device
2222      This function returns the selected window.  This is the window in
2223      which the cursor appears and to which many commands apply.  Each
2224      separate device can have its own selected window, which is
2225      remembered as focus changes from device to device.  Optional
2226      argument DEVICE specifies which device to return the selected
2227      window for, and defaults to the selected device.
2228
2229  - Function: select-window window &optional norecord
2230      This function makes WINDOW the selected window.  The cursor then
2231      appears in WINDOW (on redisplay).  The buffer being displayed in
2232      WINDOW is immediately designated the current buffer.
2233
2234      If optional argument NORECORD is non-`nil' then the global and
2235      per-frame buffer orderings are not modified, as by the function
2236      `record-buffer'.
2237
2238      The return value is WINDOW.
2239
2240           (setq w (next-window))
2241           (select-window w)
2242                => #<window 65 on windows.texi>
2243
2244  - Special Form: save-selected-window forms...
2245      This special form records the selected window, executes FORMS in
2246      sequence, then restores the earlier selected window.  It does not
2247      save or restore anything about the sizes, arrangement or contents
2248      of windows; therefore, if the FORMS change them, the changes are
2249      permanent.
2250
2251    The following functions choose one of the windows on the screen,
2252 offering various criteria for the choice.
2253
2254  - Function: get-lru-window &optional which-frames which-devices
2255      This function returns the window least recently "used" (that is,
2256      selected).  The selected window is always the most recently used
2257      window.
2258
2259      The selected window can be the least recently used window if it is
2260      the only window.  A newly created window becomes the least
2261      recently used window until it is selected.  A minibuffer window is
2262      never a candidate.
2263
2264      By default, only the windows in the selected frame are considered.
2265      The optional argument WHICH-FRAMES changes this behavior.  Here
2266      are the possible values and their meanings:
2267
2268     `nil'
2269           Consider all the windows in the selected windows's frame,
2270           plus the minibuffer used by that frame even if it lies in
2271           some other frame.
2272
2273     `t'
2274           Consider all windows in all existing frames.
2275
2276     `visible'
2277           Consider all windows in all visible frames.  (To get useful
2278           results, you must ensure WINDOW is in a visible frame.)
2279
2280     `0'
2281           Consider all windows in all visible or iconified frames.
2282
2283     FRAME
2284           Consider all windows on frame FRAME.
2285
2286     anything else
2287           Consider precisely the windows in the selected window's
2288           frame, and no others.
2289
2290      The optional argument WHICH-DEVICES further clarifies on which
2291      devices to search for frames as specified by WHICH-FRAMES.  This
2292      value is only meaningful if WHICH-FRAMES is non-`nil'.
2293
2294     `nil'
2295           Consider all devices on the selected console.
2296
2297     DEVICE
2298           Consider only the one device DEVICE.
2299
2300     CONSOLE
2301           Consider all devices on CONSOLE.
2302
2303     DEVICE-TYPE
2304           Consider all devices with device type DEVICE-TYPE.
2305
2306     `window-system'
2307           Consider all devices on window system consoles.
2308
2309     anything else
2310           Consider all devices without restriction.
2311
2312
2313  - Function: get-largest-window &optional which-frames which-devices
2314      This function returns the window with the largest area (height
2315      times width).  If there are no side-by-side windows, then this is
2316      the window with the most lines.  A minibuffer window is never a
2317      candidate.
2318
2319      If there are two windows of the same size, then the function
2320      returns the window that is first in the cyclic ordering of windows
2321      (see following section), starting from the selected window.
2322
2323      The remaining arguments control which set of windows are
2324      considered.  See `next-window', above.
2325
2326 \1f
2327 File: lispref.info,  Node: Cyclic Window Ordering,  Next: Buffers and Windows,  Prev: Selecting Windows,  Up: Windows
2328
2329 Cyclic Ordering of Windows
2330 ==========================
2331
2332 When you use the command `C-x o' (`other-window') to select the next
2333 window, it moves through all the windows on the screen in a specific
2334 cyclic order.  For any given configuration of windows, this order never
2335 varies.  It is called the "cyclic ordering of windows".
2336
2337    This ordering generally goes from top to bottom, and from left to
2338 right.  But it may go down first or go right first, depending on the
2339 order in which the windows were split.
2340
2341    If the first split was vertical (into windows one above each other),
2342 and then the subwindows were split horizontally, then the ordering is
2343 left to right in the top of the frame, and then left to right in the
2344 next lower part of the frame, and so on.  If the first split was
2345 horizontal, the ordering is top to bottom in the left part, and so on.
2346 In general, within each set of siblings at any level in the window tree,
2347 the order is left to right, or top to bottom.
2348
2349  - Function: next-window &optional window minibuf which-frames
2350           which-devices
2351      This function returns the window following WINDOW in the cyclic
2352      ordering of windows.  This is the window that `C-x o' would select
2353      if typed when WINDOW is selected.  If WINDOW is the only window
2354      visible, then this function returns WINDOW.  If omitted, WINDOW
2355      defaults to the selected window.
2356
2357      The value of the argument MINIBUF determines whether the
2358      minibuffer is included in the window order.  Normally, when
2359      MINIBUF is `nil', the minibuffer is included if it is currently
2360      active; this is the behavior of `C-x o'.  (The minibuffer window
2361      is active while the minibuffer is in use.  *Note Minibuffers::.)
2362
2363      If MINIBUF is `t', then the cyclic ordering includes the
2364      minibuffer window even if it is not active.
2365
2366      If MINIBUF is neither `t' nor `nil', then the minibuffer window is
2367      not included even if it is active.
2368
2369      By default, only the windows in the selected frame are considered.
2370      The optional argument WHICH-FRAMES changes this behavior.  Here
2371      are the possible values and their meanings:
2372
2373     `nil'
2374           Consider all the windows in WINDOW's frame, plus the
2375           minibuffer used by that frame even if it lies in some other
2376           frame.
2377
2378     `t'
2379           Consider all windows in all existing frames.
2380
2381     `visible'
2382           Consider all windows in all visible frames.  (To get useful
2383           results, you must ensure WINDOW is in a visible frame.)
2384
2385     `0'
2386           Consider all windows in all visible or iconified frames.
2387
2388     FRAME
2389           Consider all windows on frame FRAME.
2390
2391     anything else
2392           Consider precisely the windows in WINDOW's frame, and no
2393           others.
2394
2395      The optional argument WHICH-DEVICES further clarifies on which
2396      devices to search for frames as specified by WHICH-FRAMES.  This
2397      value is only meaningful if WHICH-FRAMES is non-`nil'.
2398
2399     `nil'
2400           Consider all devices on the selected console.
2401
2402     DEVICE
2403           Consider only the one device DEVICE.
2404
2405     CONSOLE
2406           Consider all devices on CONSOLE.
2407
2408     DEVICE-TYPE
2409           Consider all devices with device type DEVICE-TYPE.
2410
2411     `window-system'
2412           Consider all devices on window system consoles.
2413
2414     anything else
2415           Consider all devices without restriction.
2416
2417      If you use consistent values for MINIBUF, WHICH-FRAMES, and
2418      WHICH-DEVICES, you can use `next-window' to iterate through the
2419      entire cycle of acceptable windows, eventually ending up back at
2420      the window you started with.  `previous-window' traverses the same
2421      cycle, in the reverse order.
2422
2423      This example assumes there are two windows, both displaying the
2424      buffer `windows.texi':
2425
2426           (selected-window)
2427                => #<window 56 on windows.texi>
2428           (next-window (selected-window))
2429                => #<window 52 on windows.texi>
2430           (next-window (next-window (selected-window)))
2431                => #<window 56 on windows.texi>
2432
2433  - Function: previous-window &optional window minibuf which-frames
2434           which-devices
2435      This function returns the window preceding WINDOW in the cyclic
2436      ordering of windows.  The other arguments specify which windows to
2437      include in the cycle, as in `next-window'.
2438
2439  - Command: other-window count &optional which-frames which-devices
2440      This function selects the COUNTth following window in the cyclic
2441      order.  If COUNT is negative, then it selects the -COUNTth
2442      preceding window.  It returns `nil'.
2443
2444      In an interactive call, COUNT is the numeric prefix argument.
2445
2446      The other arguments specify which windows to include in the cycle,
2447      as in `next-window'.
2448
2449  - Function: walk-windows function &optional minibuf which-frames
2450           which-devices
2451      This function cycles through all windows, calling `function' once
2452      for each window with the window as its sole argument.
2453
2454      The other arguments specify which windows to cycle through, as in
2455      `next-window'.
2456
2457 \1f
2458 File: lispref.info,  Node: Buffers and Windows,  Next: Displaying Buffers,  Prev: Cyclic Window Ordering,  Up: Windows
2459
2460 Buffers and Windows
2461 ===================
2462
2463 This section describes low-level functions to examine windows or to
2464 display buffers in windows in a precisely controlled fashion.  *Note
2465 Displaying Buffers::, for related functions that find a window to use
2466 and specify a buffer for it.  The functions described there are easier
2467 to use than these, but they employ heuristics in choosing or creating a
2468 window; use these functions when you need complete control.
2469
2470  - Function: set-window-buffer window buffer-or-name &optional norecord
2471      This function makes WINDOW display BUFFER-OR-NAME as its contents.
2472      BUFFER-OR-NAME can be a buffer or a buffer name.
2473
2474      With non-`nil' optional argument NORECORD, do not modify the
2475      global or per-frame buffer ordering.
2476
2477      This function returns `nil'.
2478
2479           (set-window-buffer (selected-window) "foo")
2480                => nil
2481
2482  - Function: window-buffer &optional window
2483      This function returns the buffer that WINDOW is displaying.  If
2484      WINDOW is omitted, this function returns the buffer for the
2485      selected window.
2486
2487           (window-buffer)
2488                => #<buffer windows.texi>
2489
2490  - Function: get-buffer-window buffer-or-name &optional which-frames
2491           which-devices
2492      This function returns a window currently displaying
2493      BUFFER-OR-NAME, or `nil' if there is none.  If there are several
2494      such windows, then the function returns the first one in the
2495      cyclic ordering of windows, starting from the selected window.
2496      *Note Cyclic Window Ordering::.
2497
2498      The remaining arguments control which windows to consider.  They
2499      have the same meaning as for `next-window'.
2500
2501 \1f
2502 File: lispref.info,  Node: Displaying Buffers,  Next: Choosing Window,  Prev: Buffers and Windows,  Up: Windows
2503
2504 Displaying Buffers in Windows
2505 =============================
2506
2507 In this section we describe convenient functions that choose a window
2508 automatically and use it to display a specified buffer.  These functions
2509 can also split an existing window in certain circumstances.  We also
2510 describe variables that parameterize the heuristics used for choosing a
2511 window.  *Note Buffers and Windows::, for low-level functions that give
2512 you more precise control.
2513
2514    Do not use the functions in this section in order to make a buffer
2515 current so that a Lisp program can access or modify it; they are too
2516 drastic for that purpose, since they change the display of buffers in
2517 windows, which is gratuitous and will surprise the user.  Instead, use
2518 `set-buffer' (*note Current Buffer::) and `save-excursion' (*note
2519 Excursions::), which designate buffers as current for programmed access
2520 without affecting the display of buffers in windows.
2521
2522  - Command: switch-to-buffer buffer-or-name &optional norecord
2523      This function makes BUFFER-OR-NAME the current buffer, and also
2524      displays the buffer in the selected window.  This means that a
2525      human can see the buffer and subsequent keyboard commands will
2526      apply to it.  Contrast this with `set-buffer', which makes
2527      BUFFER-OR-NAME the current buffer but does not display it in the
2528      selected window.  *Note Current Buffer::.
2529
2530      If BUFFER-OR-NAME does not identify an existing buffer, then a new
2531      buffer by that name is created.  The major mode for the new buffer
2532      is set according to the variable `default-major-mode'.  *Note Auto
2533      Major Mode::.
2534
2535      Normally the specified buffer is put at the front of the buffer
2536      list.  This affects the operation of `other-buffer'.  However, if
2537      NORECORD is non-`nil', this is not done.  *Note The Buffer List::.
2538
2539      The `switch-to-buffer' function is often used interactively, as
2540      the binding of `C-x b'.  It is also used frequently in programs.
2541      It always returns `nil'.
2542
2543  - Command: switch-to-buffer-other-window buffer-or-name
2544      This function makes BUFFER-OR-NAME the current buffer and displays
2545      it in a window not currently selected.  It then selects that
2546      window.  The handling of the buffer is the same as in
2547      `switch-to-buffer'.
2548
2549      The currently selected window is absolutely never used to do the
2550      job.  If it is the only window, then it is split to make a
2551      distinct window for this purpose.  If the selected window is
2552      already displaying the buffer, then it continues to do so, but
2553      another window is nonetheless found to display it in as well.
2554
2555  - Function: pop-to-buffer buffer-or-name &optional other-window
2556           on-frame
2557      This function makes BUFFER-OR-NAME the current buffer and switches
2558      to it in some window, preferably not the window previously
2559      selected.  The "popped-to" window becomes the selected window
2560      within its frame.
2561
2562      If the variable `pop-up-frames' is non-`nil', `pop-to-buffer'
2563      looks for a window in any visible frame already displaying the
2564      buffer; if there is one, it returns that window and makes it be
2565      selected within its frame.  If there is none, it creates a new
2566      frame and displays the buffer in it.
2567
2568      If `pop-up-frames' is `nil', then `pop-to-buffer' operates
2569      entirely within the selected frame.  (If the selected frame has
2570      just a minibuffer, `pop-to-buffer' operates within the most
2571      recently selected frame that was not just a minibuffer.)
2572
2573      If the variable `pop-up-windows' is non-`nil', windows may be
2574      split to create a new window that is different from the original
2575      window.  For details, see *Note Choosing Window::.
2576
2577      If OTHER-WINDOW is non-`nil', `pop-to-buffer' finds or creates
2578      another window even if BUFFER-OR-NAME is already visible in the
2579      selected window.  Thus BUFFER-OR-NAME could end up displayed in
2580      two windows.  On the other hand, if BUFFER-OR-NAME is already
2581      displayed in the selected window and OTHER-WINDOW is `nil', then
2582      the selected window is considered sufficient display for
2583      BUFFER-OR-NAME, so that nothing needs to be done.
2584
2585      All the variables that affect `display-buffer' affect
2586      `pop-to-buffer' as well.  *Note Choosing Window::.
2587
2588      If BUFFER-OR-NAME is a string that does not name an existing
2589      buffer, a buffer by that name is created.  The major mode for the
2590      new buffer is set according to the variable `default-major-mode'.
2591      *Note Auto Major Mode::.
2592
2593      If ON-FRAME is non-`nil', it is the frame to pop to this buffer on.
2594
2595      An example use of this function is found at the end of *Note
2596      Filter Functions::.
2597
2598  - Command: replace-buffer-in-windows buffer &optional which-frames
2599           which-devices
2600      This function replaces BUFFER with some other buffer in all
2601      windows displaying it.  The other buffer used is chosen with
2602      `other-buffer'.  In the usual applications of this function, you
2603      don't care which other buffer is used; you just want to make sure
2604      that BUFFER is no longer displayed.
2605
2606      The optional arguments WHICH-FRAMES and WHICH-DEVICES have the
2607      same meaning as with `delete-windows-on'.
2608
2609      This function returns `nil'.
2610
2611 \1f
2612 File: lispref.info,  Node: Choosing Window,  Next: Window Point,  Prev: Displaying Buffers,  Up: Windows
2613
2614 Choosing a Window for Display
2615 =============================
2616
2617 This section describes the basic facility that chooses a window to
2618 display a buffer in--`display-buffer'.  All the higher-level functions
2619 and commands use this subroutine.  Here we describe how to use
2620 `display-buffer' and how to customize it.
2621
2622  - Command: display-buffer buffer-or-name &optional not-this-window
2623           override-frame
2624      This command makes BUFFER-OR-NAME appear in some window, like
2625      `pop-to-buffer', but it does not select that window and does not
2626      make the buffer current.  The identity of the selected window is
2627      unaltered by this function.
2628
2629      BUFFER-OR-NAME can be a buffer or the name of one.
2630
2631      If NOT-THIS-WINDOW is non-`nil', it means to display the specified
2632      buffer in a window other than the selected one, even if it is
2633      already on display in the selected window.  This can cause the
2634      buffer to appear in two windows at once.  Otherwise, if
2635      BUFFER-OR-NAME is already being displayed in any window, that is
2636      good enough, so this function does nothing.
2637
2638      If OVERRIDE-FRAME is non-`nil', display on that frame instead of
2639      the current frame (or the dedicated frame).
2640
2641      `display-buffer' returns the window chosen to display
2642      BUFFER-OR-NAME.
2643
2644      Precisely how `display-buffer' finds or creates a window depends on
2645      the variables described below.
2646
2647    A window can be marked as "dedicated" to a particular buffer.  Then
2648 XEmacs will not automatically change which buffer appears in the
2649 window, such as `display-buffer' might normally do.
2650
2651  - Function: window-dedicated-p window
2652      This function returns WINDOW's dedicated object, usually `t' or
2653      `nil'.
2654
2655  - Function: set-window-buffer-dedicated window buffer
2656      This function makes WINDOW display BUFFER and be dedicated to that
2657      buffer.  Then XEmacs will not automatically change which buffer
2658      appears in WINDOW.  If BUFFER is `nil', this function makes WINDOW
2659      not be dedicated (but doesn't change which buffer appears in it
2660      currently).
2661
2662  - User Option: pop-up-windows
2663      This variable controls whether `display-buffer' makes new windows.
2664      If it is non-`nil' and there is only one window, then that window
2665      is split.  If it is `nil', then `display-buffer' does not split
2666      the single window, but uses it whole.
2667
2668  - User Option: split-height-threshold
2669      This variable determines when `display-buffer' may split a window,
2670      if there are multiple windows.  `display-buffer' always splits the
2671      largest window if it has at least this many lines.  If the largest
2672      window is not this tall, it is split only if it is the sole window
2673      and `pop-up-windows' is non-`nil'.
2674
2675  - User Option: pop-up-frames
2676      This variable controls whether `display-buffer' makes new frames.
2677      If it is non-`nil', `display-buffer' looks for an existing window
2678      already displaying the desired buffer, on any visible frame.  If
2679      it finds one, it returns that window.  Otherwise it makes a new
2680      frame.  The variables `pop-up-windows' and
2681      `split-height-threshold' do not matter if `pop-up-frames' is
2682      non-`nil'.
2683
2684      If `pop-up-frames' is `nil', then `display-buffer' either splits a
2685      window or reuses one.
2686
2687      *Note Frames::, for more information.
2688
2689  - Variable: pop-up-frame-function
2690      This variable specifies how to make a new frame if `pop-up-frames'
2691      is non-`nil'.
2692
2693      Its value should be a function of no arguments.  When
2694      `display-buffer' makes a new frame, it does so by calling that
2695      function, which should return a frame.  The default value of the
2696      variable is a function that creates a frame using properties from
2697      `pop-up-frame-plist'.
2698
2699  - Variable: pop-up-frame-plist
2700      This variable holds a plist specifying frame properties used when
2701      `display-buffer' makes a new frame.  *Note Frame Properties::, for
2702      more information about frame properties.
2703
2704  - Variable: special-display-buffer-names
2705      A list of buffer names for buffers that should be displayed
2706      specially.  If the buffer's name is in this list, `display-buffer'
2707      handles the buffer specially.
2708
2709      By default, special display means to give the buffer a dedicated
2710      frame.
2711
2712      If an element is a list, instead of a string, then the CAR of the
2713      list is the buffer name, and the rest of the list says how to
2714      create the frame.  There are two possibilities for the rest of the
2715      list.  It can be a plist, specifying frame properties, or it can
2716      contain a function and arguments to give to it.  (The function's
2717      first argument is always the buffer to be displayed; the arguments
2718      from the list come after that.)
2719
2720  - Variable: special-display-regexps
2721      A list of regular expressions that specify buffers that should be
2722      displayed specially.  If the buffer's name matches any of the
2723      regular expressions in this list, `display-buffer' handles the
2724      buffer specially.
2725
2726      By default, special display means to give the buffer a dedicated
2727      frame.
2728
2729      If an element is a list, instead of a string, then the CAR of the
2730      list is the regular expression, and the rest of the list says how
2731      to create the frame.  See above, under
2732      `special-display-buffer-names'.
2733
2734  - Variable: special-display-function
2735      This variable holds the function to call to display a buffer
2736      specially.  It receives the buffer as an argument, and should
2737      return the window in which it is displayed.
2738
2739      The default value of this variable is
2740      `special-display-popup-frame'.
2741
2742  - Function: special-display-popup-frame buffer
2743      This function makes BUFFER visible in a frame of its own.  If
2744      BUFFER is already displayed in a window in some frame, it makes
2745      the frame visible and raises it, to use that window.  Otherwise, it
2746      creates a frame that will be dedicated to BUFFER.
2747
2748      This function uses an existing window displaying BUFFER whether or
2749      not it is in a frame of its own; but if you set up the above
2750      variables in your init file, before BUFFER was created, then
2751      presumably the window was previously made by this function.
2752
2753  - User Option: special-display-frame-plist
2754      This variable holds frame properties for
2755      `special-display-popup-frame' to use when it creates a frame.
2756
2757  - Variable: same-window-buffer-names
2758      A list of buffer names for buffers that should be displayed in the
2759      selected window.  If the buffer's name is in this list,
2760      `display-buffer' handles the buffer by switching to it in the
2761      selected window.
2762
2763  - Variable: same-window-regexps
2764      A list of regular expressions that specify buffers that should be
2765      displayed in the selected window.  If the buffer's name matches
2766      any of the regular expressions in this list, `display-buffer'
2767      handles the buffer by switching to it in the selected window.
2768
2769  - Variable: display-buffer-function
2770      This variable is the most flexible way to customize the behavior of
2771      `display-buffer'.  If it is non-`nil', it should be a function
2772      that `display-buffer' calls to do the work.  The function should
2773      accept two arguments, the same two arguments that `display-buffer'
2774      received.  It should choose or create a window, display the
2775      specified buffer, and then return the window.
2776
2777      This hook takes precedence over all the other options and hooks
2778      described above.
2779
2780    A window can be marked as "dedicated" to its buffer.  Then
2781 `display-buffer' does not try to use that window.
2782
2783  - Function: window-dedicated-p window
2784      This function returns `t' if WINDOW is marked as dedicated;
2785      otherwise `nil'.
2786
2787  - Function: set-window-dedicated-p window flag
2788      This function marks WINDOW as dedicated if FLAG is non-`nil', and
2789      nondedicated otherwise.
2790
2791 \1f
2792 File: lispref.info,  Node: Window Point,  Next: Window Start,  Prev: Choosing Window,  Up: Windows
2793
2794 Windows and Point
2795 =================
2796
2797 Each window has its own value of point, independent of the value of
2798 point in other windows displaying the same buffer.  This makes it useful
2799 to have multiple windows showing one buffer.
2800
2801    * The window point is established when a window is first created; it
2802      is initialized from the buffer's point, or from the window point
2803      of another window opened on the buffer if such a window exists.
2804
2805    * Selecting a window sets the value of point in its buffer to the
2806      window's value of point.  Conversely, deselecting a window sets
2807      the window's value of point from that of the buffer.  Thus, when
2808      you switch between windows that display a given buffer, the point
2809      value for the selected window is in effect in the buffer, while
2810      the point values for the other windows are stored in those windows.
2811
2812    * As long as the selected window displays the current buffer, the
2813      window's point and the buffer's point always move together; they
2814      remain equal.
2815
2816    * *Note Positions::, for more details on buffer positions.
2817
2818    As far as the user is concerned, point is where the cursor is, and
2819 when the user switches to another buffer, the cursor jumps to the
2820 position of point in that buffer.
2821
2822  - Function: window-point &optional window
2823      This function returns the current position of point in WINDOW.
2824      For a non-selected window, this is the value point would have (in
2825      that window's buffer) if that window were selected.
2826
2827      When WINDOW is the selected window and its buffer is also the
2828      current buffer, the value returned is the same as the value of
2829      point in that buffer.
2830
2831      Strictly speaking, it would be more correct to return the
2832      "top-level" value of point, outside of any `save-excursion' forms.
2833      But that value is hard to find.
2834
2835  - Function: set-window-point window position
2836      This function positions point in WINDOW at position POSITION in
2837      WINDOW's buffer.
2838
2839 \1f
2840 File: lispref.info,  Node: Window Start,  Next: Vertical Scrolling,  Prev: Window Point,  Up: Windows
2841
2842 The Window Start Position
2843 =========================
2844
2845 Each window contains a marker used to keep track of a buffer position
2846 that specifies where in the buffer display should start.  This position
2847 is called the "display-start" position of the window (or just the
2848 "start").  The character after this position is the one that appears at
2849 the upper left corner of the window.  It is usually, but not
2850 inevitably, at the beginning of a text line.
2851
2852  - Function: window-start &optional window
2853      This function returns the display-start position of window WINDOW.
2854      If WINDOW is `nil', the selected window is used.  For example,
2855
2856           (window-start)
2857                => 7058
2858
2859      When you create a window, or display a different buffer in it, the
2860      display-start position is set to a display-start position recently
2861      used for the same buffer, or 1 if the buffer doesn't have any.
2862
2863      For a realistic example, see the description of `count-lines' in
2864      *Note Text Lines::.
2865
2866  - Function: window-end &optional window guarantee
2867      This function returns the position of the end of the display in
2868      window WINDOW.  If WINDOW is `nil', the selected window is used.
2869
2870      Simply changing the buffer text or setting `window-start' does not
2871      update the value that `window-end' returns.  The value is updated
2872      only when Emacs redisplays and redisplay actually finishes.
2873
2874      If the last redisplay of WINDOW was preempted, and did not finish,
2875      Emacs does not know the position of the end of display in that
2876      window.  In that case, this function returns a value that is not
2877      correct.  In a future version, `window-end' will return `nil' in
2878      that case.
2879
2880      If optional arg GUARANTEE is non-`nil', the return value is
2881      guaranteed to be the same as `window-end' would return at the end
2882      of the next full redisplay assuming nothing else changes in the
2883      meantime.  This function is potentially much slower with this flag
2884      set.
2885
2886
2887  - Function: set-window-start window position &optional noforce
2888      This function sets the display-start position of WINDOW to
2889      POSITION in WINDOW's buffer.  It returns POSITION.
2890
2891      The display routines insist that the position of point be visible
2892      when a buffer is displayed.  Normally, they change the
2893      display-start position (that is, scroll the window) whenever
2894      necessary to make point visible.  However, if you specify the
2895      start position with this function using `nil' for NOFORCE, it
2896      means you want display to start at POSITION even if that would put
2897      the location of point off the screen.  If this does place point
2898      off screen, the display routines move point to the left margin on
2899      the middle line in the window.
2900
2901      For example, if point is 1 and you set the start of the window
2902      to 2, then point would be "above" the top of the window.  The
2903      display routines will automatically move point if it is still 1
2904      when redisplay occurs.  Here is an example:
2905
2906           ;; Here is what `foo' looks like before executing
2907           ;;   the `set-window-start' expression.
2908           
2909           ---------- Buffer: foo ----------
2910           -!-This is the contents of buffer foo.
2911           2
2912           3
2913           4
2914           5
2915           6
2916           ---------- Buffer: foo ----------
2917           
2918           (set-window-start
2919            (selected-window)
2920            (1+ (window-start)))
2921           => 2
2922           
2923           ;; Here is what `foo' looks like after executing
2924           ;;   the `set-window-start' expression.
2925           ---------- Buffer: foo ----------
2926           his is the contents of buffer foo.
2927           2
2928           3
2929           -!-4
2930           5
2931           6
2932           ---------- Buffer: foo ----------
2933
2934      If NOFORCE is non-`nil', and POSITION would place point off screen
2935      at the next redisplay, then redisplay computes a new window-start
2936      position that works well with point, and thus POSITION is not used.
2937
2938  - Function: pos-visible-in-window-p &optional position window
2939      This function returns `t' if POSITION is within the range of text
2940      currently visible on the screen in WINDOW.  It returns `nil' if
2941      POSITION is scrolled vertically out of view.  The argument
2942      POSITION defaults to the current position of point; WINDOW, to the
2943      selected window.  Here is an example:
2944
2945           (or (pos-visible-in-window-p
2946                (point) (selected-window))
2947               (recenter 0))
2948
2949      The `pos-visible-in-window-p' function considers only vertical
2950      scrolling.  If POSITION is out of view only because WINDOW has
2951      been scrolled horizontally, `pos-visible-in-window-p' returns `t'.
2952      *Note Horizontal Scrolling::.
2953
2954 \1f
2955 File: lispref.info,  Node: Vertical Scrolling,  Next: Horizontal Scrolling,  Prev: Window Start,  Up: Windows
2956
2957 Vertical Scrolling
2958 ==================
2959
2960 Vertical scrolling means moving the text up or down in a window.  It
2961 works by changing the value of the window's display-start location.  It
2962 may also change the value of `window-point' to keep it on the screen.
2963
2964    In the commands `scroll-up' and `scroll-down', the directions "up"
2965 and "down" refer to the motion of the text in the buffer at which you
2966 are looking through the window.  Imagine that the text is written on a
2967 long roll of paper and that the scrolling commands move the paper up
2968 and down.  Thus, if you are looking at text in the middle of a buffer
2969 and repeatedly call `scroll-down', you will eventually see the
2970 beginning of the buffer.
2971
2972    Some people have urged that the opposite convention be used: they
2973 imagine that the window moves over text that remains in place.  Then
2974 "down" commands would take you to the end of the buffer.  This view is
2975 more consistent with the actual relationship between windows and the
2976 text in the buffer, but it is less like what the user sees.  The
2977 position of a window on the terminal does not move, and short scrolling
2978 commands clearly move the text up or down on the screen.  We have chosen
2979 names that fit the user's point of view.
2980
2981    The scrolling functions (aside from `scroll-other-window') have
2982 unpredictable results if the current buffer is different from the buffer
2983 that is displayed in the selected window.  *Note Current Buffer::.
2984
2985  - Command: scroll-up &optional lines
2986      This function scrolls the text in the selected window upward LINES
2987      lines.  If LINES is negative, scrolling is actually downward.
2988
2989      If LINES is `nil' (or omitted), then the length of scroll is
2990      `next-screen-context-lines' lines less than the usable height of
2991      the window (not counting its modeline).
2992
2993      `scroll-up' returns `nil'.
2994
2995  - Command: scroll-down &optional lines
2996      This function scrolls the text in the selected window downward
2997      LINES lines.  If LINES is negative, scrolling is actually upward.
2998
2999      If LINES is omitted or `nil', then the length of the scroll is
3000      `next-screen-context-lines' lines less than the usable height of
3001      the window (not counting its mode line).
3002
3003      `scroll-down' returns `nil'.
3004
3005  - Command: scroll-other-window &optional lines
3006      This function scrolls the text in another window upward LINES
3007      lines.  Negative values of LINES, or `nil', are handled as in
3008      `scroll-up'.
3009
3010      You can specify a buffer to scroll with the variable
3011      `other-window-scroll-buffer'.  When the selected window is the
3012      minibuffer, the next window is normally the one at the top left
3013      corner.  You can specify a different window to scroll with the
3014      variable `minibuffer-scroll-window'.  This variable has no effect
3015      when any other window is selected.  *Note Minibuffer Misc::.
3016
3017      When the minibuffer is active, it is the next window if the
3018      selected window is the one at the bottom right corner.  In this
3019      case, `scroll-other-window' attempts to scroll the minibuffer.  If
3020      the minibuffer contains just one line, it has nowhere to scroll
3021      to, so the line reappears after the echo area momentarily displays
3022      the message "Beginning of buffer".
3023
3024  - Variable: other-window-scroll-buffer
3025      If this variable is non-`nil', it tells `scroll-other-window'
3026      which buffer to scroll.
3027
3028  - User Option: scroll-step
3029      This variable controls how scrolling is done automatically when
3030      point moves off the screen.  If the value is zero, then redisplay
3031      scrolls the text to center point vertically in the window.  If the
3032      value is a positive integer N, then redisplay brings point back on
3033      screen by scrolling N lines in either direction, if possible;
3034      otherwise, it centers point.  The default value is zero.
3035
3036  - User Option: scroll-conservatively
3037      This variable controls how many lines Emacs tries to scroll before
3038      recentering.  If you set it to a small number, then when you move
3039      point a short distance off the screen, XEmacs will scroll the
3040      screen just far enough to bring point back on screen, provided
3041      that does not exceed `scroll-conservatively' lines.  This variable
3042      overrides the redisplay preemption.
3043
3044  - User Option: next-screen-context-lines
3045      The value of this variable is the number of lines of continuity to
3046      retain when scrolling by full screens.  For example, `scroll-up'
3047      with an argument of `nil' scrolls so that this many lines at the
3048      bottom of the window appear instead at the top.  The default value
3049      is `2'.
3050
3051  - Command: recenter &optional location window
3052      This function scrolls WINDOW (which defaults to the selected
3053      window) to put the text where point is located at a specified
3054      vertical position within the window.
3055
3056      If LOCATION is a nonnegative number, it puts the line containing
3057      point LOCATION lines down from the top of the window.  If LOCATION
3058      is a negative number, then it counts upward from the bottom of the
3059      window, so that -1 stands for the last usable line in the window.
3060      If LOCATION is a non-`nil' list, then it stands for the line in
3061      the middle of the window.
3062
3063      If LOCATION is `nil', `recenter' puts the line containing point in
3064      the middle of the window, then clears and redisplays the entire
3065      selected frame.
3066
3067      When `recenter' is called interactively, LOCATION is the raw
3068      prefix argument.  Thus, typing `C-u' as the prefix sets the
3069      LOCATION to a non-`nil' list, while typing `C-u 4' sets LOCATION
3070      to 4, which positions the current line four lines from the top.
3071
3072      With an argument of zero, `recenter' positions the current line at
3073      the top of the window.  This action is so handy that some people
3074      make a separate key binding to do this.  For example,
3075
3076           (defun line-to-top-of-window ()
3077             "Scroll current line to top of window.
3078           Replaces three keystroke sequence C-u 0 C-l."
3079             (interactive)
3080             (recenter 0))
3081           
3082           (global-set-key [kp-multiply] 'line-to-top-of-window)
3083
3084 \1f
3085 File: lispref.info,  Node: Horizontal Scrolling,  Next: Size of Window,  Prev: Vertical Scrolling,  Up: Windows
3086
3087 Horizontal Scrolling
3088 ====================
3089
3090 Because we read English first from top to bottom and second from left
3091 to right, horizontal scrolling is not like vertical scrolling.  Vertical
3092 scrolling involves selection of a contiguous portion of text to display.
3093 Horizontal scrolling causes part of each line to go off screen.  The
3094 amount of horizontal scrolling is therefore specified as a number of
3095 columns rather than as a position in the buffer.  It has nothing to do
3096 with the display-start position returned by `window-start'.
3097
3098    Usually, no horizontal scrolling is in effect; then the leftmost
3099 column is at the left edge of the window.  In this state, scrolling to
3100 the right is meaningless, since there is no data to the left of the
3101 screen to be revealed by it; so this is not allowed.  Scrolling to the
3102 left is allowed; it scrolls the first columns of text off the edge of
3103 the window and can reveal additional columns on the right that were
3104 truncated before.  Once a window has a nonzero amount of leftward
3105 horizontal scrolling, you can scroll it back to the right, but only so
3106 far as to reduce the net horizontal scroll to zero.  There is no limit
3107 to how far left you can scroll, but eventually all the text will
3108 disappear off the left edge.
3109
3110  - Command: scroll-left &optional count
3111      This function scrolls the selected window COUNT columns to the
3112      left (or to the right if COUNT is negative).  The return value is
3113      the total amount of leftward horizontal scrolling in effect after
3114      the change--just like the value returned by `window-hscroll'
3115      (below).
3116
3117  - Command: scroll-right &optional count
3118      This function scrolls the selected window COUNT columns to the
3119      right (or to the left if COUNT is negative).  The return value is
3120      the total amount of leftward horizontal scrolling in effect after
3121      the change--just like the value returned by `window-hscroll'
3122      (below).
3123
3124      Once you scroll a window as far right as it can go, back to its
3125      normal position where the total leftward scrolling is zero,
3126      attempts to scroll any farther right have no effect.
3127
3128  - Function: window-hscroll &optional window
3129      This function returns the total leftward horizontal scrolling of
3130      WINDOW--the number of columns by which the text in WINDOW is
3131      scrolled left past the left margin.
3132
3133      The value is never negative.  It is zero when no horizontal
3134      scrolling has been done in WINDOW (which is usually the case).
3135
3136      If WINDOW is `nil', the selected window is used.
3137
3138           (window-hscroll)
3139                => 0
3140           (scroll-left 5)
3141                => 5
3142           (window-hscroll)
3143                => 5
3144
3145  - Function: set-window-hscroll window columns
3146      This function sets the number of columns from the left margin that
3147      WINDOW is scrolled to the value of COLUMNS.  The argument COLUMNS
3148      should be zero or positive; if not, it is taken as zero.
3149
3150      The value returned is COLUMNS.
3151
3152           (set-window-hscroll (selected-window) 10)
3153                => 10
3154
3155    Here is how you can determine whether a given position POSITION is
3156 off the screen due to horizontal scrolling:
3157
3158      (defun hscroll-on-screen (window position)
3159        (save-excursion
3160          (goto-char position)
3161          (and
3162           (>= (- (current-column) (window-hscroll window)) 0)
3163           (< (- (current-column) (window-hscroll window))
3164              (window-width window)))))
3165
3166 \1f
3167 File: lispref.info,  Node: Size of Window,  Next: Position of Window,  Prev: Horizontal Scrolling,  Up: Windows
3168
3169 The Size of a Window
3170 ====================
3171
3172 An Emacs window is rectangular, and its size information consists of
3173 the height (in lines or pixels) and the width (in character positions
3174 or pixels).  The modeline is included in the height.  The pixel width
3175 and height values include scrollbars and margins, while the
3176 line/character-position values do not.
3177
3178    Note that the height in lines, and the width in characters, are
3179 determined by dividing the corresponding pixel value by the height or
3180 width of the default font in that window (if this is a variable-width
3181 font, the average width is used).  The resulting values may or may not
3182 represent the actual number of lines in the window, or the actual number
3183 of character positions in any particular line, esp. if there are pixmaps
3184 or various different fonts in the window.
3185
3186    The following functions return size information about a window:
3187
3188  - Function: window-height &optional window
3189      This function returns the number of lines in WINDOW, including its
3190      modeline but not including the horizontal scrollbar, if any (this
3191      is different from `window-pixel-height').  If WINDOW is `nil', the
3192      function uses the selected window.
3193
3194           (window-height)
3195                => 40
3196           (split-window-vertically)
3197                => #<window on "windows.texi" 0x679b>
3198           (window-height)
3199                => 20
3200
3201  - Function: window-width &optional window
3202      This function returns the number of columns in WINDOW, not
3203      including any left margin, right margin, or vertical scrollbar
3204      (this is different from `window-pixel-width').  If WINDOW is
3205      `nil', the function uses the selected window.
3206
3207           (window-width)
3208                => 80
3209           (window-height)
3210                => 40
3211           (split-window-horizontally)
3212                => #<window on "windows.texi" 0x7538>
3213           (window-width)
3214                => 39
3215
3216    Note that after splitting the window into two side-by-side windows,
3217 the width of each window is less the half the width of the original
3218 window because a vertical scrollbar appeared between the windows,
3219 occupying two columns worth of space.  Also, the height shrunk by one
3220 because horizontal scrollbars appeared that weren't there before.
3221 (Horizontal scrollbars appear only when lines are truncated, not when
3222 they wrap.  This is usually the case for horizontally split windows but
3223 not for full-frame windows.  You can change this using the variables
3224 `truncate-lines' and `truncate-partial-width-windows'.)
3225
3226  - Function: window-pixel-height &optional window
3227      This function returns the height of WINDOW in pixels, including
3228      its modeline and horizontal scrollbar, if any.  If WINDOW is
3229      `nil', the function uses the selected window.
3230
3231           (window-pixel-height)
3232                => 600
3233           (split-window-vertically)
3234                => #<window on "windows.texi" 0x68a6>
3235           (window-pixel-height)
3236                => 300
3237
3238  - Function: window-pixel-width &optional window
3239      This function returns the width of WINDOW in pixels, including any
3240      left margin, right margin, or vertical scrollbar that may be
3241      displayed alongside it.  If WINDOW is `nil', the function uses the
3242      selected window.
3243
3244           (window-pixel-width)
3245                => 735
3246           (window-pixel-height)
3247                => 600
3248           (split-window-horizontally)
3249                => #<window on "windows.texi" 0x7538>
3250           (window-pixel-width)
3251                => 367
3252           (window-pixel-height)
3253                => 600
3254
3255  - Function: window-text-area-pixel-height &optional window
3256      This function returns the height in pixels of the text displaying
3257      portion of WINDOW, which defaults to the selected window.  Unlike
3258      `window-pixel-height', the space occupied by the modeline and
3259      horizontal scrollbar, if any, is not counted.
3260
3261  - Function: window-text-area-pixel-width &optional window
3262      This function returns the width in pixels of the text displaying
3263      portion of WINDOW, which defaults to the selected window.  Unlike
3264      `window-pixel-width', the space occupied by the vertical scrollbar
3265      and divider, if any, is not counted.
3266
3267  - Function: window-displayed-text-pixel-height &optional window
3268           noclipped
3269      This function returns the height in pixels of the text displayed in
3270      WINDOW, which defaults to the selected window.  Unlike
3271      `window-text-area-pixel-height', any blank space below the end of
3272      the buffer is not included.  If optional argument NOCLIPPED is
3273      non-`nil', any space occupied by clipped lines will not be
3274      included.
3275
3276 \1f
3277 File: lispref.info,  Node: Position of Window,  Next: Resizing Windows,  Prev: Size of Window,  Up: Windows
3278
3279 The Position of a Window
3280 ========================
3281
3282 XEmacs provides functions to determine the absolute location of windows
3283 within a frame, and the relative location of a window in comparison to
3284 other windows in the same frame.
3285
3286  - Function: window-pixel-edges &optional window
3287      This function returns a list of the pixel edge coordinates of
3288      WINDOW.  If WINDOW is `nil', the selected window is used.
3289
3290      The order of the list is `(LEFT TOP RIGHT BOTTOM)', all elements
3291      relative to 0, 0 at the top left corner of WINDOW's frame.  The
3292      element RIGHT of the value is one more than the rightmost pixel
3293      used by WINDOW (including any left margin, right margin, or
3294      vertical scrollbar displayed alongside it), and BOTTOM is one more
3295      than the bottommost pixel used by WINDOW (including any modeline
3296      or horizontal scrollbar displayed above or below it).  The frame
3297      area does not include any frame menubars, toolbars, or gutters
3298      that may be displayed; thus, for example, if there is only one
3299      window on the frame, the values for LEFT and TOP will always be 0.
3300
3301      If WINDOW is at the upper left corner of its frame, RIGHT and
3302      BOTTOM are the same as the values returned by
3303      `(window-pixel-width)' and `(window-pixel-height)' respectively,
3304      and LEFT and TOP are zero.
3305
3306    There is no longer a function `window-edges' because it does not
3307 make sense in a world with variable-width and variable-height lines, as
3308 are allowed in XEmacs.
3309
3310  - Function: window-highest-p window
3311      This function returns non-`nil' if WINDOW is along the top of its
3312      frame.
3313
3314  - Function: window-lowest-p window
3315      This function returns non-`nil' if WINDOW is along the bottom of
3316      its frame.
3317
3318  - Function: window-text-area-pixel-edges &optional window
3319