@end defvar
@defopt make-backup-files
- This variable determines whether or not to make backup files. If it
+This variable determines whether or not to make backup files. If it
is non-@code{nil}, then Emacs creates a backup of each file when it is
-saved for the first time.
+saved for the first time---provided that @code{backup-inhibited}
+is @code{nil} (see below).
- The following example shows how to change the @code{make-backup-files}
+The following example shows how to change the @code{make-backup-files}
variable only in the @file{RMAIL} buffer and not elsewhere. Setting it
@code{nil} stops Emacs from making backups of the @file{RMAIL} file,
which may save disk space. (You would put this code in your
If this variable is non-@code{nil}, backups are inhibited. It records
the result of testing @code{backup-enable-predicate} on the visited file
name. It can also coherently be used by other mechanisms that inhibit
-backups based on which file is visited. This is a permanent local,
-so that changing the major mode does not lose its value.
+backups based on which file is visited. For example, VC sets this
+variable non-@code{nil} to prevent making backups for files managed
+with a version control system.
-Major modes should not set this variable---they should set
+This is a permanent local, so that changing the major mode does not lose
+its value. Major modes should not set this variable---they should set
@code{make-backup-files} instead.
@end defvar
have auto-saving enabled by default. Otherwise, they do not.
@end defopt
-@deffn Command do-auto-save &optional no-message
+@deffn Command do-auto-save &optional no-message current-only
This function auto-saves all buffers that need to be auto-saved. It
saves all buffers for which auto-saving is enabled and that have been
changed since the previous auto-save.
@samp{Auto-saving...} is displayed in the echo area while auto-saving is
going on. However, if @var{no-message} is non-@code{nil}, the message
is inhibited.
+
+If @var{current-only} is non-@code{nil}, only the current buffer
+is auto-saved.
@end deffn
@defun delete-auto-save-file-if-necessary
If it is -1, that means auto-saving is temporarily shut off in this
buffer due to a substantial deletion. Explicitly saving the buffer
-stores a positive value in this variable, thus reenabling auto-save.
+stores a positive value in this variable, thus reenabling auto-saving.
Turning auto-save mode off or on also alters this variable.
@end defvar
@defvar auto-save-list-file-name
This variable (if non-@code{nil}) specifies a file for recording the
names of all the auto-save files. Each time Emacs does auto-saving, it
-writes into this file the names of all the auto-save files of all the
-buffers that have auto-save enabled. If Emacs crashes, you can look in
-this file to find all the auto-save files that might contain work that
-was otherwise lost. The @code{multi-replace} command uses these files.
+writes two lines into this file for each buffer that has auto-saving
+enabled. The first line gives the name of the visited file (it's empty
+if the buffer has none), and the second gives the name of the auto-save
+file.
+
+If Emacs exits normally, it deletes this file. If Emacs crashes, you
+can look in the file to find all the auto-save files that might contain
+work that was otherwise lost. The @code{recover-session} command uses
+these files.
The default name for this file is in your home directory and starts with
@samp{.saves-}. It also contains the Emacs process @sc{id} and the host
@defvar revert-buffer-insert-file-contents-function
The value of this variable, if non-@code{nil}, is the function to use to
-insert contents when reverting this buffer. The function receives two
-arguments, first the file name to use; second, @code{t} if the user has
-asked to read the auto-save file.
+insert the updated contents when reverting this buffer. The function
+receives two arguments: first the file name to use; second, @code{t} if
+the user has asked to read the auto-save file.
@end defvar
@defvar before-revert-hook
buffer contents.
@end defvar
-@deffn Command recover-file filename
-This function visits @var{filename}, but gets the contents from its
-last auto-save file. This is useful after the system has crashed, to
-resume editing the same file without losing all the work done in the
-previous session.
-
-An error is signaled if there is no auto-save file for @var{filename},
-or if @var{filename} is newer than its auto-save file. If
-@var{filename} does not exist, but its auto-save file does, then the
-auto-save file is read as usual. This last situation may occur if you
-visited a nonexistent file and never actually saved it.
-@end deffn
-
not be displayed in any windows.
@end ifinfo
- Buffers in Emacs editing are objects that have distinct names and
-hold text that can be edited. Buffers appear to Lisp programs as a
-special data type. The contents of a buffer may be viewed as an
-extendable string; insertions and deletions may occur in any part of the
-buffer. @xref{Text}.
+ Buffers in Emacs editing are objects that have distinct names and hold
+text that can be edited. Buffers appear to Lisp programs as a special
+data type. You can think of the contents of a buffer as an extendable
+string; insertions and deletions may occur in any part of the buffer.
+@xref{Text}.
A Lisp buffer object contains numerous pieces of information. Some of
this information is directly accessible to the programmer through
object, not a name.
Buffers that are ephemeral and generally uninteresting to the user
-have names starting with a space, so that the @code{list-buffers} or
+have names starting with a space, so that the @code{list-buffers} and
@code{buffer-menu} commands don't mention them. A name starting with
space also initially disables recording undo information; see
@ref{Undo}.
Here, the purpose is to show the user that editing the buffer with the
aim of saving it in the file may be futile or undesirable. The user who
wants to change the buffer text despite this can do so after clearing
-the read-only flag with @kbd{C-M-q}.
+the read-only flag with @kbd{C-x C-q}.
@item
Modes such as Dired and Rmail make buffers read-only when altering the
associated with changing the current buffer (unless you happen to know
that the buffer being killed isn't current). @xref{Current Buffer}.
+ If you kill a buffer that is the base buffer of one or more indirect
+buffers, the indirect buffers are automatically killed as well.
+
The @code{buffer-name} of a killed buffer is @code{nil}. You can use
this feature to test whether a buffer has been killed:
An @dfn{indirect buffer} shares the text of some other buffer, which
is called the @dfn{base buffer} of the indirect buffer. In some ways it
-is the equivalent, for buffers, of a symbolic link among files. The base
+is the analogue, for buffers, of a symbolic link among files. The base
buffer may not itself be an indirect buffer.
The text of the indirect buffer is always identical to the text of its
@code{last-command} describes the command before that. @xref{Hooks}.
@end defvar
- An erroneous function in the @code{pre-command-hook} list could easily
-make Emacs go into an infinite loop of errors. To protect you from this
-sort of painful problem, Emacs sets the hook variable to @code{nil}
-temporarily while running the functions in the hook. Thus, if a hook
-function gets an error, the hook variable is left as @code{nil}. Emacs
-does the same thing for @code{post-command-hook}.
-
Quitting is suppressed while running @code{pre-command-hook} and
-@code{post-command-hook}; this is because otherwise a quit, happening by
-chance within one of these hooks, would turn off the hook.
-
- One inconvenient result of these protective features is that you
-cannot have a function in @code{post-command-hook} or
-@code{pre-command-hook} which changes the value of that variable. But
-that's not a real limitation. If you want hook functions to change the
-hook, simply add one fixed function to the hook, and code that function
-to look in another hook variable for other functions to call. Here is
-an example:
-
-@example
-;; @r{Set up the mechanism.}
-(defvar current-post-command-function nil)
-(defun run-current-post-command-function ()
- (if current-post-command-function
- (funcall current-post-command-function)))
-(add-hooks 'post-command-hook
- 'run-current-post-command-function)
-
-;; @r{Here's a hook function which replaces itself}
-;; @r{with a different hook function to run next time.}
-(defun first-post-command-function ()
- (setq current-post-command-function
- 'second-post-command-function))
-@end example
+@code{post-command-hook}. If an error happens while executing one of
+these hooks, it terminates execution of the hook, but that is all it
+does.
@node Defining Commands
@section Defining Commands
The interactively callable objects include strings and vectors (treated
as keyboard macros), lambda expressions that contain a top-level call to
-@code{interactive}, compiled function objects made from such lambda
+@code{interactive}, byte-code function objects made from such lambda
expressions, autoload objects that are declared as interactive
(non-@code{nil} fourth argument to @code{autoload}), and some of the
primitive functions.
The value is copied from @code{this-command} when a command returns to
the command loop, except when the command specifies a prefix argument
for the following command.
+
+This variable is always local to the current terminal and cannot be
+buffer-local. @xref{Multiple Displays}.
@end defvar
@defvar this-command
@cindex kill command repetition
Some commands set this variable during their execution, as a flag for
-whatever command runs next. In particular, the functions that kill text
+whatever command runs next. In particular, the functions for killing text
set @code{this-command} to @code{kill-region} so that any kill commands
immediately following will know to append the killed text to the
previous kill.
@xref{Input Focus}.
@end defvar
-@defvar echo-keystrokes
-This variable determines how much time should elapse before command
-characters echo. Its value must be an integer, which specifies the
-number of seconds to wait before echoing. If the user types a prefix
-key (such as @kbd{C-x}) and then delays this many seconds before
-continuing, the prefix key is echoed in the echo area. Any subsequent
-characters in the same command will be echoed as well.
-
-If the value is zero, then command input is not echoed.
-@end defvar
-
@node Input Events
@section Input Events
@cindex events
@table @asis
@item meta
-The 2**23 bit in the character code indicates a character
+The
+@iftex
+$2^{27}$
+@end iftex
+@ifinfo
+2**27
+@end ifinfo
+bit in the character code indicates a character
typed with the meta key held down.
@item control
-The 2**22 bit in the character code indicates a non-@sc{ASCII}
+The
+@iftex
+$2^{26}$
+@end iftex
+@ifinfo
+2**26
+@end ifinfo
+bit in the character code indicates a non-@sc{ASCII}
control character.
@sc{ASCII} control characters such as @kbd{C-a} have special basic
But if you type a control combination not in @sc{ASCII}, such as
@kbd{%} with the control key, the numeric value you get is the code
-for @kbd{%} plus 2**22 (assuming the terminal supports non-@sc{ASCII}
+for @kbd{%} plus
+@iftex
+$2^{26}$
+@end iftex
+@ifinfo
+2**26
+@end ifinfo
+(assuming the terminal supports non-@sc{ASCII}
control characters).
@item shift
-The 2**21 bit in the character code indicates an @sc{ASCII} control
+The
+@iftex
+$2^{25}$
+@end iftex
+@ifinfo
+2**25
+@end ifinfo
+bit in the character code indicates an @sc{ASCII} control
character typed with the shift key held down.
For letters, the basic code indicates upper versus lower case; for
digits and punctuation, the shift key selects an entirely different
character with a different basic code. In order to keep within
the @sc{ASCII} character set whenever possible, Emacs avoids using
-the 2**21 bit for those characters.
+the
+@iftex
+$2^{25}$
+@end iftex
+@ifinfo
+2**25
+@end ifinfo
+bit for those characters.
However, @sc{ASCII} provides no way to distinguish @kbd{C-A} from
-@kbd{C-a}, so Emacs uses the 2**21 bit in @kbd{C-A} and not in
+@kbd{C-a}, so Emacs uses the
+@iftex
+$2^{25}$
+@end iftex
+@ifinfo
+2**25
+@end ifinfo
+bit in @kbd{C-A} and not in
@kbd{C-a}.
@item hyper
-The 2**20 bit in the character code indicates a character
+The
+@iftex
+$2^{24}$
+@end iftex
+@ifinfo
+2**24
+@end ifinfo
+bit in the character code indicates a character
typed with the hyper key held down.
@item super
-The 2**19 bit in the character code indicates a character
+The
+@iftex
+$2^{23}$
+@end iftex
+@ifinfo
+2**23
+@end ifinfo
+bit in the character code indicates a character
typed with the super key held down.
@item alt
-The 2**18 bit in the character code indicates a character typed with
+The
+@iftex
+$2^{22}$
+@end iftex
+@ifinfo
+2**22
+@end ifinfo
+bit in the character code indicates a character typed with
the alt key held down. (On some terminals, the key labeled @key{ALT}
is actually the meta key.)
@end table
- In the future, Emacs may support a larger range of basic codes. We
-may also move the modifier bits to larger bit numbers. Therefore, you
-should avoid mentioning specific bit numbers in your program.
-Instead, the way to test the modifier bits of a character is with the
-function @code{event-modifiers} (@pxref{Classifying Events}).
+ It is best to avoid mentioning specific bit numbers in your program.
+To test the modifier bits of a character, use the function
+@code{event-modifiers} (@pxref{Classifying Events}). When making key
+bindings, you can use the read syntax for characters with modifier bits
+(@samp{\C-}, @samp{\M-}, and so on). For making key bindings with
+@code{define-key}, you can use lists such as @code{(control hyper ?x)} to
+specify the characters (@pxref{Changing Key Bindings}). The function
+@code{event-convert-list} converts such a list into an event type
+(@pxref{Classifying Events}).
@node Function Keys
@subsection Function Keys
frame has already been iconified, Emacs has no work to do.
@end table
+ If one of these events arrives in the middle of a key sequence---that
+is, after a prefix key---then Emacs reorders the events so that this
+event comes either before or after the multi-event key sequence, not
+within it.
+
@node Event Examples
@subsection Event Examples
event.
@end defun
+@defun event-convert-list list
+This function converts a list of modifier names and a basic event type
+to an event type which specifies all of them. For example,
+
+@example
+(event-convert-list '(control ?a))
+ @result{} 1
+(event-convert-list '(control meta ?a))
+ @result{} -134217727
+(event-convert-list '(control super f1))
+ @result{} C-s-f1
+@end example
+@end defun
+
@node Accessing Events
@subsection Accessing Events
A keyboard character typed using the @key{META} key is called a
@dfn{meta character}. The numeric code for such an event includes the
-2**23 bit; it does not even come close to fitting in a string. However,
+@iftex
+$2^{27}$
+@end iftex
+@ifinfo
+2**27
+@end ifinfo
+bit; it does not even come close to fitting in a string. However,
earlier Emacs versions used a different representation for these
characters, which gave them codes in the range of 128 to 255. That did
fit in a string, and many Lisp programs contain string constants that
in the string unchanged.
@item
-The meta variants of those characters, with codes in the range of 2**23
-to 2**23+127, can also go in the string, but you must change their
-numeric values. You must set the 2**7 bit instead of the 2**23 bit,
+The meta variants of those characters, with codes in the range of
+@iftex
+$2^{27}$
+@end iftex
+@ifinfo
+2**27
+@end ifinfo
+to
+@iftex
+$2^{27} + 127$,
+@end iftex
+@ifinfo
+2**27+127,
+@end ifinfo
+can also go in the string, but you must change their
+numeric values. You must set the
+@iftex
+$2^{7}$
+@end iftex
+@ifinfo
+2**7
+@end ifinfo
+bit instead of the
+@iftex
+$2^{27}$
+@end iftex
+@ifinfo
+2**27
+@end ifinfo
+bit,
resulting in a value between 128 and 255.
@item
The function @code{read-key-sequence} also transforms some mouse events.
It converts unbound drag events into click events, and discards unbound
-button-down events entirely. It also reshuffles focus events so that they
-never appear in a key sequence with any other events.
+button-down events entirely. It also reshuffles focus events and
+miscellaneous window events so that they never appear in a key sequence
+with any other events.
When mouse events occur in special parts of a window, such as a mode
line or a scroll bar, the event type shows nothing special---it is the
defining key sequences using these imaginary prefix keys.
For example, if you call @code{read-key-sequence} and then click the
-mouse on the window's mode line, you get an event like this:
+mouse on the window's mode line, you get two events, like this:
@example
(read-key-sequence "Click on the mode line: ")
@end group
@group
+;; @r{We assume here you use @kbd{M-:} to evaluate this.}
(symbol-function 'foo)
- @result{} "^[^[(read-char)^M1"
+ @result{} "^[:(read-char)^M1"
@end group
@group
(execute-kbd-macro 'foo)
In the example below, the Lisp program reads the character @kbd{1},
@sc{ASCII} code 49. It becomes the value of @code{last-input-event},
-while @kbd{C-e} (from the @kbd{C-x C-e} command used to evaluate this
-expression) remains the value of @code{last-command-event}.
+while @kbd{C-e} (we assume @kbd{C-x C-e} command is used to evaluate
+this expression) remains the value of @code{last-command-event}.
@example
@group
time with no input arriving (see @code{input-pending-p} in @ref{Event
Input Misc}). Otherwise, the value is @code{nil}.
-@c Emacs 19 feature ??? maybe not working yet
+The argument @var{seconds} need not be an integer. If it is a floating
+point number, @code{sit-for} waits for a fractional number of seconds.
+Some systems support only a whole number of seconds; on these systems,
+@var{seconds} is rounded down.
+
The optional argument @var{millisec} specifies an additional waiting
period measured in milliseconds. This adds to the period specified by
-@var{seconds}. Not all operating systems support waiting periods other
-than multiples of a second; on those that do not, you get an error if
-you specify nonzero @var{millisec}.
+@var{seconds}. If the system doesn't support waiting fractions of a
+second, you get an error if you specify nonzero @var{millisec}.
@cindex forcing redisplay
Redisplay is always preempted if input arrives, and does not happen at
the display. It pays no attention to available input. It returns
@code{nil}.
-@c Emacs 19 feature ??? maybe not working yet
+The argument @var{seconds} need not be an integer. If it is a floating
+point number, @code{sleep-for} waits for a fractional number of seconds.
+Some systems support only a whole number of seconds; on these systems,
+@var{seconds} is rounded down.
+
The optional argument @var{millisec} specifies an additional waiting
period measured in milliseconds. This adds to the period specified by
-@var{seconds}. Not all operating systems support waiting periods other
-than multiples of a second; on those that do not, you get an error if
-you specify nonzero @var{millisec}.
+@var{seconds}. If the system doesn't support waiting fractions of a
+second, you get an error if you specify nonzero @var{millisec}.
Use @code{sleep-for} when you wish to guarantee a delay.
@end defun
been executed, to make it convenient to repeat these commands. A
@dfn{complex command} is one for which the interactive argument reading
uses the minibuffer. This includes any @kbd{M-x} command, any
-@kbd{M-ESC} command, and any command whose @code{interactive}
+@kbd{M-:} command, and any command whose @code{interactive}
specification reads an argument from the minibuffer. Explicit use of
the minibuffer during the execution of the command itself does not cause
the command to be considered complex.
encounters an error or a failing search.
@end defun
-@defvar last-kbd-macro
-This variable is the definition of the most recently defined keyboard
-macro. Its value is a string or vector, or @code{nil}.
-
-The variable is always local to the current X terminal and cannot be
-buffer-local. @xref{Multiple Displays}.
-@end defvar
-
@defvar executing-macro
This variable contains the string or vector that defines the keyboard
macro that is currently executing. It is @code{nil} if no macro is
being defined. The commands @code{start-kbd-macro} and
@code{end-kbd-macro} set this variable---do not set it yourself.
-The variable is always local to the current X terminal and cannot be
+The variable is always local to the current terminal and cannot be
+buffer-local. @xref{Multiple Displays}.
+@end defvar
+
+@defvar last-kbd-macro
+This variable is the definition of the most recently defined keyboard
+macro. Its value is a string or vector, or @code{nil}.
+
+The variable is always local to the current terminal and cannot be
buffer-local. @xref{Multiple Displays}.
@end defvar
by recent earlier versions of Emacs, but the reverse is not true. In
particular, if you compile a program with Emacs 19.29, the compiled
code does not run in earlier versions.
+@iftex
+@xref{Docs and Compilation}.
+@end iftex
+Files compiled in versions before 19.29 may not work in 19.29 if they
+contain character constants with modifier bits, because the bits were
+renumbered in Emacs 19.29.
@xref{Compilation Errors}, for how to investigate errors occurring in
byte compilation.
for proper compilation. For more details, see @ref{Compiling Macros}.
Normally, compiling a file does not evaluate the file's contents or
-load the file. But it does execute any @code{require} calls at
-top level in the file. One way to ensure that necessary macro
-definitions are available during compilation is to require the file that
-defines them. @xref{Features}.
+load the file. But it does execute any @code{require} calls at top
+level in the file. One way to ensure that necessary macro definitions
+are available during compilation is to require the file that defines
+them (@pxref{Named Features}). To avoid loading the macro definition files
+when someone @emph{runs} the compiled program, write
+@code{eval-when-compile} around the @code{require} calls (@pxref{Eval
+During Compile}).
@defun byte-compile symbol
This function byte-compiles the function definition of @var{symbol},
needs recompilation. A file needs recompilation if a @samp{.elc} file
exists but is older than the @samp{.el} file.
-If a @samp{.el} file exists, but there is no corresponding @samp{.elc}
-file, then @var{flag} says what to do. If it is @code{nil}, the file is
+When a @samp{.el} file has no corresponding @samp{.elc} file, then
+@var{flag} says what to do. If it is @code{nil}, these files are
ignored. If it is non-@code{nil}, the user is asked whether to compile
-the file.
+each such file.
The returned value of this command is unpredictable.
@end deffn
to @code{nil}. Once this is done, you can compile files that will load
into older Emacs versions. You can do this globally, or for one source
file by specifying a file-local binding for the variable. Here's one
-way:
+way to do that:
@example
-*-byte-compile-dynamic-docstrings: nil;-*-
@end defspec
@node Byte-Code Objects
-@section Byte-Code Objects
+@section Byte-Code Function Objects
@cindex compiled function
@cindex byte-code function
The maximum stack size this function needs.
@item docstring
-The documentation string (if any); otherwise, @code{nil}. For functions
-preloaded before Emacs is dumped, this is usually an integer which is an
-index into the @file{DOC} file; use @code{documentation} to convert this
-into a string (@pxref{Accessing Documentation}).
+The documentation string (if any); otherwise, @code{nil}. The value may
+be a number or a list, in case the documentation string is stored in a
+file. Use the function @code{documentation} to get the real
+documentation string (@pxref{Accessing Documentation}).
@item interactive
The interactive spec (if any). This can be a string or a Lisp
(if (eq baz 35)
t
;; @r{This is a call to the function @code{error}.}
- (error "Rats! The variable %s was %s, not 35." 'baz baz))
+ (error "Rats! The variable %s was %s, not 35" 'baz baz))
;; @r{This is the handler; it is not a form.}
(error (princ (format "The error was: %s" err))
2))
-@print{} The error was: (error "Rats! The variable baz was 34, not 35.")
+@print{} The error was: (error "Rats! The variable baz was 34, not 35")
@result{} 2
@end group
@end smallexample
This error has three condition names: @code{new-error}, the narrowest
classification; @code{my-own-errors}, which we imagine is a wider
classification; and @code{error}, which is the widest of all.
+
+ The error string should start with a capital letter but it should
+not end with a period. This is for consistency with the rest of Emacs.
Naturally, Emacs will never signal @code{new-error} on its own; only
an explicit call to @code{signal} (@pxref{Signaling Errors}) in your
If the function is already set up to invoke the debugger on entry,
@code{debug-on-entry} does nothing.
- Caveat: if you redefine a function after using @code{debug-on-entry}
-on it, the code to enter the debugger is lost.
+ @strong{Note:} if you redefine a function after using
+@code{debug-on-entry} on it, the code to enter the debugger is lost.
@code{debug-on-entry} returns @var{function-name}.
@deffn Command cancel-debug-on-entry function-name
This function undoes the effect of @code{debug-on-entry} on
@var{function-name}. When called interactively, it prompts for
-@var{function-name} in the minibuffer.
+@var{function-name} in the minibuffer. If @var{function-name} is
+@code{nil} or the empty string, it cancels debugging for all functions.
If @code{cancel-debug-on-entry} is called more than once on the same
function, the second call does nothing. @code{cancel-debug-on-entry}
@item e
Read a Lisp expression in the minibuffer, evaluate it, and print the
-value in the echo area. The debugger alters certain important variables
-as part of its operation; @kbd{e} temporarily restores their
-outside-the-debugger values so you can examine them. This makes the
-debugger more transparent. By contrast, @kbd{M-@key{ESC}} does nothing
-special in the debugger; it shows you the variable values within the
-debugger.
+value in the echo area. The debugger alters certain important
+variables, and the current buffer, as part of its operation; @kbd{e}
+temporarily restores their outside-the-debugger values so you can
+examine them. This makes the debugger more transparent. By contrast,
+@kbd{M-:} does nothing special in the debugger; it shows you the
+variable values within the debugger.
@item q
Terminate the program being debugged; return to top-level Emacs
If the first of the @var{debugger-args} passed to @code{debug} is
@code{nil} (or if it is not one of the special values in the table
-below), then @code{debug} displays the rest of its arguments at the the
+below), then @code{debug} displays the rest of its arguments at the
top of the @samp{*Backtrace*} buffer. This mechanism is used to display
a message to the user.
@end defun
@defvar command-debug-status
-This variable records the debugging status of current interactive
+This variable records the debugging status of the current interactive
command. Each time a command is called interactively, this variable is
bound to @code{nil}. The debugger can set this variable to leave
information for future debugger invocations during the same command.
This function clears and redisplays all visible frames.
@end deffn
+ Processing user input takes absolute priority over redisplay. If you
+call these functions when input is available, they do nothing
+immediately, but a full redisplay does happen eventually---after all the
+input has been processed.
+
Normally, suspending and resuming Emacs also refreshes the screen.
Some terminal emulators record separate contents for display-oriented
programs such as Emacs and for ordinary sequential display. If you are
means no.
@end defvar
- Processing user input takes absolute priority over redisplay. If you
-call these functions when input is available, they do nothing
-immediately, but a full redisplay does happen eventually---after all the
-input has been processed.
-
@node Screen Size
@section Screen Size
@cindex size of screen
frame) regardless of the value of @code{truncate-lines}.
@end defopt
-@defvar default-truncate-lines
+@defopt default-truncate-lines
This variable is the default value for @code{truncate-lines}, for
buffers that do not have local values for it.
-@end defvar
+@end defopt
@defopt truncate-partial-width-windows
This variable controls display of lines that extend beyond the right
If your buffer contains @strong{very} long lines, and you use
continuation to display them, just thinking about them can make Emacs
-redisplay slow.
+redisplay slow. The column computation and indentation functions also
+become slow. Then you might find it advisable to set
+@code{cache-long-line-scans} to @code{t}.
@defvar cache-long-line-scans
If this variable is non-@code{nil}, various indentation and motion
-functions, and Emacs redisplay, cache the results of their scans for
-newlines, and consult the cache to avoid rescanning regions of the
-buffer unless they are modified.
+functions, and Emacs redisplay, cache the results of scanning the
+buffer, and consult the cache to avoid rescanning regions of the buffer
+unless they are modified.
-Turning on the newline cache slows down processing of short lines.
+Turning on the cache slows down processing of short lines somewhat.
This variable is automatically local in every buffer.
@end defvar
@end example
@end defopt
+@defvar echo-keystrokes
+This variable determines how much time should elapse before command
+characters echo. Its value must be an integer, which specifies the
+number of seconds to wait before echoing. If the user types a prefix
+key (such as @kbd{C-x}) and then delays this many seconds before
+continuing, the prefix key is echoed in the echo area. Any subsequent
+characters in the same command will be echoed as well.
+
+If the value is zero, then command input is not echoed.
+@end defvar
+
@defvar cursor-in-echo-area
This variable controls where the cursor appears when a message is
displayed in the echo area. If it is non-@code{nil}, then the cursor
base. It permits the implementation of convenient filtering commands to
view just a part of the entries in the data base. Setting this variable
is very fast, much faster than scanning all the text in the buffer
-looking for things to change.
+looking for properties to change.
@defvar buffer-invisibility-spec
This variable specifies which kinds of @code{invisible} properties
@end table
@end defvar
+ Ordinarily, commands that operate on text or move point do not care
+whether the text is invisible. However, the user-level line motion
+commands explicitly ignore invisible newlines.
+
@node Selective Display
@section Selective Display
@cindex selective display
- @dfn{Selective display} is a class of minor modes in which specially
-marked lines do not appear on the screen, or in which highly indented
-lines do not appear.
+ @dfn{Selective display} is a pair of features that hide certain
+lines on the screen.
The first variant, explicit selective display, is designed for use in
a Lisp program. The program controls which lines are hidden by altering
Text}); there is a new version of Outline mode which uses that instead.
In the second variant, the choice of lines to hide is made
-automatically based on indentation. This variant is designed as a
+automatically based on indentation. This variant is designed to be a
user-level feature.
The way you control explicit selective display is by replacing a
Temporary displays are used by commands to put output into a buffer
and then present it to the user for perusal rather than for editing.
-Many of the help commands use this feature. Nowadays you can do the
-same job by creating an overlay with a @code{before-string} property.
-@xref{Overlay Properties}.
+Many of the help commands use this feature.
@defspec with-output-to-temp-buffer buffer-name forms@dots{}
This function executes @var{forms} while arranging to insert any
The return value of @code{momentary-string-display} is not meaningful.
+If the string @var{string} does not contain control characters, you can
+do the same job in a more general way by creating an overlay with a
+@code{before-string} property. @xref{Overlay Properties}.
+
If @var{message} is non-@code{nil}, it is displayed in the echo area
while @var{string} is displayed in the buffer. If it is @code{nil}, a
default message says to type @var{char} to continue.
@cindex overlays
You can use @dfn{overlays} to alter the appearance of a buffer's text on
-the screen. An overlay is an object that belongs to a particular
-buffer, and has a specified beginning and end. It also has properties
-that you can examine and set; these affect the display of the text
-within the overlay.
+the screen, for the sake of presentation features. An overlay is an
+object that belongs to a particular buffer, and has a specified
+beginning and end. It also has properties that you can examine and set;
+these affect the display of the text within the overlay.
@menu
* Overlay Properties:: How to read and set properties.
@item category
@kindex category @r{(overlay property)}
If an overlay has a @code{category} property, we call it the
-@dfn{category} of the character. It should be a symbol. The properties
+@dfn{category} of the overlay. It should be a symbol. The properties
of the symbol serve as defaults for the properties of the overlay.
@item face
modified, and the length of the pre-change text replaced by that range.
(For an insertion, the pre-change length is zero; for a deletion, that
length is the number of characters deleted, and the post-change
-beginning and end are at the same place.)
+beginning and end are equal.)
@item insert-in-front-hooks
@kindex insert-in-front-hooks @r{(overlay property)}
@item intangible
@kindex intangible @r{(overlay property)}
The @code{intangible} property on an overlay works just like the
-@code{intangible} text propert. @xref{Special Properties}, for details.
+@code{intangible} text property. @xref{Special Properties}, for details.
@item before-string
@kindex before-string @r{(overlay property)}
With overlays. An overlay may have @code{face} and @code{mouse-face}
properties too; they apply to all the text covered by the overlay.
+@item
+With a region that is active. In Transient Mark mode, the region is
+highlighted with a particular face (see @code{region-face}, below).
+
@item
With special glyphs. Each glyph can specify a particular face id
number. @xref{Glyphs}.
If these various sources together specify more than one face for a
particular character, Emacs merges the attributes of the various faces
specified. The attributes of the faces of special glyphs come first;
+then comes the face for region highlighting, if appropriate;
then come attributes of faces from overlays, followed by those from text
properties, and last the default face.
These functions set the foreground (or background, respectively) color
of face @var{face} to @var{color}. The argument @var{color} should be a
string, the name of a color.
+
+Certain shades of gray are implemented by stipple patterns on
+black-and-white screens.
+@end defun
+
+@defun set-face-stipple face pattern &optional frame
+This function sets the background stipple pattern of face @var{face} to
+@var{pattern}. The argument @var{pattern} should be the name of a
+stipple pattern defined by the X server, or @code{nil} meaning don't use
+stipple.
+
+Normally there is no need to pay attention to stipple patterns, because
+they are used automatically to handle certain shades of gray.
@end defun
@defun set-face-font face font &optional frame
respectively) of face @var{face}, as a string.
@end defun
+@defun face-stipple face &optional frame
+This function returns the name of the background stipple pattern of face
+@var{face}, or @code{nil} if it doesn't have one.
+@end defun
+
@defun face-font face &optional frame
This function returns the name of the font of face @var{face}.
@end defun
This function returns the underline attribute of face @var{face}.
@end defun
-@defun face-id-number face
+@defun face-id face
This function returns the face id number of face @var{face}.
@end defun
parenthesis before giving up.
@end defvar
+@defvar blink-matching-paren-delay
+This variable specifies the number of seconds for the cursor to remain
+at the matching parenthesis. A fraction of a second often gives
+good results, but the default is 1, which works on all systems.
+@end defvar
+
@defun blink-matching-open
This function is the default value of @code{blink-paren-function}. It
assumes that point follows a character with close parenthesis syntax and
@defopt mode-line-inverse-video
This variable controls the use of inverse video for mode lines. If it
-is non-@code{nil}, then mode lines are displayed in inverse video (under
-X, this uses the face named @code{modeline}, which you can set as you
-wish). Otherwise, mode lines are displayed normally, just like text.
-The default is @code{t}.
+is non-@code{nil}, then mode lines are displayed in inverse video.
+Otherwise, mode lines are displayed normally, just like text. The
+default is @code{t}.
+
+For X window frames, this displays mode lines using the face named
+@code{modeline}, which is normally the inverse of the default face
+unless you change it.
@end defopt
@node Usual Display
The usual display conventions apply even when there is a display
table, for any character whose entry in the active display table is
@code{nil}. Thus, when you set up a display table, you need only
-specify the the characters for which you want unusual behavior.
+specify the characters for which you want unusual behavior.
These variables affect the way certain characters are displayed on the
screen. Since they change the number of columns the characters occupy,
terminal).
@end defvar
-@defvar window-system-version
-This variable distinguishes between different versions of the X Window
-System. Its value is 10 or 11 when using X; @code{nil} otherwise.
-@end defvar
-
@defvar window-setup-hook
This variable is a normal hook which Emacs runs after loading your
@file{.emacs} file and the default initialization file (if any), after
definition in a way that does not instrument. There are two ways of
evaluating forms that never instrument them: from a file with
@code{load}, and from the minibuffer with @code{eval-expression}
-(@kbd{M-ESC}).
+(@kbd{M-:}).
If Edebug detects a syntax error while instrumenting, it leaves point
at the erroneous code and signals an @code{invalid-read-syntax} error.
(@code{edebug-eval-expression}). That is, Edebug tries to minimize its
interference with the evaluation.
-@item M-@key{ESC} @var{exp} @key{RET}
+@item M-: @var{exp} @key{RET}
Evaluate expression @var{exp} in the context of Edebug itself.
@item C-x C-e
* Standard Keymaps:: List of standard keymaps.
* Standard Hooks:: List of standard hook variables.
-* Antinews:: Information about Emacs 18.
-
* Index:: Index including concepts, functions, variables,
and other terms.
* How Programs Do Loading:: The @code{load} function and others.
* Autoload:: Setting up a function to autoload.
-* Features:: Loading a library if it isn't already loaded.
+* Named Features:: Loading a library if it isn't already loaded.
* Repeated Loading:: Precautions about loading a file twice.
Byte Compilation
* Resizing Windows:: Changing the size of a window.
* Window Configurations:: Saving and restoring the state of the screen.
+Frames
+
+* Creating Frames:: Creating additional frames.
+* Multiple Displays:: Creating frames on other X displays.
+* Frame Parameters:: Controlling frame size, position, font, etc.
+* Frame Titles:: Automatic updating of frame titles.
+* Deleting Frames:: Frames last until explicitly deleted.
+* Finding All Frames:: How to examine all existing frames.
+* Frames and Windows:: A frame contains windows;
+ display of text always works through windows.
+* Minibuffers and Frames:: How a frame finds the minibuffer to use.
+* Input Focus:: Specifying the selected frame.
+* Visibility of Frames:: Frames may be visible or invisible, or icons.
+* Raising and Lowering:: Raising a frame makes it hide other X windows;
+ lowering it makes the others hide them.
+* Frame Configurations:: Saving the state of all frames.
+* Mouse Tracking:: Getting events that say when the mouse moves.
+* Mouse Position:: Asking where the mouse is, or moving it.
+* Pop-Up Menus:: Displaying a menu for the user to select from.
+* Dialog Boxes:: Displaying a box to ask yes or no.
+* Pointer Shapes:: Specifying the shape of the mouse pointer.
+* X Selections:: Transferring text to and from other X clients.
+* Color Names:: Getting the definitions of color names.
+* Resources:: Getting resource values from the server.
+* Server Data:: Getting info about the X server.
+
Positions
* Point:: The special position where editing takes place.
* Buffer End Motion:: Moving to the beginning or end of the buffer.
* Text Lines:: Moving in terms of lines of text.
* Screen Lines:: Moving in terms of lines as displayed.
-* Vertical Motion:: Implementation of @code{next-line} and
- @code{previous-line}.
* List Motion:: Moving by parsing lists and sexps.
* Skipping Characters:: Skipping characters belonging to a certain set.
* Undo:: Undoing changes to the text of a buffer.
* Auto Filling:: How auto-fill mode is implemented to break lines.
* Filling:: Functions for explicit filling.
+* Margins:: How to specify margins for filling commands.
* Sorting:: Functions for sorting parts of the buffer.
* Indentation:: Functions to insert or adjust indentation.
* Columns:: Computing horizontal positions, and using them.
an asynchronous subprocess.
* Output from Processes:: Collecting output from an asynchronous subprocess.
* Sentinels:: Sentinels run when process run-status changes.
-* TCP:: Opening network connections.
+* Network:: Opening network connections.
Receiving Output from Processes
@include locals.texi
@include maps.texi
@include hooks.texi
-@include anti.texi
@include index.texi
@code{"Buffer is read-only"}@*
@xref{Read Only Buffers}.
+@item cyclic-function-indirection
+@code{"Symbol's chain of function indirections contains a loop"}@*
+@xref{Function Indirection}.
+
@item end-of-buffer
@code{"End of buffer"}@*
@xref{Motion}.
may not be changed.@*
@xref{Constant Variables, , Variables that Never Change}.
+@item undefined-color
+@code{"Undefined color"}@*
+@xref{Color Names}.
+
@item void-function
@code{"Symbol's function definition is void"}@*
@xref{Function Cells}.
@item wrong-type-argument
@code{"Wrong type argument"}@*
@xref{Type Predicates}.
+@end table
+
+ These error types, which are all classified as special cases of
+@code{arith-error}, can occur on certain systems for invalid use of
+mathematical functions.
+
+@table @code
+@item domain-error
+@code{"Arithmetic domain error"}@*
+@xref{Math Functions}.
+
+@item overflow-error
+@code{"Arithmetic overflow error"}@*
+@xref{Math Functions}.
+
+@item range-error
+@code{"Arithmetic range error"}@*
+@xref{Math Functions}.
+
+@item singularity-error
+@code{"Arithmetic singularity error"}@*
+@xref{Math Functions}.
+
+@item underflow-error
+@code{"Arithmetic underflow error"}@*
+@xref{Math Functions}.
@end table
recursively, so that its value can be passed as an argument to the
function @code{car}.
+ Evaluation of a function call ultimately calls the function specified
+in it. @xref{Functions}. The execution of the function may itself work
+by evaluating the function definition; or the function may be a Lisp
+primitive implemented in C, or it may be a byte-compiled function
+(@pxref{Byte Compilation}).
+
@cindex environment
The evaluation of forms takes place in a context called the
@dfn{environment}, which consists of the current values and bindings of
are called @dfn{side effects}. An example of a form that produces side
effects is @code{(setq foo 1)}.
- Finally, evaluation of one particular function call, @code{byte-code},
-invokes the @dfn{byte-code interpreter} on its arguments. Although the
-byte-code interpreter is not the same as the Lisp interpreter, it uses
-the same environment as the Lisp interpreter, and may on occasion invoke
-the Lisp interpreter. (@xref{Byte Compilation}.)
-
The details of what evaluation means for each kind of form are
described below (@pxref{Forms}).
@node Eval
@section Eval
+@c ??? Perhaps this should be the last section in the chapter.
Most often, forms are evaluated automatically, by virtue of their
occurrence in a program being run. On rare occasions, you may need to
after reading a form from text being edited or getting one from a
property list. On these occasions, use the @code{eval} function.
- The functions and variables described in this section evaluate
-forms, specify limits to the evaluation process, or record recently
-returned values. Loading a file also does evaluation
-(@pxref{Loading}).
+ @strong{Note:} it is generally cleaner and more flexible to call
+functions that are stored in data structures, rather than to evaluate
+expressions stored in data structures. Using functions provides the
+ability to pass information to them as arguments.
+
+ The functions and variables described in this section evaluate forms,
+specify limits to the evaluation process, or record recently returned
+values. Loading a file also does evaluation (@pxref{Loading}).
@defun eval form
This is the basic function for performing evaluation. It evaluates
@code{max-lisp-eval-depth} (see below).
@end defun
-@cindex evaluation of buffer contents
-@deffn Command eval-current-buffer &optional stream
-This function evaluates the forms in the current buffer. It reads
-forms from the buffer and calls @code{eval} on them until the end of the
-buffer is reached, or until an error is signaled and not handled.
-
-If @var{stream} is supplied, the variable @code{standard-output} is
-bound to @var{stream} during the evaluation (@pxref{Output
-Functions}).
-
-@code{eval-current-buffer} always returns @code{nil}.
-@end deffn
-
@deffn Command eval-region start end &optional stream
This function evaluates the forms in the current buffer in the region
defined by the positions @var{start} and @var{end}. It reads forms from
@code{eval-region} always returns @code{nil}.
@end deffn
+@cindex evaluation of buffer contents
+@deffn Command eval-current-buffer &optional stream
+This is like @code{eval-region} except that it operates on the whole
+buffer.
+@end deffn
+
@defvar max-lisp-eval-depth
This variable defines the maximum depth allowed in calls to @code{eval},
@code{apply}, and @code{funcall} before an error is signaled (with error
It is common to write numbers, characters, strings, and even vectors
in Lisp code, taking advantage of the fact that they self-evaluate.
However, it is quite unusual to do this for types that lack a read
-syntax, because there's no way to write them textually; however, it is
-possible to construct Lisp expressions containing these types by means
-of a Lisp program. Here is an example:
+syntax, because there's no way to write them textually. It is possible
+to construct Lisp expressions containing these types by means of a Lisp
+program. Here is an example:
@example
@group
@section Quoting
@cindex quoting
- The special form @code{quote} returns its single argument
-``unchanged''.
+ The special form @code{quote} returns its single argument, as written,
+without evaluating it. This provides a way to include constant symbols
+and lists, which are not self-evaluating objects, in a program. (It is
+not necessary to quote self-evaluating objects such as numbers, strings,
+and vectors.)
@defspec quote object
-This special form returns @var{object}, without evaluating it. This
-provides a way to include constant symbols and lists, which are not
-self-evaluating objects, in a program. (It is not necessary to quote
-self-evaluating objects such as numbers, strings, and vectors.)
+This special form returns @var{object}, without evaluating it.
+@end defspec
@cindex @samp{'} for quoting
@cindex quoting using apostrophe
@result{} [(quote foo)]
@end group
@end example
-@end defspec
Other quoting constructs include @code{function} (@pxref{Anonymous
Functions}), which causes an anonymous lambda expression written in Lisp
-to be compiled, and @code{`} (@pxref{Backquote}), which is used to quote
+to be compiled, and @samp{`} (@pxref{Backquote}), which is used to quote
only part of a list, while computing and substituting other parts.
functions and variables that access the visited file name of a buffer or
that find an existing buffer by its visited file name.
+ In a Lisp program, if you want to look at the contents of a file but
+not alter it, the fastest way is to use @code{insert-file-contents} in a
+temporary buffer. Visiting the file is not necessary and takes longer.
+@xref{Reading from Files}.
+
@deffn Command find-file filename
This command selects a buffer visiting the file @var{filename},
using an existing buffer if there is one, and otherwise creating a
@end example
@end defun
-@deffn Command find-alternate-file filename
-This command selects a buffer visiting the file @var{filename}, then
-kills the buffer that was previously displayed in the selected window.
-It is useful if you have visited the wrong file by mistake, so that you
-can get rid of the buffer that you did not want to create, at the same
-time as you visit the file you intended.
-
-When this command is called interactively, it prompts for @var{filename}.
-@end deffn
-
@deffn Command find-file-other-window filename
This command selects a buffer visiting the file @var{filename}, but
does so in a window other than the selected window. It may use another
@end deffn
@deffn Command view-file filename
-This command visits @var{filename} in View mode, returning to the
-previous buffer when done. View mode is a mode that allows you to skim
-rapidly through the file but does not let you modify it. Entering View
-mode runs the normal hook @code{view-mode-hook}. @xref{Hooks}.
+This command visits @var{filename} in View mode, and displays it in a
+recursive edit, returning to the previous buffer when done. View mode
+is a mode that allows you to skim rapidly through the file but does not
+let you modify it. Entering View mode runs the normal hook
+@code{view-mode-hook}. @xref{Hooks}.
When @code{view-file} is called interactively, it prompts for
@var{filename}.
@strong{Please note:} @code{create-file-buffer} does @emph{not}
associate the new buffer with a file and does not select the buffer.
+It also does not use the default major mode.
@example
@group
prevents problems such as a lack of disk space from resulting in an
invalid file.
-(This feature worked differently in older Emacs versions.)
+As a side effect, backups must be made by copying.
+@xref{Rename or Copy}.
-Some modes set this non-@code{nil} locally in particular buffers.
+Some modes set this variable non-@code{nil} locally in particular
+buffers.
@end defvar
@defopt require-final-newline
and the length of the data inserted. An error is signaled if
@var{filename} is not the name of a file that can be read.
-To set up saved text properties, @code{insert-file-contents} calls the
-functions in the list @code{after-insert-file-functions}. For more
-information, see @ref{Saving Properties}.
+The function @code{insert-file-contents} checks the file contents
+against the defined file formats, and converts the file contents if
+appropriate. @xref{Format Conversion}. It also calls the functions in
+the list @code{after-insert-file-functions}; see @ref{Saving
+Properties}.
If @var{visit} is non-@code{nil}, this function additionally marks the
buffer as unmodified and sets up various fields in the buffer so that it
contents of the file. This is better than simply deleting the buffer
contents and inserting the whole file, because (1) it preserves some
marker positions and (2) it puts less data in the undo list.
-
-The function @code{insert-file-contents} checks the file contents
-against the defined file formats, and converts the file contents if
-appropriate. @xref{Format Conversion}.
@end defun
If you want to pass a file name to another process so that another
to implement @code{file-precious-flag}; don't use it yourself unless you
really know what you're doing.
-To output information about text properties, @code{write-region} calls
-the functions in the list @code{write-region-annotation-functions}. For
-more information, see @ref{Saving Properties}.
+The function @code{write-region} converts the data which it writes to
+the appropriate file formats specified by @code{buffer-file-format}.
+@xref{Format Conversion}. It also calls the functions in the list
+@code{write-region-annotate-functions}; see @ref{Saving Properties}.
Normally, @code{write-region} displays a message @samp{Wrote file
@var{filename}} in the echo area. If @var{visit} is neither @code{t}
nor @code{nil} nor a string, then this message is inhibited. This
feature is useful for programs that use files for internal purposes,
files that the user does not need to know about.
-
-The function @code{write-region} converts the data which it writes to
-the appropriate file formats specified by @code{buffer-file-format}.
-@xref{Format Conversion}.
@end deffn
@node File Locks
@comment node-name, next, previous, up
@subsection Distinguishing Kinds of Files
- This section describes how to distinguish directories and symbolic
-links from ordinary files.
+ This section describes how to distinguish various kinds of files, such
+as directories, symbolic links, and ordinary files.
@defun file-symlink-p filename
@cindex file symbolic links
@end defun
@defun file-name-sans-extension filename
-This function returns @var{filename} sans its final ``extension'', if
-any. The extension, in a file name, is the part that follows the last
-@samp{.}.
+This function returns @var{filename} minus its ``extension,'' if any.
+The extension, in a file name, is the part that starts with the last
+@samp{.} in the last name component. For example,
+
+@example
+(file-name-sans-extension "foo.lose.c")
+ @result{} "foo.lose"
+(file-name-sans-extension "big.hack/foo")
+ @result{} "big.hack/foo"
+@end example
@end defun
@node Directory Names
@defun delete-directory dirname
This function deletes the directory named @var{dirname}. The function
@code{delete-file} does not work for files that are directories; you
-must use @code{delete-directory} in that case.
+must use @code{delete-directory} for them. If the directory contains
+any files, @code{delete-directory} signals an error.
@end defun
@node Magic File Names
@code{file-name-directory}, @code{file-name-nondirectory},
@code{file-name-sans-versions}, @code{file-newer-than-file-p},
@code{file-readable-p}, @code{file-regular-p}, @code{file-symlink-p},
-@code{file-truename}, @code{file-writable-p}, @code{insert-directory},
+@code{file-truename}, @code{get-file-buffer}, @code{file-writable-p},
+@code{insert-directory},
@code{insert-file-contents}, @code{load}, @code{make-directory},
@code{make-symbolic-link}, @code{rename-file}, @code{set-file-modes},
@code{set-visited-file-modtime}, @code{unhandled-file-name-directory},
@cindex encoding file formats
@cindex decoding file formats
The variable @code{format-alist} defines a list of @dfn{file formats},
-which are textual representations used in files for the data (text,
+which describe textual representations used in files for the data (text,
text-properties, and possibly other information) in an Emacs buffer.
-Emacs performs format conversion when reading and writing files.
+Emacs performs format conversion if appropriate when reading and writing
+files.
@defvar format-alist
This list contains one format definition for each defined file format.
the text by editing it in place. Since this can change the length of the
text, @var{from-fn} should return the modified end position.
-One responsibility of @var{from-fm} is to make sure that the beginning
+One responsibility of @var{from-fn} is to make sure that the beginning
of the file no longer matches @var{regexp}. Otherwise it is likely to
get called again.
Visiting a file, with @code{find-file-noselect} or the commands that use
it, performs conversion likewise (because it calls
-@code{insert-file-contents}); but it also calls the mode function for
-each format that it decodes. It stores a list of the format names
-in the buffer-local variable @code{buffer-file-format}.
+@code{insert-file-contents}); it also calls the mode function for each
+format that it decodes. It stores a list of the format names in the
+buffer-local variable @code{buffer-file-format}.
@defvar buffer-file-format
-This variable holds a list of the file formats that were decoded in the
-course of visiting the current buffer's file. It is always local in all
+This variable states the format of the visited file. More precisely,
+this is a list of the file format names that were decoded in the course
+of visiting the current buffer's file. It is always local in all
buffers.
@end defvar
When @code{write-region} writes data into a file, it first calls the
-encoding functions for the formats listed in @code{buffer-file-format}.
+encoding functions for the formats listed in @code{buffer-file-format},
+in the order of appearance in the list.
@defun format-write-file file format
This command writes the current buffer contents into the file @var{file}
in format @var{format}, and makes that format the default for future
-saves of the buffer.
+saves of the buffer. The argument @var{format} is a list of format
+names.
@end defun
@defvar auto-save-file-format
Emacs on MS-DOS makes a distinction between text files and binary
files. This is necessary because ordinary text files on MS-DOS use a
two character sequence between lines: carriage-return and linefeed
-(CRLF). Emacs expects just a newline character (a linefeed) between
+(@sc{crlf}). Emacs expects just a newline character (a linefeed) between
lines. When Emacs reads or writes a text file on MS-DOS, it needs to
convert the line separators. This means it needs to know which files
are text files and which are binary. It makes this decision when
@dfn{terminal frames}. If you create additional ones, Emacs displays
one and only one at any given time---on the terminal screen, of course.
- When Emacs uses X for display, it does not have a terminal frame;
-instead, it starts with a single @dfn{X window frame}. It can display
-multiple X window frames at the same time, each in its own X window.
+ When Emacs communicates directly with an X server, it does not have a
+terminal frame; instead, it starts with a single @dfn{X window frame}.
+It can display multiple X window frames at the same time, each in its
+own X window.
@defun framep object
This predicate returns @code{t} if @var{object} is a frame, and
* Dialog Boxes:: Displaying a box to ask yes or no.
* Pointer Shapes:: Specifying the shape of the mouse pointer.
* X Selections:: Transferring text to and from other X clients.
-* X Connections:: Opening and closing the X server connection.
+* Color Names:: Getting the definitions of color names.
* Resources:: Getting resource values from the server.
* Server Data:: Getting info about the X server.
@end menu
The argument is an alist specifying frame parameters. Any parameters
not mentioned in @var{alist} default according to the value of the
-variable @code{default-frame-alist}; parameters not specified there
-either default from the standard X defaults file and X resources.
+variable @code{default-frame-alist}; parameters not specified even there
+default from the standard X defaults file and X resources.
The set of possible parameters depends in principle on what kind of
window system Emacs uses to display its frames. @xref{X Frame
@defun x-display-list
This returns a list that indicates which X displays Emacs has a
-connection to. The elements of the list are display names (strings).
+connection to. The elements of the list are strings, and each one is
+a display name.
@end defun
@defun x-open-connection display &optional xrm-string
does not create a frame on that display, but it permits you to check
that communication can be established with that display.
-The optional second argument @var{xrm-string} should be a string of
-resources in xrdb format, or @code{nil}. The resources, if specified,
-apply to all Emacs frames created on this display.
+The optional argument @var{resource-string}, if not @code{nil}, is a
+string of resource names and values, in the same format used in the
+@file{.Xresources} file. The values you specify override the resource
+values recorded in the X server itself; they apply to all Emacs frames
+created on this display. Here's an example of what this string might
+look like:
+
+@example
+"*BorderWidth: 3\n*InternalBorder: 2\n"
+@end example
+
+@xref{Resources}.
@end defun
@defun x-close-connection display
uses.
Frame parameters exist for the sake of window systems. A terminal frame
-has a few parameters, for compatibility's sake only. You can't change
-these parameters directly; the only ones that ever change are the height
-and width.
+has a few parameters, mostly for compatibility's sake; only the height,
+width and @code{buffer-predicate} parameters really do something.
@menu
* Parameter Access:: How to change a frame's parameters.
and applies the parameter settings in the altered value to the already
created initial frame.
-If these settings affect the frame geometry, you'll see the frame appear
-with the wrong geometry and then change to the specified one. If you
-like, you can specify the same geometry with X resources; those do take
-affect before the frame is created. @xref{Resources X,, X Resources,
-emacs, The GNU Emacs Manual}.
+If these settings affect the frame geometry and appearance, you'll see
+the frame appear with the wrong ones and then change to the specified
+ones. If that bothers you, you can specify the same geometry and
+appearance with X resources; those do take affect before the frame is
+created. @xref{Resources X,, X Resources, emacs, The GNU Emacs Manual}.
X resource settings typically apply to all frames. If you want to
specify some X resources solely for the sake of the initial frame, and
@code{initial-frame-alist} with values that match the X resources.
@end defvar
-If these parameters specify a separate minibuffer-only frame,
-and you have not created one, Emacs creates one for you.
+If these parameters specify a separate minibuffer-only frame with
+@code{(minibuffer . nil)}, and you have not created one, Emacs creates
+one for you.
@defvar minibuffer-frame-alist
This variable's value is an alist of parameter values used when creating
to the parameters for the main initial frame.
@end defvar
-@defvar special-display-frame-alist
-The variable @code{special-display-frame-alist} specifies the frame
-parameters for special display frames.
-@end defvar
-
@defvar default-frame-alist
This is an alist specifying default values of frame parameters for
subsequent Emacs frames (not the initial ones).
@end defvar
+See also @code{special-display-frame-alist}, in @ref{Choosing Window}.
+
If you use options that specify window appearance when you invoke Emacs,
they take effect by adding elements to @code{default-frame-alist}. One
-exception is @samp{-geometry}, which adds to @code{initial-frame-alist}
-instead. @xref{Command Arguments,,, emacs, The GNU Emacs Manual}.
+exception is @samp{-geometry}, which adds the specified position to
+@code{initial-frame-alist} instead. @xref{Command Arguments,,, emacs,
+The GNU Emacs Manual}.
@node X Frame Parameters
@subsection X Window Frame Parameters
A negative number @minus{}@var{pos}, or a list of the form @code{(-
@var{pos})}, actually specifies the position of the right edge of the
-window with respect to the right edge of the screen, counting toward the
-left.
+window with respect to the right edge of the screen. A positive value
+of @var{pos} counts toward the left. If the parameter is a negative
+integer @minus{}@var{pos} then @var{pos} is positive!
@item top
The screen position of the top edge, in pixels, with respect to the
A negative number @minus{}@var{pos}, or a list of the form @code{(-
@var{pos})}, actually specifies the position of the bottom edge of the
-window with respect to the bottom edge of the screen, counting toward the
-top.
+window with respect to the bottom edge of the screen. A positive value
+of @var{pos} counts toward the top. If the parameter is a negative
+integer @minus{}@var{pos} then @var{pos} is positive!
@item icon-left
The screen position of the left edge @emph{of the frame's icon}, in
@item minibuffer
Whether this frame has its own minibuffer. The value @code{t} means
yes, @code{nil} means no, @code{only} means this frame is just a
-minibuffer, a minibuffer window (in some other frame) means the new
-frame uses that minibuffer.
+minibuffer. If the value is a minibuffer window (in some other frame),
+the new frame uses that minibuffer.
@item buffer-predicate
The buffer-predicate function for this frame. The function
Any other non-@code{nil} value specifies the default bitmap icon (a
picture of a gnu); @code{nil} specifies a text icon.
+@item icon-name
+The name to use in the icon for this frame, when and if the icon
+appears. If this is @code{nil}, the frame's title is used.
+
@item foreground-color
The color to use for the image of a character. This is a string; the X
server defines the meaningful color names.
Here are some special features for working with sizes and positions:
@defun set-frame-position frame left top
-This function sets the position of the top left corner of
-@var{frame} to @var{left} and @var{top}. These arguments are measured
-in pixels, counting from the top left corner of the screen.
+This function sets the position of the top left corner of @var{frame} to
+@var{left} and @var{top}. These arguments are measured in pixels, and
+count from the top left corner of the screen. Negative parameter values
+count up or rightward from the top left corner of the screen.
@end defun
@defun frame-height &optional frame
right or bottom edge of the window to the right or bottom edge of the
screen.
-@item (+ @var{position})
+@item @code{(+ @var{position})}
This specifies the position of the left or top edge of the window
relative to the left or top edge of the screen. The integer
@var{position} may be positive or negative; a negative value specifies a
position outside the screen.
-@item (- @var{position})
+@item @code{(- @var{position})}
This specifies the position of the right or bottom edge of the window
relative to the right or bottom edge of the screen. The integer
@var{position} may be positive or negative; a negative value specifies a
Here is an example:
-@smallexample
+@example
(x-parse-geometry "35x70+0-0")
- @result{} ((width . 35) (height . 70) (left . 0) (top - 0))
-@end smallexample
+ @result{} ((width . 35) (height . 70)
+ (left . 0) (top - 0))
+@end example
@end defun
@ignore
@code{multiple-frames} so as to put the buffer name in the frame title
only when there is more than one frame.
-The variable is always local to the current X terminal and cannot be
+The variable is always local to the current terminal and cannot be
buffer-local. @xref{Multiple Displays}.
@end defvar
Exclude minibuffer-only frames.
@item @code{visible}
Consider all visible frames.
+@item 0
+Consider all visible or iconified frames.
@item a window
Consider only the frames using that particular window as their
minibuffer.
direction.
@end defun
+ See also @code{next-window} and @code{previous-window}, in @ref{Cyclic
+Window Ordering}.
+
@node Frames and Windows
@section Frames and Windows
Conversely, selecting a window for Emacs with @code{select-window} also
makes that window selected within its frame. @xref{Selecting Windows}.
+Another function that (usually) returns one of the windows in a frame is
+@code{minibuffer-window}. @xref{Minibuffer Misc}.
+
@node Minibuffers and Frames
@section Minibuffers and Frames
However, you can also create a frame with no minibuffer. Such a frame
must use the minibuffer window of some other frame. When you create the
-frame, you can specify explicitly the frame on which to find the
-minibuffer to use. If you don't, then the minibuffer is found in the
-frame which is the value of the variable
-@code{default-minibuffer-frame}. Its value should be a frame that does
-have a minibuffer.
+frame, you can specify explicitly the minibuffer window to use (in some
+other frame). If you don't, then the minibuffer is found in the frame
+which is the value of the variable @code{default-minibuffer-frame}. Its
+value should be a frame that does have a minibuffer.
If you use a minibuffer-only frame, you might want that frame to raise
when you enter the minibuffer. If so, set the variable
@defvar default-minibuffer-frame
This variable specifies the frame to use for the minibuffer window, by
-default. It is always local to the current X terminal and cannot be
+default. It is always local to the current terminal and cannot be
buffer-local. @xref{Multiple Displays}.
@end defvar
Only the selected terminal frame is actually displayed on the terminal.
Each terminal screen except for the initial one has a number, and the
number of the selected frame appears in the mode line after the word
-@samp{Emacs}.
+@samp{Emacs} (@pxref{Mode Line Variables}).
@c ??? This is not yet implemented properly.
@defun select-frame frame
@cindex iconified frame
@cindex frame visibility
-An X windo frame may be @dfn{visible}, @dfn{invisible}, or
+An X window frame may be @dfn{visible}, @dfn{invisible}, or
@dfn{iconified}. If it is visible, you can see its contents. If it is
iconified, the frame's contents do not appear on the screen, but an icon
does. If the frame is invisible, it doesn't show on the screen, not
the consequences of pushing or releasing a button at the current
position.
+In many cases, you can avoid the need to track the mouse by using
+the @code{mouse-face} text property (@pxref{Special Properties}).
+That works at a much lower level and runs more smoothly than
+Lisp-level mouse tracking.
+
@ignore
@c These are not implemented yet.
where each pane is a list of form
@example
-(@var{title} (@var{line} @var{item})...)
+(@var{title} (@var{line} . @var{item})...)
@end example
Each @var{line} should be a string, and each @var{item} should be the
implement the menu by defining a command that calls @code{x-popup-menu},
the help facilities cannot know what happens inside that command, so
they cannot give any help for the menu's items. This is the reason why
-all the menu bar items except @samp{Buffers} are implemented with menu
-keymaps (@pxref{Menu Keymaps}).
+all the menu bar items are normally implemented with menu keymaps
+(@pxref{Menu Keymaps}).
@node Dialog Boxes
@section Dialog Boxes
like the way successive kills in Emacs move down the kill ring.
@end defun
-@node X Connections
-@section X Connections
-
-You can close the connection with the X server with the function
-@code{x-close-current-connection}, and open a new one with
-@code{x-open-connection} (perhaps with a different server and display).
-
-@defun x-close-current-connection
-This function closes the connection to the X server. It deletes all
-frames, making Emacs effectively inaccessible to the user; therefore, a
-Lisp program that closes the connection should open another one.
-@end defun
-
-@defun x-open-connection display &optional resource-string
-This function opens a connection to an X server, for use of display
-@var{display}.
-
-The optional argument @var{resource-string} is a string of resource
-names and values, in the same format used in the @file{.Xresources}
-file. The values you specify override the resource values recorded in
-the X server itself. Here's an example of what this string might look
-like:
-
-@example
-"*BorderWidth: 3\n*InternalBorder: 2\n"
-@end example
-
-@xref{Resources}.
-@end defun
-
-@defun x-display-color-p
-This returns @code{t} if the connected X display has color, and
-@code{nil} otherwise.
-@end defun
+@node Color Names
+@section Color Names
@defun x-color-defined-p color
This function reports whether a color name is meaningful. It returns
@end example
@end defun
-@defun x-synchronize flag
-The function @code{x-synchronize} enables or disables synchronous
-communication with the X server. It enables synchronous communication
-if @var{flag} is non-@code{nil}, and disables it if @var{flag} is
-@code{nil}.
-
-In synchronous mode, Emacs waits for a response to each X protocol
-command before doing anything else. This is useful for debugging Emacs,
-because protocol errors are reported right away, which helps you find
-the erroneous command. Synchronous mode is not the default because it
-is much slower.
-@end defun
-
@node Resources
@section X Resources
-@defun x-get-resource attribute &optional component subclass
+@defun x-get-resource attribute class &optional component subclass
The function @code{x-get-resource} retrieves a resource value from the X
Windows defaults database.
Resources are indexed by a combination of a @dfn{key} and a @dfn{class}.
This function searches using a key of the form
@samp{@var{instance}.@var{attribute}} (where @var{instance} is the name
-under which Emacs was invoked), and using @samp{Emacs} as the class.
+under which Emacs was invoked), and using @samp{Emacs.@var{class}} as
+the class.
The optional arguments @var{component} and @var{subclass} add to the key
and the class, respectively. You must specify both of them or neither.
If you specify them, the key is
@samp{@var{instance}.@var{component}.@var{attribute}}, and the class is
-@samp{Emacs.@var{subclass}}.
+@samp{Emacs.@var{class}.@var{subclass}}.
@end defun
- @xref{Resources X, X Resources,, emacs, The GNU Emacs Manual}.
+ @xref{Resources X,, X Resources, emacs, The GNU Emacs Manual}.
@node Server Data
@section Data about the X Server
Emacs is using. Each of these functions lets you specify the display
you are interested in: the @var{display} argument can be either a
display name, or a frame (meaning use the display that frame is on). If
-you omit the @var{display} argument, that means to use the selected
-frame's display.
+you omit the @var{display} argument, or specify @code{nil}, that means
+to use the selected frame's display.
@defun x-display-screens &optional display
This function returns the number of screens associated with the display.
A @dfn{macro} is a construct defined in Lisp by the programmer. It
differs from a function in that it translates a Lisp expression that you
write into an equivalent expression to be evaluated instead of the
-original expression. @xref{Macros}, for how to define and use macros.
+original expression. Macros enable Lisp programmers to do the sorts of
+things that special forms can do. @xref{Macros}, for how to define and
+use macros.
@item command
@cindex command
@end example
@noindent
-(Such a list is called a @dfn{lambda expression} for historical reasons,
-even though it is not really an expression at all---it is not a form
-that can be evaluated meaningfully.)
+Such a list is called a @dfn{lambda expression}. In Emacs Lisp, it
+actually is valid as an expression---it evaluates to itself. In some
+other Lisp dialects, a lambda expression is not a valid expression at
+all. In either case, its main use is not to be evaluated as an
+expression, but to be called as a function.
@menu
* Lambda Components:: The parts of a lambda expression.
facilities. @xref{Documentation}, for how the @var{documentation-string} is
accessed.
- It is a good idea to provide documentation strings for all commands,
-and for all other functions in your program that users of your program
-should know about; internal functions might as well have only comments,
-since comments don't take up any room when your program is loaded.
+ It is a good idea to provide documentation strings for all the
+functions in your program, even those that are only called from within
+your program. Documentation strings are like comments, except that they
+are easier to access.
The first line of the documentation string should stand on its own,
because @code{apropos} displays just this first line. It should consist
of one or two complete sentences that summarize the function's purpose.
- The start of the documentation string is usually indented, but since
-these spaces come before the starting double-quote, they are not part of
+ The start of the documentation string is usually indented in the source file,
+but since these spaces come before the starting double-quote, they are not part of
the string. Some people make a practice of indenting any additional
lines of the string so that the text lines up in the program source.
@emph{This is a mistake.} The indentation of the following lines is
@defun defalias name definition
This special form defines the symbol @var{name} as a function, with
definition @var{definition} (which can be any valid Lisp function).
-It's best to use this rather than @code{fset} when defining a function
-in a file, because @code{defalias} records which file defined the
-function (@pxref{Unloading}), while @code{fset} does not.
+
+The proper place to use @code{defalias} is where a specific function
+name is being defined---especially where that name appears explicitly in
+the source file being loaded. This is because @code{defalias} records
+which file defined the function, just like @code{defun}
+(@pxref{Unloading}).
+
+By contrast, in programs that manipulate function definitions for other
+purposes, it is better to use @code{fset}, which does not keep such
+records.
@end defun
+ See also @code{defsubst}, which defines a function like @code{defun}
+and tells the Lisp compiler to open-code it. @xref{Inline Functions}.
+
@node Calling Functions
@section Calling Functions
@cindex function invocation
lists) and call them using @code{funcall} or @code{apply}. Functions
that accept function arguments are often called @dfn{functionals}.
- Sometimes, when you call such a function, it is useful to supply a
-no-op function as the argument. Here are two different kinds of no-op
+ Sometimes, when you call a functional, it is useful to supply a no-op
+function as the argument. Here are two different kinds of no-op
function:
@defun identity arg
@end defun
When writing a function that extends a previously defined function,
-the following idiom is often used:
+the following idiom is sometimes used:
@example
(fset 'old-foo (symbol-function 'foo))
proper results. The only way to avoid this problem is to make sure the
file is loaded before moving aside the old definition of @code{foo}.
+ But it is unmodular and unclean, in any case, for a Lisp file to
+redefine a function defined elsewhere.
+
@node Inline Functions
@section Inline Functions
@cindex inline functions
Inline functions can be used and open-coded later on in the same file,
following the definition, just like macros.
-Emacs versions prior to 19 did not have inline functions.
+@c Emacs versions prior to 19 did not have inline functions.
@node Related Topics
@section Other Topics Related to Functions
to the keys for related commands and be accurate even when a user
rearranges the key bindings. (@xref{Accessing Documentation}.)
- Within the Lisp world, a documentation string is kept with the
+ Within the Lisp world, a documentation string accessible through the
function or variable that it describes:
@itemize @bullet
@cindex @file{etc/DOC-@var{version}}
To save space, the documentation for preloaded functions and variables
(including primitive functions and autoloaded functions) is stored in
-the file @file{emacs/etc/DOC-@var{version}}. The data structure inside
-Emacs has an integer offset into the file, where the documentation
-string ought to be. The functions @code{documentation} and
-@code{documentation-property} read the documentation from the file
-@file{emacs/etc/DOC-@var{version}} when they notice the integer there;
-this is transparent to the user. Keeping the documentation strings out
-of the Emacs core image saves a significant amount of space.
-@xref{Building Emacs}.
+the file @file{emacs/etc/DOC-@var{version}}. The documentation for
+functions and variables loaded during the Emacs session from
+byte-compiled files is stored in those files (@pxref{Docs and
+Compilation}).
+
+The data structure inside Emacs has an integer offset into the file, or
+a list containing a string and an integer, in place of the documentation
+string. The functions @code{documentation} and
+@code{documentation-property} use that information to read the
+documentation from the appropriate file; this is transparent to the
+user.
For information on the uses of documentation strings, see @ref{Help, ,
Help, emacs, The GNU Emacs Manual}.
@defun documentation-property symbol property &optional verbatim
This function returns the documentation string that is recorded
@var{symbol}'s property list under property @var{property}. It
-retrieves the text from the file @file{emacs/etc/DOC-@var{version}} if
-necessary, and runs @code{substitute-command-keys} to substitute actual
-key bindings. (This substitution is not done if @var{verbatim} is
-non-@code{nil}; the @var{verbatim} argument exists only as of Emacs 19.)
+retrieves the text from a file if necessary, and runs
+@code{substitute-command-keys} to substitute actual key bindings. (This
+substitution is not done if @var{verbatim} is non-@code{nil}; the
+@var{verbatim} argument exists only as of Emacs 19.)
@smallexample
@group
@end defun
@defun documentation function &optional verbatim
-This function returns the documentation string of @var{function}.
-This function will access the documentation string if it is stored in
-the @file{emacs/etc/DOC-@var{version}} file.
-
-In addition, @code{documentation} runs @code{substitute-command-keys}
-on the resulting string, so the value contains the actual (current) key
-bindings. (This is not done if @var{verbatim} is non-@code{nil}; the
-@var{verbatim} argument exists only as of Emacs 19.)
+This function returns the documentation string of @var{function}. It
+reads the text from a file if necessary. Then (unless @var{verbatim} is
+non-@code{nil}) it calls @code{substitute-command-keys}, to return a
+value containing the actual (current) key bindings.
The function @code{documentation} signals a @code{void-function} error
if @var{function} has no function definition. However, it is ok if
@c Copyright (C) 1990, 1991, 1992, 1993 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/hooks
-@node Standard Hooks, Antinews, Standard Keymaps, Top
+@node Standard Hooks, Index, Standard Keymaps, Top
@appendix Standard Hooks
The following is a list of hook variables that let you provide
@item window-setup-hook
@item write-contents-hooks
@item write-file-hooks
-@item write-region-annotation-functions
+@item write-region-annotate-functions
@end table
@example
@group
(emacs-version)
- @result{} "GNU Emacs 19.22.1 of Fri Feb 27 1994 \
-on slug (berkeley-unix)"
+ @result{} "GNU Emacs 19.29.1 (i386-debian-linux) \
+ of Tue Jun 6 1995 on balloon"
@end group
@end example
@end deffn
@defvar emacs-build-time
- The value of this variable is the time at which Emacs was built at the
+The value of this variable is the time at which Emacs was built at the
local site.
@example
@group
emacs-build-time
- @result{} "Fri Feb 27 14:55:57 1994"
+ @result{} "Tue Jun 6 14:55:57 1995"
@end group
@end example
@end defvar
@defvar emacs-version
The value of this variable is the version of Emacs being run. It is a
-string such as @code{"19.22.1"}.
+string such as @code{"19.29.1"}.
@end defvar
The following two variables did not exist before Emacs version 19.23,
@defvar emacs-major-version
The major version number of Emacs, as an integer. For Emacs version
-19.23, the value is 19.
+19.29, the value is 19.
@end defvar
@defvar emacs-minor-version
The minor version number of Emacs, as an integer. For Emacs version
-19.23, the value is 23.
+19.29, the value is 29.
@end defvar
@node Pure Storage, Garbage Collection, Building Emacs, GNU Emacs Internals
the threshold is exhausted, but only the next time the Lisp evaluator is
called.
-The initial threshold value is 100,000. If you specify a larger
+The initial threshold value is 300,000. If you specify a larger
value, garbage collection will happen less often. This reduces the
amount of time spent garbage collecting, but increases total memory use.
You may want to do this when running a program that creates lots of
that have special slots in the buffer object. (Those slots are omitted
from this table.) @xref{Buffer-Local Variables}.
+@item base_buffer
+This field holds the buffer's base buffer (if it is an indirect buffer),
+or @code{nil}.
+
@item keymap
This field holds the buffer's local keymap. @xref{Keymaps}.
The file descriptor for the terminal that the subprocess is using. (On
some systems, there is no need to record this, so the value is
@code{nil}.)
+
+@item tty_name
+The name of the terminal that the subprocess is using,
+or @code{nil} if it is using pipes.
@end table
Throughout this manual, the phrases ``the Lisp reader'' and ``the Lisp
printer'' are used to refer to those routines in Lisp that convert
-textual representations of Lisp objects into actual objects, and vice
+textual representations of Lisp objects into actual Lisp objects, and vice
versa. @xref{Printed Representation}, for more details. You, the
person reading this manual, are thought of as ``the programmer'' and are
addressed as ``you''. ``The user'' is the person who uses Lisp programs,
@cindex boolean
@cindex false
- In Lisp, the symbol @code{nil} is overloaded with three meanings: it
+ In Lisp, the symbol @code{nil} has three separate meanings: it
is a symbol with the name @samp{nil}; it is the logical truth value
@var{false}; and it is the empty list---the list of zero elements.
When used as a variable, @code{nil} always has the value @code{nil}.
keymaps; if this is not so, the sequence of events does not form a
unit---it is not really a key sequence. In other words, removing one or
more events from the end of any valid key must always yield a prefix
-key. For example, @kbd{C-f C-f} is not a key; @kbd{C-f} is not a prefix
+key. For example, @kbd{C-f C-n} is not a key; @kbd{C-f} is not a prefix
key, so a longer sequence starting with @kbd{C-f} cannot be a key.
Note that the set of possible multi-event key sequences depends on the
Here we describe the functions for creating keymaps.
+@c ??? This should come after makr-sparse-keymap
@defun make-keymap &optional prompt
This function creates and returns a new full keymap (i.e., one
containing a vector of length 128 for defining all the @sc{ASCII}
minor modes so that they don't interfere with each other. If you do
this properly, the order will not matter.
-See also @code{minor-mode-key-binding} in @ref{Functions for Key
-Lookup}. See @ref{Keymaps and Minor Modes}, for more information about
-minor modes.
+See also @code{minor-mode-key-binding}, above. See @ref{Keymaps and
+Minor Modes}, for more information about minor modes.
@end defvar
@defvar overriding-local-map
clear @code{overriding-local-map} before looking up and executing that
key sequence. Modes that use @code{overriding-local-map} would
typically do this anyway; normally they respond to events that they do
-not handle by ``unreading'' them and and exiting.
+not handle by ``unreading'' them and exiting.
@end defvar
@node Key Lookup
The events used so far in the lookup form a complete key,
and @var{command} is its binding. @xref{What Is a Function}.
-@item @var{string}
-@itemx @var{vector}
+@item @var{array}
@cindex string in keymap
-The events used so far in the lookup form a complete key, whose
-binding is a keyboard macro. See @ref{Keyboard Macros}, for more
-information.
+The array (either a string or a vector) is a keyboard macro. The events
+used so far in the lookup form a complete key, and the array is its
+binding. See @ref{Keyboard Macros}, for more information.
@item @var{list}
@cindex list in keymap
This feature permits you to define one key as an alias for another key.
For example, an entry whose @sc{car} is the keymap called @code{esc-map}
-and whose @sc{cdr} is 32 (the code for space) means, ``Use the global
+and whose @sc{cdr} is 32 (the code for @key{SPC}) means, ``Use the global
binding of @kbd{Meta-@key{SPC}}, whatever that may be.''
@end itemize
@code{?\C-a} and @code{(hyper control left)} is equivalent to
@code{C-H-left}.
+ One advantage of using a list to represent the event type is that the
+precise numeric codes for the modifier bits don't appear in compiled
+files.
+
For the functions below, an error is signaled if @var{keymap} is not a
keymap or if @var{key} is not a string or vector representing a key
sequence. You can use event types (symbols) as shorthand for events
(global-set-key [?\C-x ?\C-\\] 'next-line)
@end smallexample
+@noindent
+or
+
+@smallexample
+(global-set-key [(control ?x) (control ?\\)] 'next-line)
+@end smallexample
+
@noindent
redefines @kbd{C-x C-\} to move down a line.
Currently Emacs does not actually use @var{help-string}; it knows only
how to ignore @var{help-string} in order to extract @var{real-binding}.
-In the future we hope to make @var{help-string} serve as extended
-documentation for the menu item, available on request.
+In the future we may use @var{help-string} as extended documentation for
+the menu item, available on request.
If @var{real-binding} is @code{nil}, then @var{string} appears in the
menu but cannot be selected.
menu item is disabled, it is displayed in a ``fuzzy'' fashion, and
cannot be selected with the mouse.
+The menu bar does not recalculate which items are enabled every time you
+look at a menu. This is because the X toolkit requires the whole tree
+of menus in advance. To force recalculation of the menu bar, call
+@code{force-mode-line-update} (@pxref{Mode Line Format}).
+
Sometimes it is useful to make menu items that use the ``same'' command
but with different enable conditions. You can do this by defining alias
commands. Here's an example that makes two aliases for
should type the corresponding character---the one whose binding is that
alternative.
+@ignore
In a menu intended for keyboard use, each menu item must clearly
indicate what character to type. The best convention to use is to make
-the character the first letter of the item string. That is something
-users will understand without being told.
+the character the first letter of the item string---that is something
+users will understand without being told. We plan to change this; by
+the time you read this manual, keyboard menus may explicitly name the
+key for each alternative.
+@end ignore
This way of using menus in an Emacs-like editor was inspired by the
Hierarkey system.
parameter must be greater than zero. Emacs uses just one line for the
menu bar itself; if you specify more than one line, the other lines
serve to separate the menu bar from the windows in the frame. We
-recommend you try 1 or 2 as the value of @code{menu-bar-lines}. @xref{X
-Frame Parameters}.
+recommend 1 or 2 as the value of @code{menu-bar-lines}. @xref{X Frame
+Parameters}.
Here's an example of setting up a menu bar item:
@example
(append '(x y) 'z)
- @result{} (x y z)
+ @result{} (x y . z)
(append '(x y) [z])
- @result{} (x y [z])
+ @result{} (x y . [z])
@end example
@noindent
sorted order. If you wish to make a sorted copy without destroying the
original, copy it first with @code{copy-sequence} and then sort.
-Sorting does not change the @sc{car}s of the cons cells in @var{list};
-each cons cell in the result contains the same element that it contained
-before. The result differs from the argument @var{list} because the
-cells themselves have been reordered.
-
Sorting does not change the @sc{car}s of the cons cells in @var{list};
the cons cell that originally contained the element @code{a} in
@var{list} still has @code{a} in its @sc{car} after sorting, but it now
@end group
@end example
-Note that @code{(delq 'b sample-list)} modifies @code{sample-list} to
-splice out the second element, but @code{(delq 'a sample-list)} does not
+Note that @code{(delq 'c sample-list)} modifies @code{sample-list} to
+splice out the third element, but @code{(delq 'a sample-list)} does not
splice anything---it just returns a shorter list. Don't assume that a
variable which formerly held the argument @var{list} now has fewer
elements, or that it still holds the original list! Instead, save the
Lisp versions do not use @code{equal} to compare elements.
@end quotation
+ See also the function @code{add-to-list}, in @ref{Setting Variables},
+for another way to add an element to a list stored in a variable.
+
@node Association Lists
@section Association Lists
@cindex association list
* How Programs Do Loading:: The @code{load} function and others.
* Autoload:: Setting up a function to autoload.
* Repeated Loading:: Precautions about loading a file twice.
-* Features:: Loading a library if it isn't already loaded.
+* Named Features:: Loading a library if it isn't already loaded.
* Unloading:: How to ``unload'' a library that was loaded.
* Hooks for Loading:: Providing code to be run when
particular libraries are loaded.
@code{autoload} creates a placeholder object for a function in a file;
trying to call the autoloading function loads the file to get the
function's real definition (@pxref{Autoload}). @code{require} loads a
-file if it isn't already loaded (@pxref{Features}). Ultimately, all
+file if it isn't already loaded (@pxref{Named Features}). Ultimately, all
these facilities call the @code{load} function to do the work.
@defun load filename &optional missing-ok nomessage nosuffix
built.
The syntax of @code{EMACSLOADPATH} is the same as used for @code{PATH};
-@samp{:} separates directory names, and @samp{.} is used for the current
-default directory. Here is an example of how to set your
-@code{EMACSLOADPATH} variable from a @code{csh} @file{.login} file:
+@samp{:} (or @samp{;}, according to the operating system) separates
+directory names, and @samp{.} is used for the current default directory.
+Here is an example of how to set your @code{EMACSLOADPATH} variable from
+a @code{csh} @file{.login} file:
@c This overfull hbox is OK. --rjc 16mar92
@smallexample
@defvar load-in-progress
This variable is non-@code{nil} if Emacs is in the process of loading a
-file, and it is @code{nil} otherwise. This is how @code{defun} and
-@code{provide} determine whether a load is in progress, so that their
-effect can be undone if the load fails.
+file, and it is @code{nil} otherwise.
@end defvar
@defvar load-read-function
@cindex autoload
The @dfn{autoload} facility allows you to make a function or macro
-available but put off loading its actual definition. The first call to
-the function automatically reads the proper file to install the real
-definition and other associated code, then runs the real definition
+known in Lisp, but put off loading the file that defines it. The first
+call to the function automatically reads the proper file to install the
+real definition and other associated code, then runs the real definition
as if it had been loaded all along.
There are two ways to set up an autoloaded function: by calling
(cons '(leif-mode " Leif") minor-mode-alist)))
@end example
+ To add an element to a list just once, use @code{add-to-list}
+(@pxref{Setting Variables}).
+
Occasionally you will want to test explicitly whether a library has
already been loaded. Here's one way to test, in a library, whether it
has been loaded before:
@example
+(defvar foo-was-loaded)
+
(if (not (boundp 'foo-was-loaded))
@var{execute-first-time-only})
If the library uses @code{provide} to provide a named feature, you can
use @code{featurep} to test whether the library has been loaded.
@ifinfo
-@xref{Features}.
+@xref{Named Features}.
@end ifinfo
-@node Features
+@node Named Features
@section Features
@cindex features
@cindex requiring features
@result{} (foo bar bish)
@end smallexample
-If the file isn't completely loaded, due to an error in the evaluating
-its contents, any function definitions or @code{provide} calls that
-occurred during the load are undone. @xref{Autoload}.
+When a file is loaded to satisfy an autoload, and it stops due to an
+error in the evaluating its contents, any function definitions or
+@code{provide} calls that occurred during the load are undone.
+@xref{Autoload}.
@end defun
@defun require feature &optional filename
It undefines all functions, macros, and variables defined in that
library with @code{defconst}, @code{defvar}, @code{defun},
@code{defmacro}, @code{defsubst} and @code{defalias}. It then restores
-any autoloads formerly associated with those symbols.
+any autoloads formerly associated with those symbols. (Loading
+saves these in the @code{autoload} property of the symbol.)
Ordinarily, @code{unload-feature} refuses to unload a library on which
other loaded libraries depend. (A library @var{a} depends on library
the library is loaded. To do (2), you must load the library (preferably
with @code{require}).
-But it is to use @code{eval-after-load} in your personal customizations
+But it is ok to use @code{eval-after-load} in your personal customizations
if you don't feel they must meet the design standards of programs to be
released.
@item buffer-display-table
@pxref{Display Tables}
+@item buffer-file-format
+@pxref{Format Conversion}
+
@item buffer-file-name
@pxref{Buffer File Name}
@item buffer-file-type
@pxref{Files and MS-DOS}
+@item buffer-invisibility-spec
+@pxref{Invisible Text}
+
@item buffer-offer-save
@pxref{Saving Buffers}
@item paragraph-start
@pxref{Standard Regexps}
+@item point-before-scroll
+Used for communication between mouse commands and scroll-bar commands.
+
@item require-final-newline
@pxref{Insertion}
Byte-compiling a file executes any @code{require} calls at top-level
in the file. This is in case the file needs the required packages for
proper compilation. One way to ensure that necessary macro definitions
-are available during compilation is to require the file that defines
-them. @xref{Features}.
+are available during compilation is to require the files that define
+them (@pxref{Named Features}). To avoid loading the macro definition files
+when someone @emph{runs} the compiled program, write
+@code{eval-when-compile} around the @code{require} calls (@pxref{Eval
+During Compile}).
@node Defining Macros
@section Defining Macros
It is possible to use an anonymous Lisp macro just like an anonymous
function, but this is never done, because it does not make sense to pass
-an anonymous macro to mapping functions such as @code{mapcar}. In
-practice, all Lisp macros have names, and they are usually defined with
-the special form @code{defmacro}.
+an anonymous macro to functionals such as @code{mapcar}. In practice,
+all Lisp macros have names, and they are usually defined with the
+special form @code{defmacro}.
@defspec defmacro name argument-list body-forms@dots{}
@code{defmacro} defines the symbol @var{name} as a macro that looks
Macros often need to construct large list structures from a mixture of
constants and nonconstant parts. To make this easier, use the macro
-@code{`} (often called @dfn{backquote}).
+@samp{`} (often called @dfn{backquote}).
Backquote allows you to quote a list, but selectively evaluate
elements of that list. In the simplest case, it is identical to the
@end example
@findex , @r{(with Backquote)}
-The special marker @code{,} inside of the argument to backquote
+The special marker @samp{,} inside of the argument to backquote
indicates a value that isn't constant. Backquote evaluates the
-argument of @code{,} and puts the value in the list structure:
+argument of @samp{,} and puts the value in the list structure:
@example
@group
@findex ,@@ @r{(with Backquote)}
@cindex splicing (with backquote)
You can also @dfn{splice} an evaluated value into the resulting list,
-using the special marker @code{,@@}. The elements of the spliced list
+using the special marker @samp{,@@}. The elements of the spliced list
become elements at the same level as the other elements of the resulting
-list. The equivalent code without using @code{`} is often unreadable.
+list. The equivalent code without using @samp{`} is often unreadable.
Here are some examples:
@example
@end example
@quotation
-Before Emacs version 19.29, @code{`} used a different syntax which
+Before Emacs version 19.29, @samp{`} used a different syntax which
required an extra level of parentheses around the entire backquote
-construct. Likewise, each @code{,} or @code{,@@} substition required an
-extra level of parentheses surrounding both the @code{,} or @code{,@@}
+construct. Likewise, each @samp{,} or @samp{,@@} substition required an
+extra level of parentheses surrounding both the @samp{,} or @samp{,@@}
and the following expression. The old syntax required whitespace
-between the @code{`}, @code{,} or @code{,@@} and the following
+between the @samp{`}, @samp{,} or @samp{,@@} and the following
expression.
This syntax is still accepted, but no longer recommended except for
(defmacro for (var from init to final do &rest body)
"Execute a simple \"for\" loop.
For example, (for i from 1 to 10 do (print i))."
- (` (let (((, var) (, init)))
- (while (<= (, var) (, final))
- (,@@ body)
- (inc (, var))))))
+ `(let ((,var ,init))
+ (while (<= ,var ,final)
+ ,@@body
+ (inc ,var))))
@end group
@end smallexample
@group
(defmacro for (var from init to final do &rest body)
"Execute a simple for loop: (for i from 1 to 10 do (print i))."
- (` (let (((, var) (, init))
- (max (, final)))
- (while (<= (, var) max)
- (,@@ body)
- (inc (, var))))))
+ `(let ((,var ,init)
+ (max ,final))
+ (while (<= ,var max)
+ ,@@body
+ (inc ,var))))
@end group
@end smallexample
"Execute a simple for loop: (for i from 1 to 10 do (print i))."
@end group
@group
- (` (let (((, var) (, init))
- (max (, final)))
- (while (<= (, var) max)
- (,@@ body)
- (inc (, var))))))
+ `(let ((,var ,init)
+ (max ,final))
+ (while (<= ,var max)
+ ,@@body
+ (inc ,var))))
@end group
@end smallexample
@end ifinfo
(defmacro for (var from init to final do &rest body)
"Execute a simple for loop: (for i from 1 to 10 do (print i))."
(let ((tempvar (make-symbol "max")))
- (` (let (((, var) (, init))
- ((, tempvar) (, final)))
- (while (<= (, var) (, tempvar))
- (,@@ body)
- (inc (, var)))))))
+ `(let ((,var ,init)
+ (,tempvar ,final))
+ (while (<= ,var ,tempvar)
+ ,@@body
+ (inc ,var)))))
@end group
@end smallexample
A full keymap used by Command History mode.
@item ctl-x-4-map
+@vindex ctl-x-4-map
A sparse keymap for subcommands of the prefix @kbd{C-x 4}.
+@item ctl-x-5-map
+@vindex ctl-x-5-map
+A sparse keymap for subcommands of the prefix @kbd{C-x 5}.
+
@item ctl-x-map
+@vindex ctl-x-map
A full keymap for @kbd{C-x} commands.
@item debugger-mode-map
@vindex dired-mode-map
A full keymap for @code{dired-mode} buffers.
-@item doctor-mode-map
-@vindex doctor-mode-map
-A sparse keymap used by Doctor mode.
-
@item edit-abbrevs-map
@vindex edit-abbrevs-map
A sparse keymap used in @code{edit-abbrevs}.
@vindex emacs-lisp-mode-map
A sparse keymap used by Emacs Lisp mode.
+@item facemenu-menu
+@vindex facemenu-menu
+The keymap that displays the Text Properties menu.
+
+@item facemenu-background-menu
+@vindex facemenu-background-menu
+The keymap that displays the Background Color submenu of the Text
+Properties menu.
+
+@item facemenu-face-menu
+@vindex facemenu-face-menu
+The keymap that displays the Face submenu of the Text Properties menu.
+
+@item facemenu-foreground-menu
+@vindex facemenu-foreground-menu
+The keymap that displays the Foreground Color submenu of the Text
+Properties menu.
+
+@item facemenu-indentation-menu
+@vindex facemenu-indentation-menu
+The keymap that displays the Indentation submenu of the Text Properties menu.
+
+@item facemenu-justification-menu
+@vindex facemenu-justification-menu
+The keymap that displays the Justification submenu of the Text
+Properties menu.
+
+@item facemenu-special-menu
+@vindex facemenu-special-menu
+The keymap that displays the Special Props submenu of the Text
+Properties menu.
+
@item function-key-map
@vindex function-key-map
The keymap for translating keypad and function keys.@*
A sparse keymap containing Info commands.
@item isearch-mode-map
+@vindex isearch-mode-map
A keymap that defines the characters you can type within incremental
search.
@vindex lisp-mode-map
A sparse keymap used by Lisp mode.
+@item menu-bar-edit-menu
+@vindex menu-bar-edit-menu
+The keymap which displays the Edit menu in the menu bar.
+
+@item menu-bar-files-menu
+@vindex menu-bar-files-menu
+The keymap which displays the Files menu in the menu bar.
+
+@item menu-bar-help-menu
+@vindex menu-bar-help-menu
+The keymap which displays the Help menu in the menu bar.
+
+@item menu-bar-search-menu
+@vindex menu-bar-search-menu
+The keymap which displays the Search menu in the menu bar.
+
+@item menu-bar-tools-menu
+@vindex menu-bar-tools-menu
+The keymap which displays the Tools menu in the menu bar.
+
@item mode-specific-map
+@vindex mode-specific-map
The keymap for characters following @kbd{C-c}. Note, this is in the
global map. This map is not actually mode specific: its name was chosen
to be informative for the user in @kbd{C-h b} (@code{display-bindings}),
A local keymap used by Occur mode.
@item query-replace-map
+@vindex query-replace-map
A local keymap used for responses in @code{query-replace} and related
commands; also for @code{y-or-n-p} and @code{map-y-or-n-p}. The functions
that use this map do not support prefix keys; they look up one event at a
@defopt transient-mark-mode
@cindex Transient Mark mode
-This variable enables Transient Mark mode, in which every
-buffer-modifying primitive sets @code{deactivate-mark}. The consequence
-of this is that commands that modify the buffer normally make the mark
-inactive.
+This variable if non-@code{nil} enables Transient Mark mode, in which
+every buffer-modifying primitive sets @code{deactivate-mark}. The
+consequence of this is that commands that modify the buffer normally
+make the mark inactive.
@end defopt
@defvar deactivate-mark
Like other buffers, a minibuffer may use any of several local keymaps
(@pxref{Keymaps}); these contain various exit commands and in some cases
-completion commands. @xref{Completion}.
+completion commands (@pxref{Completion}).
@itemize @bullet
@item
primitive for minibuffer input is @code{read-from-minibuffer}; it can do
either one.
+ In most cases, you should not call minibuffer input functions in the
+middle of a Lisp function. Instead, do all minibuffer input as part of
+reading the arguments for a command, in the @code{interactive} spec.
+@xref{Defining Commands}.
+
@defun read-from-minibuffer prompt-string &optional initial-contents keymap read hist
This function is the most general way to get input through the
minibuffer. By default, it accepts arbitrary text and returns it as a
@defvar minibuffer-local-ns-map
This built-in variable is the keymap used as the minibuffer local keymap
in the function @code{read-no-blanks-input}. By default, it makes the
-following bindings:
+following bindings, in addition to those of @code{minibuffer-local-map}:
@table @asis
-@item @key{LFD}
-@code{exit-minibuffer}
-
@item @key{SPC}
@cindex @key{SPC} in minibuffer
@code{exit-minibuffer}
@cindex @key{TAB} in minibuffer
@code{exit-minibuffer}
-@item @key{RET}
-@code{exit-minibuffer}
-
-@item @kbd{C-g}
-@code{abort-recursive-edit}
-
@item @kbd{?}
@cindex @kbd{?} in minibuffer
@code{self-insert-and-exit}
-
-@item @kbd{M-n}
-@code{next-history-element}
-
-@item @kbd{M-p}
-@code{previous-history-element}
-
-@item @kbd{M-r}
-@code{next-matching-history-element}
-
-@item @kbd{M-s}
-@code{previous-matching-history-element}
@end table
@end defvar
This section describes the higher-level convenient functions for
reading certain sorts of names with completion.
+ In most cases, you should not call these functions in the middle of a
+Lisp function. When possible, do all minibuffer input as part of
+reading the arguments for a command, in the @code{interactive} spec.
+@xref{Defining Commands}.
+
@defun read-buffer prompt &optional default existing
This function reads the name of a buffer and returns it as a string.
The argument @var{default} is the default name to use, the value to
whether @code{read-file-name} starts by placing the name of the default
directory in the minibuffer, plus the initial file name if any. If the
value of this variable is @code{nil}, then @code{read-file-name} does
-not place any initial input in the minibuffer. In that case, the
+not place any initial input in the minibuffer (unless you specify
+initial input with the @var{initial} argument). In that case, the
default directory is still used for completion of relative file names,
but is not displayed.
@end itemize
It would be consistent and clean for completion functions to allow
-lambda expressions (lists tha are functions) as well as function
+lambda expressions (lists that are functions) as well as function
symbols as @var{collection}, but this is impossible. Lists as
completion tables are already assigned another meaning---as alists. It
would be unreliable to fail to handle an alist normally because it is
expression).
@end deffn
+@defun minibuffer-prompt
+This function returns the prompt string of the currently active
+minibuffer. If no minibuffer is active, it returns @code{nil}.
+@end defun
+
+@defun minibuffer-prompt-width
+This function returns the display width of the prompt string of the
+currently active minibuffer. If no minibuffer is active, it returns 0.
+@end defun
+
@defvar minibuffer-setup-hook
This is a normal hook that is run whenever the minibuffer is entered.
@xref{Hooks}.
returns zero.
@end defun
-@defun minibuffer-prompt
-This function returns the prompt string of the currently active
-minibuffer. If no minibuffer is active, it returns @code{nil}.
-@end defun
-
-@defun minibuffer-prompt-width
-This function returns the display width of the prompt string of the
-currently active minibuffer. If no minibuffer is active, it returns 0.
-@end defun
-
@defopt enable-recursive-minibuffers
If this variable is non-@code{nil}, you can invoke commands (such as
@code{find-file}) that use minibuffers even while in the minibuffer
If a command name has a property @code{enable-recursive-minibuffers}
that is non-@code{nil}, then the command can use the minibuffer to read
arguments even if it is invoked from the minibuffer. The minibuffer
-command @code{next-matching-history-element} (normally bound to
-@kbd{M-s} in the minibuffer) uses this feature.
+command @code{next-matching-history-element} (normally @kbd{M-s} in the
+minibuffer) uses this feature.
@smallexample
@group
(make-local-variable 'paragraph-start)
+ ;; @r{Having @samp{^} is not clean, but @code{page-delimiter}}
+ ;; @r{has them too, and removing those is a pain.}
(setq paragraph-start (concat "^$\\|" page-delimiter))
@dots{}
@end group
@end deffn
@deffn Command normal-mode &optional find-file
- This function establishes the proper major mode and local variable
+This function establishes the proper major mode and local variable
bindings for the current buffer. First it calls @code{set-auto-mode},
then it runs @code{hack-local-variables} to parse, and bind or
evaluate as appropriate, any local variables.
- If the @var{find-file} argument to @code{normal-mode} is
+If the @var{find-file} argument to @code{normal-mode} is
non-@code{nil}, @code{normal-mode} assumes that the @code{find-file}
function is calling it. In this case, it may process a local variables
-list at the end of the file. The variable @code{enable-local-variables}
-controls whether to do so.
+list at the end of the file and in the @samp{-*-} line. The variable
+@code{enable-local-variables} controls whether to do so.
- If you run @code{normal-mode} interactively, the argument
+If you run @code{normal-mode} interactively, the argument
@var{find-file} is normally @code{nil}. In this case,
@code{normal-mode} unconditionally processes any local variables list.
@xref{File variables, , Local Variables in Files, emacs, The GNU Emacs
Manual}, for the syntax of the local variables section of a file.
@cindex file mode specification error
- @code{normal-mode} uses @code{condition-case} around the call to the
+@code{normal-mode} uses @code{condition-case} around the call to the
major mode function, so errors are caught and reported as a @samp{File
mode specification error}, followed by the original error message.
@end deffn
ask the user what to do for each file. The default value is @code{t}.
@end defopt
+@defvar ignored-local-variables
+This variable holds a list of variables that should not be
+set by a local variables list. Any value specified
+for one of these variables is ignored.
+@end defvar
+
+In addition to this list, any variable whose name has a non-@code{nil}
+@code{risky-local-variable} property is also ignored.
+
@defopt enable-local-eval
This variable controls processing of @samp{Eval:} in local variables
lists in files being visited. A value of @code{t} means process them
the current buffer's major mode (if that is suitable).
The low-level primitives for creating buffers do not use this function,
-but medium-level commands such as @code{switch-to-buffer} should use it
-whenever they create buffers.
+but medium-level commands such as @code{switch-to-buffer} and
+@code{find-file-noselect} use it whenever they create buffers.
@end defun
@defvar initial-major-mode
Often the biggest problem in implementing a minor mode is finding a
way to insert the necessary hook into the rest of Emacs. Minor mode
-keymaps make this easier in Emacs 19 than it used to be.
+keymaps make this easier than it used to be.
@menu
* Minor Mode Conventions:: Tips for writing a minor mode.
list whose @sc{car} is such an integer or symbol; it should turn the
mode off otherwise.
-Here is an example taken from the definition of @code{overwrite-mode}.
-It shows the use of @code{overwrite-mode} as a variable that enables or
+Here is an example taken from the definition of @code{transient-mark-mode}.
+It shows the use of @code{transient-mark-mode} as a variable that enables or
disables the mode's behavior, and also shows the proper way to toggle,
enable or disable the minor mode based on the raw prefix argument value.
@smallexample
@group
-(setq overwrite-mode
- (if (null arg) (not overwrite-mode)
+(setq transient-mark-mode
+ (if (null arg) (not transient-mark-mode)
(> (prefix-numeric-value arg) 0)))
@end group
@end smallexample
@node Keymaps and Minor Modes
@subsection Keymaps and Minor Modes
-As of Emacs version 19, each minor mode can have its own keymap, which is
-active when the mode is enabled. @xref{Active Keymaps}. To set up a
-keymap for a minor mode, add an element to the alist
-@code{minor-mode-map-alist}.
+ Each minor mode can have its own keymap, which is active when the mode
+is enabled. To set up a keymap for a minor mode, add an element to the
+alist @code{minor-mode-map-alist}. @xref{Active Keymaps}.
@cindex @code{self-insert-command}, minor modes
One use of minor mode keymaps is to modify the behavior of certain
substituting your own definition of @code{self-insert-command} for the
standard one. The editor command loop handles this function specially.)
-@defvar minor-mode-map-alist
-This variable is an alist of elements that look like this:
-
-@example
-(@var{variable} . @var{keymap})
-@end example
-
-@noindent
-where @var{variable} is the variable that indicates whether the minor
-mode is enabled, and @var{keymap} is the keymap. The keymap
-@var{keymap} is active whenever @var{variable} has a non-@code{nil}
-value.
-
-Note that elements of @code{minor-mode-map-alist} do not have the same
-structure as elements of @code{minor-mode-alist}. The map must be the
-@sc{cdr} of the element; a list with the map as the second element will
-not do.
-
-What's more, the keymap itself must appear in the @sc{cdr}. It does not
-work to store a variable in the @sc{cdr} and make the map the value of
-that variable.
-
-When more than one minor mode keymap is active, their order of priority
-is the order of @code{minor-mode-map-alist}. But you should design
-minor modes so that they don't interfere with each other. If you do
-this properly, the order will not matter.
-@end defvar
-
@node Mode Line Format
@section Mode Line Format
@cindex mode line
@code{mode-line-format} is a buffer-local variable that holds a
template used to display the mode line of the current buffer. All
-windows for the same buffer use the same @code{mode-line-format} and the
-mode lines will appear the same (except for scrolling percentages and
+windows for the same buffer use the same @code{mode-line-format} and
+their mode lines appear the same (except for scrolling percentages and
line numbers).
The mode line of a window is normally updated whenever a different
@code{mode-line-format}. The data structure is called a @dfn{mode line
construct}, and it is built in recursive fashion out of simpler mode line
constructs. The same data structure is used for constructing
-frame titles (pxref{Frame Titles}).
+frame titles (@pxref{Frame Titles}).
@defvar mode-line-format
The value of this variable is a mode line construct with overall
@cindex percent symbol in mode line
@item @var{string}
A string as a mode line construct is displayed verbatim in the mode line
-except for @dfn{@code{%}-constructs}. Decimal digits after the @code{%}
+except for @dfn{@code{%}-constructs}. Decimal digits after the @samp{%}
specify the field width for space filling on the right (i.e., the data
is left justified). @xref{%-Constructs}.
use the same variables that appear in the default value (@pxref{Mode
Line Variables}), rather than duplicating their contents or displaying
the information in another fashion. This way, customizations made by
-the user, by libraries (such as @code{display-time}) and by major modes
-via changes to those variables remain effective.
+the user or by Lisp programs (such as @code{display-time} and major
+modes) via changes to those variables remain effective.
@cindex Shell mode @code{mode-line-format}
Here is an example of a @code{mode-line-format} that might be
"%n"
")%]----"
@group
- (line-number-mode "L%l--")
+ '(line-number-mode "L%l--")
'(-3 . "%p")
"-%-"))
@end group
This variable holds the value of the mode-line construct that displays
whether the current buffer is modified.
-The default value of @code{mode-line-modified} is
-@code{("--%1*%1*-")}. This means that the mode line displays
-@samp{--**-} if the buffer is modified, @samp{-----} if the buffer is
-not modified, and @samp{--%%-} if the buffer is read only.
+The default value of @code{mode-line-modified} is @code{("--%1*%1+-")}.
+This means that the mode line displays @samp{--**-} if the buffer is
+modified, @samp{-----} if the buffer is not modified, @samp{--%%-} if
+the buffer is read only, and @samp{--%*--} if the buffer is read only
+and modified.
Changing this variable does not force an update of the mode line.
@end defvar
@defvar mode-line-buffer-identification
This variable identifies the buffer being displayed in the window. Its
-default value is @code{("Emacs: %17b")}, which means that it displays
-@samp{Emacs:} followed by seventeen characters of the buffer name. You
-may want to change this in modes such as Rmail that do not behave like a
+default value is @code{("%F: %17b")}, which means that it usually
+displays @samp{Emacs:} followed by seventeen characters of the buffer
+name. (In a terminal frame, it displays the frame name instead of
+@samp{Emacs}; this has the effect of showing the frame number.) You may
+want to change this in modes such as Rmail that do not behave like a
``normal'' Emacs.
@end defvar
@example
@group
minor-mode-alist
-@result{} ((abbrev-mode " Abbrev")
- (overwrite-mode " Ovwrt")
+@result{} ((vc-mode vc-mode)
+ (abbrev-mode " Abbrev")
+ (overwrite-mode overwrite-mode)
(auto-fill-function " Fill")
- (defining-kbd-macro " Def"))
+ (defining-kbd-macro " Def")
+ (isearch-mode isearch-mode))
@end group
@end example
-@noindent
-(In earlier Emacs versions, @code{auto-fill-function} was called
-@code{auto-fill-hook}.)
-
- @code{minor-mode-alist} is not buffer-local. The variables mentioned
+@code{minor-mode-alist} is not buffer-local. The variables mentioned
in the alist should be buffer-local if the minor mode can be enabled
separately in each buffer.
@end defvar
mode-name
@end group
@group
+ mode-line-process
minor-mode-alist
"%n"
- mode-line-process
")%]----"
+ (line-number-mode "L%l--")
(-3 . "%p")
"-%-")
@end group
The name shows you that the hook is abnormal and that you should look at
its documentation string to see how to use it properly.
- Most major modes run hooks as the last step of initialization. This
-makes it easy for a user to customize the behavior of the mode, by
-overriding the local variable assignments already made by the mode. But
-hooks are used in other contexts too. For example, the hook
-@code{suspend-hook} runs just before Emacs suspends itself
-(@pxref{Suspending Emacs}).
+ Major mode functions are supposed to run a hook called the @dfn{mode
+hook} as the last step of initialization. This makes it easy for a user
+to customize the behavior of the mode, by overriding the local variable
+assignments already made by the mode. But hooks are used in other
+contexts too. For example, the hook @code{suspend-hook} runs just
+before Emacs suspends itself (@pxref{Suspending Emacs}).
- Here's an expression you can put in your @file{.emacs} file to turn on
-Auto Fill mode when in Lisp Interaction mode:
+ Here's an expression that uses a mode hook to turn on Auto Fill mode
+when in Lisp Interaction mode:
@example
(add-hook 'lisp-interaction-mode-hook 'turn-on-auto-fill)
(setq c++-mode-hook c-mode-hook)
@end group
-@end example
-
- Finally, here is an example of how to use the Text mode hook to
-provide a customized mode line for buffers in Text mode, displaying the
-default directory in addition to the standard components of the
-mode line. (This may cause the mode line to run out of space if you
-have very long file names or display the time and load.)
-
-@example
-@group
-(add-hook 'text-mode-hook
- (function (lambda ()
- (setq mode-line-format
-@end group
- '(mode-line-modified
- "Emacs: %14b"
- " "
- default-directory
- " "
- global-mode-string
- "%[("
- mode-name
- minor-mode-alist
-@group
- "%n"
- mode-line-process
- ") %]---"
- (-3 . "%p")
- "-%-")))))
-@end group
@end example
At the appropriate time, Emacs uses the @code{run-hooks} function to
-run particular hooks. This function calls the hook functions you have
-added with @code{add-hooks}.
+run particular hooks. This function calls the hook functions that have
+been added with @code{add-hook}.
@defun run-hooks &rest hookvar
This function takes one or more hook variable names as arguments, and
called. If it is a list, the elements are called, in order.
The hook functions are called with no arguments.
-For example, here's how @code{emacs-lisp-hooks} runs its mode hook:
+For example, here's how @code{emacs-lisp-mode} runs its mode hook:
@example
(run-hooks 'emacs-lisp-mode-hook)
@example
(defvar fuzz-factor 1.0e-6)
(defun approx-equal (x y)
- (< (/ (abs (- x y))
- (max (abs x) (abs y)))
- fuzz-factor))
+ (or (and (= x 0) (= y 0))
+ (< (/ (abs (- x y))
+ (max (abs x) (abs y)))
+ fuzz-factor)))
@end example
@cindex CL note---integers vrs @code{eq}
@defun round number
This returns @var{number}, converted to an integer by rounding towards the
-nearest integer.
+nearest integer. Rounding a value equidistant between two integers
+may choose the integer closer to zero, or it may prefer an even integer,
+depending on your machine.
@end defun
@node Arithmetic Operations
@result{} 5
@end example
-This function is not analogous to the C operator @code{++}---it does
-not increment a variable. It just computes a sum. Thus,
+This function is not analogous to the C operator @code{++}---it does not
+increment a variable. It just computes a sum. Thus, if we continue,
@example
foo
@defun + &rest numbers-or-markers
This function adds its arguments together. When given no arguments,
-@code{+} returns 0. It does not check for overflow.
+@code{+} returns 0.
@example
(+)
When @code{-} has a single argument, the value is the negative of the
argument. When there are multiple arguments, @code{-} subtracts each of
the @var{other-numbers-or-markers} from @var{number-or-marker},
-cumulatively. If there are no arguments, the result is 0. This
-function does not check for overflow.
+cumulatively. If there are no arguments, the result is 0.
@example
(- 10 1 2 3 4)
@defun * &rest numbers-or-markers
This function multiplies its arguments together, and returns the
-product. When given no arguments, @code{*} returns 1. It does
-not check for overflow.
+product. When given no arguments, @code{*} returns 1.
@example
(*)
@end example
@noindent
-always equals @var{dividend}, subject to rounding error if
-either argument is floating point.
+always equals @var{dividend}, subject to rounding error if either
+argument is floating point. For @code{floor}, see @ref{Numeric
+Conversions}.
@end defun
@node Rounding Operations
the left produces a number that is twice the value of the previous
number.
-The function @code{lsh}, like all Emacs Lisp arithmetic functions, does
-not check for overflow, so shifting left can discard significant bits
-and change the sign of the number. For example, left shifting
-134,217,727 produces @minus{}2 on a 28-bit machine:
-
-@example
-(lsh 134217727 1) ; @r{left shift}
- @result{} -2
-@end example
-
-In binary, in the 28-bit implementation, the argument looks like this:
-
-@example
-@group
-;; @r{Decimal 134.217,727}
-0111 1111 1111 1111 1111 1111 1111
-@end group
-@end example
-
-@noindent
-which becomes the following when left shifted:
-
-@example
-@group
-;; @r{Decimal @minus{}2}
-1111 1111 1111 1111 1111 1111 1110
-@end group
-@end example
-
-Shifting the pattern of bits two places to the left produces results
+Shifting a pattern of bits two places to the left produces results
like this (with 8-bit binary numbers):
@example
@end group
@end example
-On the other hand, shifting the pattern of bits one place to the right
-looks like this:
+On the other hand, shifting one place to the right looks like this:
@example
@group
@end example
@noindent
-As the example illustrates, shifting the pattern of bits one place to
-the right divides the value of the binary number by two, rounding downward.
+As the example illustrates, shifting one place to the right divides the
+value of a positive integer by two, rounding downward.
+
+The function @code{lsh}, like all Emacs Lisp arithmetic functions, does
+not check for overflow, so shifting left can discard significant bits
+and change the sign of the number. For example, left shifting
+134,217,727 produces @minus{}2 on a 28-bit machine:
+
+@example
+(lsh 134217727 1) ; @r{left shift}
+ @result{} -2
+@end example
+
+In binary, in the 28-bit implementation, the argument looks like this:
+
+@example
+@group
+;; @r{Decimal 134.217,727}
+0111 1111 1111 1111 1111 1111 1111
+@end group
+@end example
+
+@noindent
+which becomes the following when left shifted:
+
+@example
+@group
+;; @r{Decimal @minus{}2}
+1111 1111 1111 1111 1111 1111 1110
+@end group
+@end example
@end defun
@defun ash integer1 count
@code{ash} gives the same results as @code{lsh} except when
@var{integer1} and @var{count} are both negative. In that case,
-@code{ash} puts a one in the leftmost position, while @code{lsh} puts
-a zero in the leftmost position.
+@code{ash} puts ones in the empty bit positions on the left, while
+@code{lsh} puts zeros in those bit positions.
Thus, with @code{ash}, shifting the pattern of bits one place to the right
looks like this:
This function returns a pseudo-random integer. Repeated calls return a
series of pseudo-random integers.
-If @var{limit} is @code{nil}, then the value may in principle be any
-integer. However, on machines where integers have more than 32 bits,
-the possible values may be limited to the interval
-@tex
-$[0,2^{32})$.
-@end tex
-@ifinfo
-[0,2**32).
-@end ifinfo
-
If @var{limit} is a positive integer, the value is chosen to be
-nonnegative and less than @var{limit} (only in Emacs 19).
+nonnegative and less than @var{limit}.
If @var{limit} is @code{t}, it means to choose a new seed based on the
current time of day and on Emacs's process @sc{id} number.
part of the Lisp objects which represent the program within the Lisp
system.
+ The @samp{#@@@var{count}} construct, which skips the next @var{count}
+characters, is useful for program-generated comments containing binary
+data. The Emacs Lisp byte compiler uses this in its output files
+(@pxref{Byte Compilation}). It isn't meant for source files, however.
+
@xref{Comment Tips}, for conventions for formatting comments.
@node Programming Types
characters that exist in @sc{ASCII}, but for keyboard input purposes,
you can turn any character into a control character with @samp{C-}. The
character codes for these non-@sc{ASCII} control characters include the
-2**22 bit as well as the code for the corresponding non-control
+@iftex
+$2^{26}$
+@end iftex
+@ifinfo
+2**26
+@end ifinfo
+bit as well as the code for the corresponding non-control
character. Ordinary terminals have no way of generating non-@sc{ASCII}
control characters, but you can generate them straightforwardly using an
X terminal.
- You can think of the @key{DEL} character as @kbd{Control-?}:
+ For historical reasons, Emacs treats the @key{DEL} character as
+the control equivalent of @kbd{?}:
@example
?\^? @result{} 127 ?\C-? @result{} 127
@end example
+@noindent
+As a result, it is currently not possible to represent the character
+@kbd{Control-?}, which is a meaningful input character under X. It is
+not easy to change this as various Lisp files refer to @key{DEL} in this
+way.
+
For representing control characters to be found in files or strings,
we recommend the @samp{^} syntax; for control characters in keyboard
input, we prefer the @samp{C-} syntax. This does not affect the meaning
@cindex meta characters
A @dfn{meta character} is a character typed with the @key{META}
modifier key. The integer that represents such a character has the
-2**23 bit set (which on most machines makes it a negative number). We
+@iftex
+$2^{27}$
+@end iftex
+@ifinfo
+2**27
+@end ifinfo
+bit set (which on most machines makes it a negative number). We
use high bits for this and other modifiers to make possible a wide range
of basic character codes.
- In a string, the 2**7 bit indicates a meta character, so the meta
+ In a string, the
+@iftex
+$2^{7}$
+@end iftex
+@ifinfo
+2**7
+@end ifinfo
+bit indicates a meta character, so the meta
characters that can fit in a string have codes in the range from 128 to
255, and are the meta versions of the ordinary @sc{ASCII} characters.
(In Emacs versions 18 and older, this convention was used for characters
The case of an ordinary letter is indicated by its character code as
part of @sc{ASCII}, but @sc{ASCII} has no way to represent whether a
-control character is upper case or lower case. Emacs uses the 2**21 bit
-to indicate that the shift key was used for typing a control character.
-This distinction is possible only when you use X terminals or other
-special terminals; ordinary terminals do not indicate the distinction to
-the computer in any way.
+control character is upper case or lower case. Emacs uses the
+@iftex
+$2^{25}$
+@end iftex
+@ifinfo
+2**25
+@end ifinfo
+bit to indicate that the shift key was used for typing a control
+character. This distinction is possible only when you use X terminals
+or other special terminals; ordinary terminals do not indicate the
+distinction to the computer in any way.
@cindex hyper characters
@cindex super characters
The X Window System defines three other modifier bits that can be set
in a character: @dfn{hyper}, @dfn{super} and @dfn{alt}. The syntaxes
for these bits are @samp{\H-}, @samp{\s-} and @samp{\A-}. Thus,
-@samp{?\H-\M-\A-x} represents @kbd{Alt-Hyper-Meta-x}. Numerically, the
-bit values are 2**18 for alt, 2**19 for super and 2**20 for hyper.
+@samp{?\H-\M-\A-x} represents @kbd{Alt-Hyper-Meta-x}.
+@iftex
+Numerically, the
+bit values are $2^{22}$ for alt, $2^{23}$ for super and $2^{24}$ for hyper.
+@end iftex
+@ifinfo
+Numerically, the
+bit values are 2**22 for alt, 2**23 for super and 2**24 for hyper.
+@end ifinfo
@cindex @samp{?} in character constant
@cindex question mark in character constant
@cindex CL note---case of letters
@quotation
@b{Common Lisp note:} In Common Lisp, lower case letters are always
-``folded'' to upper case, unless they are explicitly escaped. This is
-in contrast to Emacs Lisp, in which upper case and lower case letters
-are distinct.
+``folded'' to upper case, unless they are explicitly escaped. In Emacs
+Lisp, upper case and lower case letters are distinct.
@end quotation
Here are several examples of symbol names. Note that the @samp{+} in
the fifth example is escaped to prevent it from being read as a number.
-This is not necessary in the last example because the rest of the name
+This is not necessary in the sixth example because the rest of the name
makes it invalid as a number.
@example
characters.)
If you use the @samp{\M-} syntax to indicate a meta character in a
-string constant, this sets the 2**7 bit of the character in the string.
+string constant, this sets the
+@iftex
+$2^{7}$
+@end iftex
+@ifinfo
+2**7
+@end ifinfo
+bit of the character in the string.
This is not the same representation that the meta modifier has in a
character on its own (not inside a string). @xref{Character Type}.
function to be called. @xref{Byte Compilation}, for information about
the byte compiler.
-The printed representation for a byte-code function object is like that
-for a vector, with an additional @samp{#} before the opening @samp{[}.
+The printed representation and read syntax for a byte-code function
+object is like that for a vector, with an additional @samp{#} before the
+opening @samp{[}.
@node Autoload Type
@subsection Autoload Type
@item
a local variable binding list (@pxref{Buffer-Local Variables}).
+
+@item
+a list of overlays (@pxref{Overlays}).
+
+@item
+text properties for the text in the buffer (@pxref{Text Properties}).
@end itemize
@noindent
behavior of programs in different buffers, without actually changing the
programs.
- Buffers have no read syntax. They print in hash notation with the
+ A buffer may be @dfn{indirect}, which means it shares the text
+of another buffer. @xref{Indirect Buffers}.
+
+ Buffers have no read syntax. They print in hash notation, showing the
buffer name.
@example
A @dfn{display table} specifies how to display each character code.
Each buffer and each window can have its own display table. A display
-table is actually a vector of length 261. @xref{Display Tables}.
+table is actually a vector of length 262. @xref{Display Tables}.
@node Overlay Type
@subsection Overlay Type
appearance of a part of a buffer. It contains markers delimiting a
range of the buffer, plus a property list (a list whose elements are
alternating property names and values). Overlays are used to present
-parts of the buffer temporarily in a different display style.
-
- @xref{Overlays}, for how to create and use overlays. They have no
-read syntax, and print in hash notation, giving the buffer name and
+parts of the buffer temporarily in a different display style. They have
+no read syntax, and print in hash notation, giving the buffer name and
range of positions.
+ @xref{Overlays}, for how to create and use overlays.
+
@node Type Predicates
@section Type Predicates
@cindex predicates
@result{} nil
@end group
@end example
+
+Two distinct buffers are never @code{equal}, even if their contents
+are the same.
@end defun
The test for equality is implemented recursively, and circular lists may
using a window system. This library's name is
@file{term/@var{windowsystem}-win.el}.
+@item
+It processes the initial options. (Some of them are handled
+even earlier than this.)
+
@item
It initializes the X window frame and faces, if appropriate.
that with @code{inhibit-startup-echo-area-message}.
@item
-It processes any remaining command line arguments.
+It processes the action arguments from the command line.
@item
It runs @code{term-setup-hook}.
loads this @emph{before} the user's init file. You can inhibit the
loading of this file with the option @samp{-no-site-file}.
+@defvar site-run-file
+This variable specifies the site-customization file to load
+before the user's init file. Its normal value is @code{"site-start"}.
+@end defvar
+
If there is a great deal of code in your @file{.emacs} file, you
should move it into another file named @file{@var{something}.el},
byte-compile it (@pxref{Byte Compilation}), and make your @file{.emacs}
system, the user's @sc{uid}, and so on.
@defvar system-type
-The value of this variable is a symbol indicating the type of
-operating system Emacs is operating on. Here is a table of the symbols
-for the operating systems that Emacs can run on up to version 19.1.
+The value of this variable is a symbol indicating the type of operating
+system Emacs is operating on. Here is a table of the possible values:
@table @code
@item aix-v3
@item berkeley-unix
Berkeley BSD.
+@item dgux
+Data General DGUX operating system.
+
+@item gnu
+A GNU system using the GNU HURD and Mach.
+
@item hpux
-Hewlett-Packard operating system.
+Hewlett-Packard HPUX operating system.
@item irix
Silicon Graphics Irix system.
@item linux
-The free Linux operating system.
+A GNU system using the Linux kernel.
+
+@item ms-dos
+Microsoft MS-DOS ``operating system.''
+
+@item next-mach
+NeXT Mach-based system.
@item rtu
Masscomp RTU, UCB universe.
@item vax-vms
VAX VMS.
+@item windows-nt
+Microsoft windows NT.
+
@item xenix
SCO Xenix 386.
@end table
variable with @code{let} is also reasonable practice.
@end deffn
-@defvar path-separator
-This variable holds a string which says which character separates
-directories in a search path (as found in an environment variable). Its
-value is @code{":"} for Unix and GNU systems, and @code{";"} for MS-DOS
-and Windows NT.
-@end defvar
-
@defvar process-environment
This variable is a list of strings, each describing one environment
variable. The functions @code{getenv} and @code{setenv} work by means
@end smallexample
@end defvar
+@defvar path-separator
+This variable holds a string which says which character separates
+directories in a search path (as found in an environment variable). Its
+value is @code{":"} for Unix and GNU systems, and @code{";"} for MS-DOS
+and Windows NT.
+@end defvar
+
@defvar invocation-name
This variable holds the program name under which Emacs was invoked. The
value is a string, and does not include a directory name.
variables are also useful for constructing frame titles (@pxref{Frame
Titles}).
-@defvar user-real-login-name
-This variable holds the same value that the function
-@code{user-real-login-name} returns. The variable lets you alter the value;
-also, you can use variables for constructing frame titles.
-@end defvar
-
-@defvar user-full-name
-This variable holds the same value that the function
-@code{user-full-name} returns. The variable lets you alter the value;
-also, you can use variables for constructing frame titles.
-@end defvar
-
@defun user-real-uid
This function returns the real @sc{uid} of the user.
This function returns the current time and date as a humanly-readable
string. The format of the string is unvarying; the number of characters
used for each part is always the same, so you can reliably use
-@code{substring} to extract pieces of it. However, it would be wise to
-count the characters from the beginning of the string rather than from
-the end, as additional information may be added at the end.
+@code{substring} to extract pieces of it. It is wise to count the
+characters from the beginning of the string rather than from the end, as
+additional information may be added at the end.
@c Emacs 19 feature
The argument @var{time-value}, if given, specifies a time to format
-instead of the current time. The argument should be a cons cell
-containing two integers, or a list whose first two elements are
-integers. Thus, you can use times obtained from @code{current-time}
-(see below) and from @code{file-attributes} (@pxref{File Attributes}).
+instead of the current time. The argument should be a list whose first
+two elements are integers. Thus, you can use times obtained from
+@code{current-time} (see below) and from @code{file-attributes}
+(@pxref{File Attributes}).
@example
@group
@item %c
This is a synonym for @samp{%x %X}.
@item %C
-This has a locale-specific meaning. In the C locale, it is equivalent
-to @samp{%A, %B %e, %Y}.
+This has a locale-specific meaning. In the default locale (named C), it
+is equivalent to @samp{%A, %B %e, %Y}.
@item %d
This stands for the day of month, zero-padded.
@item %D
This stands for the week of the year (01-52), assuming that weeks
start on Monday.
@item %x
-This has a locale-specific meaning. In the C locale, it is equivalent
-to @samp{%D}.
+This has a locale-specific meaning. In the default locale (named C), it
+is equivalent to @samp{%D}.
@item %X
-This has a locale-specific meaning. In the C locale, it is equivalent
-to @samp{%T}.
+This has a locale-specific meaning. In the default locale (named C), it
+is equivalent to @samp{%T}.
@item %y
This stands for the year without century (00-99).
@item %Y
@end defun
@defun decode-time time
-This function converts a time value into calendrical form. The return
-value is a list of nine elements, as follows:
+This function converts a time value into calendrical information. The
+return value is a list of nine elements, as follows:
@example
(@var{seconds} @var{minutes} @var{hour} @var{day} @var{month} @var{year} @var{dow} @var{dst} @var{zone})
@item dst
@code{t} if daylight savings time is effect, otherwise @code{nil}.
@item zone
-An integer indicating the number of seconds east of Greenwich.
+An integer indicating the time zone, as the number of seconds east of
+Greenwich.
@end table
Note that Common Lisp has different meanings for @var{dow} and
@defun encode-time seconds minutes hour day month year &optional zone
This function is the inverse of @code{decode-time}. It converts seven
-items of calendrical data into a time value.
-
-For the meanings of the arguments, see the table above under
-@code{decode-time}.
+items of calendrical data into a time value. For the meanings of the
+arguments, see the table above under @code{decode-time}.
Year numbers less than 100 are treated just like other year numbers. If
you them to stand for years above 1900, you must alter them yourself
@end defun
@node Timers
-@section Timers
+@section Timers for Delayed Execution
You can set up a timer to call a function at a specified future time.
@defun set-input-mode interrupt flow meta quit-char
This function sets the mode for reading keyboard input. If
@var{interrupt} is non-null, then Emacs uses input interrupts. If it is
-@code{nil}, then it uses @sc{cbreak} mode.
+@code{nil}, then it uses @sc{cbreak} mode. When Emacs communicates
+directly with X, it ignores this argument and uses interrupts if that is
+the way it knows how to communicate.
If @var{flow} is non-@code{nil}, then Emacs uses @sc{xon/xoff} (@kbd{C-q},
@kbd{C-s}) flow control for output to the terminal. This has no effect except
flow control for output to the terminal. This value has no effect
unless @var{interrupt} is non-@code{nil}.
@item meta
-is non-@code{t} if Emacs treats the eighth bit of input characters as
+is @code{t} if Emacs treats the eighth bit of input characters as
the meta bit; @code{nil} means Emacs clears the eighth bit of every
input character; any other value means Emacs uses all eight bits as the
basic character code.
@end table
@end defun
-@defvar meta-flag
-This variable used to control whether to treat the eight bit in keyboard
-input characters as the @key{Meta} bit. @code{nil} meant no, and
-anything else meant yes. This variable existed in Emacs versions 18 and
-earlier but no longer exists in Emacs 19; use @code{set-input-mode}
-instead.
-@end defvar
-
@node Translating Input
@subsection Translating Input Events
@cindex translating input events
Each time the user types a keyboard key, it is altered as if the
modifier keys specified in the bit mask were held down.
-When you use X windows, the program can ``press'' any of the modifier
+When using X windows, the program can ``press'' any of the modifier
keys in this way. Otherwise, only the @key{CTL} and @key{META} keys can
be virtually pressed.
@end defvar
model 33 teletype with a paper tape punch (which is very old), @kbd{C-s}
and @kbd{C-q} were sent by the computer to turn the punch on and off!
- GNU Emacs version 19 provides a convenient way of enabling flow
-control if you want it: call the function @code{enable-flow-control}.
+ As X servers and other window systems replace character-only
+terminals, this problem is gradually being cured. For the mean time,
+Emacs provides a convenient way of enabling flow control if you want it:
+call the function @code{enable-flow-control}.
@defun enable-flow-control
This function enables use of @kbd{C-s} and @kbd{C-q} for output flow
Any Lisp program output that would normally go to the echo area,
either using @code{message} or using @code{prin1}, etc., with @code{t}
-as the stream, goes instead to Emacs's standard output descriptor when
+as the stream, goes instead to Emacs's standard error descriptor when
in batch mode. Thus, Emacs behaves much like a noninteractive
application program. (The echo area output that Emacs itself normally
generates, such as command echoing, is suppressed entirely.)
Like other positions, point designates a place between two characters
(or before the first character, or after the last character), rather
-than a particular character. Many terminals display the cursor over the
-character that immediately follows point; on such terminals, point is
-actually before the character on which the cursor sits.
+than a particular character. Usually terminals display the cursor over
+the character that immediately follows point; point is actually before
+the character on which the cursor sits.
@cindex point with narrowing
The value of point is a number between 1 and the buffer size plus 1.
* Buffer End Motion:: Moving to the beginning or end of the buffer.
* Text Lines:: Moving in terms of lines of text.
* Screen Lines:: Moving in terms of lines as displayed.
-* Vertical Motion:: Implementation of @code{next-line} and
- @code{previous-line}.
* List Motion:: Moving by parsing lists and sexps.
* Skipping Characters:: Skipping characters belonging to a certain set.
@end menu
@c ================
@end ignore
-@defvar cache-long-line-scans
-This variable determines whether Emacs should use caches to handle long
-lines more quickly. This variable is buffer-local, in all buffers.
-
- Normally, the line-motion functions work by scanning the buffer for
-newlines. Columnar operations (like @code{move-to-column} and
-@code{compute-motion}) also work by scanning the buffer, summing
-character widths as they go. This works well for ordinary text, but if
-the buffer's lines are very long (say, more than 500 characters), these
-motion functions will take longer to execute. Emacs may also take
-longer to update the display.
-
- If @code{cache-long-line-scans} is non-@code{nil}, these motion
-functions cache the results of their scans, and consult the cache to
-avoid rescanning regions of the buffer until the text is modified. The
-caches are most beneficial when they prevent the most searching---that
-is, when the buffer contains long lines and large regions of characters
-with the same, fixed screen width.
-
- When @code{cache-long-line-scans} is non-@code{nil}, processing short
-lines will become slightly slower (because of the overhead of consulting
-the cache), and the caches will use memory roughly proportional to the
-number of newlines and characters whose screen width varies.
-
- The caches require no explicit maintenance; their accuracy is
-maintained internally by the Emacs primitives. Enabling or disabling
-the cache should not affect the behavior of any of the motion functions;
-it should only affect their performance.
-@end defvar
-
Also see the functions @code{bolp} and @code{eolp} in @ref{Near Point}.
These functions do not move point, but test whether it is already at the
beginning or end of a line.
The argument @var{width} is the number of columns available to display
text; this affects handling of continuation lines. Use the value
-returned by @code{window-width} for the window of your choice.
+returned by @code{window-width} for the window of your choice;
+normally, use @code{(window-width @var{window})}.
The argument @var{offsets} is either @code{nil} or a cons cell of the
form @code{(@var{hscroll} . @var{tab-offset})}. Here @var{hscroll} is
beginning of the first screen line. @xref{Minibuffer Misc}.
@end defun
-@node Vertical Motion
-@comment node-name, next, previous, up
-@subsection The User-Level Vertical Motion Commands
-@cindex goal column
-@cindex vertical text line motion
-@findex next-line
-@findex previous-line
-
- A goal column is useful if you want to edit text such as a table in
-which you want to move point to a certain column on each line. The goal
-column affects the vertical text line motion commands, @code{next-line}
-and @code{previous-line}. @xref{Basic,, Basic Editing Commands, emacs,
-The GNU Emacs Manual}.
-
-@defopt goal-column
-This variable holds an explicitly specified goal column for vertical
-line motion commands. If it is an integer, it specifies a column, and
-these commands try to move to that column on each line. If it is
-@code{nil}, then the commands set their own goal columns. Any other
-value is invalid.
-@end defopt
-
-@defvar temporary-goal-column
-This variable holds the temporary goal column during a sequence of
-consecutive vertical line motion commands. It is overridden by
-@code{goal-column} if that is non-@code{nil}. It is set each time a
-vertical motion command is invoked, unless the previous command was also
-a vertical motion command.
-@end defvar
-
-@defopt track-eol
-This variable controls how the vertical line motion commands operate
-when starting at the end of a line. If @code{track-eol} is
-non-@code{nil}, then vertical motion starting at the end of a line will
-keep to the ends of lines (instead of keeping to a particular column).
-This means moving to the end of each line moved onto. The value of
-@code{track-eol} has no effect if point is not at the end of a line when
-the first vertical motion command is given.
-
-@code{track-eol} has its effect by telling line motion commands to set
-@code{temporary-goal-column} to 9999 instead of to the current column.
-@end defopt
-
@node List Motion
@comment node-name, next, previous, up
@subsection Moving over Balanced Expressions
* Output from Processes:: Collecting output from an asynchronous subprocess.
* Sentinels:: Sentinels run when process run-status changes.
* Transaction Queues:: Transaction-based communication with subprocesses.
-* TCP:: Opening network connections.
+* Network:: Opening network connections.
@end menu
@node Subprocess Creation
a synchronous subprocess are text or binary. Text data requires
translation between the end-of-line convention used within Emacs
(a single newline character) and the convention used outside Emacs
-(the two-character sequence, CRLF).
+(the two-character sequence, @sc{crlf}).
The variable @code{binary-process-input} applies to input sent to the
subprocess, and @code{binary-process-output} applies to output received
means the data is text, and calls for conversion.
@defvar binary-process-input
-If this variable is @code{nil}, convert newlines to CRLF sequences in
+If this variable is @code{nil}, convert newlines to @sc{crlf} sequences in
the input to a synchronous subprocess.
@end defvar
@defvar binary-process-output
-If this variable is @code{nil}, convert CRLF sequences to newlines in
+If this variable is @code{nil}, convert @sc{crlf} sequences to newlines in
the output from a synchronous subprocess.
@end defvar
@cindex pipes
@cindex @sc{pty}s
This variable controls the type of device used to communicate with
-asynchronous subprocesses. If it is @code{nil}, then pipes are used.
-If it is @code{t}, then @sc{pty}s are used (or pipes if @sc{pty}s are
-not supported).
+asynchronous subprocesses. If it is non-@code{nil}, then @sc{pty}s are
+used, when available. Otherwise, pipes are used.
@sc{pty}s are usually preferable for processes visible to the user, as
in Shell mode, because they allow job control (@kbd{C-c}, @kbd{C-z},
explicitly. @xref{Match Data}.
A filter function that writes the output into the buffer of the
-process should check whether the process is still alive. If it tries to
+process should check whether the buffer is still alive. If it tries to
insert into a dead buffer, it will get an error. If the buffer is dead,
@code{(buffer-name (process-buffer @var{process}))} returns @code{nil}.
returns after that much time whether or not there has been any
subprocess output.
+The argument @var{seconds} need not be an integer. If it is a floating
+point number, this function waits for a fractional number of seconds.
+Some systems support only a whole number of seconds; on these systems,
+@var{seconds} is rounded down. If the system doesn't support waiting
+fractions of a second, you get an error if you specify nonzero
+@var{millisec}.
+
Not all operating systems support waiting periods other than multiples
of a second; on those that do not, you get an error if you specify
nonzero @var{millisec}.
sentinel, bind @code{inhibit-quit} to @code{nil}. @xref{Quitting}.
A sentinel that writes the output into the buffer of the process
-should check whether the process is still alive. If it tries to insert
+should check whether the buffer is still alive. If it tries to insert
into a dead buffer, it will get an error. If the buffer is dead,
@code{(buffer-name (process-buffer @var{process}))} returns @code{nil}.
- In earlier Emacs versions, every sentinel that did regexp searching or
-matching had to explicitly save and restore the match data. Now Emacs
-does this automatically; sentinels never need to do it explicitly.
-@xref{Match Data}.
-
If an error happens during execution of a sentinel, it is caught
automatically, so that it doesn't stop the execution of whatever
programs was running when the sentinel was started. However, if
off. This makes it possible to use the Lisp debugger to debug the
sentinel. @xref{Debugger}.
+ In earlier Emacs versions, every sentinel that did regexp searching or
+matching had to explicitly save and restore the match data. Now Emacs
+does this automatically; sentinels never need to do it explicitly.
+@xref{Match Data}.
+
@defun set-process-sentinel process sentinel
This function associates @var{sentinel} with @var{process}. If
@var{sentinel} is @code{nil}, then the process will have no sentinel.
Transaction queues are implemented by means of a filter function.
@xref{Filter Functions}.
-@node TCP
-@section TCP
+@node Network
+@section Network Connections
+@cindex network connection
@cindex TCP
- Emacs Lisp programs can open TCP connections to other processes on the
-same machine or other machines. A network connection is handled by Lisp
+ Emacs Lisp programs can open TCP network connections to other processes on
+the same machine or other machines. A network connection is handled by Lisp
much like a subprocess, and is represented by a process object.
However, the process you are communicating with is not a child of the
Emacs process, so you can't kill it or send it signals. All you can do
You can distinguish process objects representing network connections
from those representing subprocesses with the @code{process-status}
-function. @xref{Process Information}.
+function. It always returns either @code{open} or @code{closed} for a
+network connection, and it never returns either of those values for a
+real subprocess. @xref{Process Information}.
@defun open-network-stream name buffer-or-name host service
This function opens a TCP connection for a service to a host. It
or match operation. It returns the entire text if @var{count} is zero,
or just the portion corresponding to the @var{count}th parenthetical
subexpression, if @var{count} is positive. If @var{count} is out of
-range, the value is @code{nil}.
+range, or if that subexpression didn't match anything, the value is
+@code{nil}.
If the last such operation was done against a string with
@code{string-match}, then you should pass the same string as the
was matched by the last search. It replaces that text with
@var{replacement}.
-If @var{string} is @code{nil}, @code{replace-match} does the replacement
-by editing the buffer; it leaves point at the end of the replacement
-text, and returns @code{t}. If @var{string} is a string, it does the
-replacement by constructing and returning a new string.
+If you did the last search in a buffer, you should specify @code{nil}
+for @var{string}. Then @code{replace-match} does the replacement by
+editing the buffer; it leaves point at the end of the replacement text,
+and returns @code{t}.
+
+If you did the search in a string, pass the same string as @var{string}.
+Then @code{replace-match} does the replacement by constructing and
+returning a new string.
If @var{fixedcase} is non-@code{nil}, then the case of the replacement
text is not changed; otherwise, the replacement text is converted to a
You can save and restore the match data with @code{save-match-data}:
-@defspec save-match-data body@dots{}
+@defmac save-match-data body@dots{}
This special form executes @var{body}, saving and restoring the match
data around it.
-@end defspec
+@end defmac
You can use @code{set-match-data} together with @code{match-data} to
imitate the effect of the special form @code{save-match-data}. This is
match always starts at the beginning of a line; they should not use
@samp{^} to anchor the match. Most often, the paragraph commands do
check for a match only at the beginning of a line, which means that
-@samp{^} would be superfluous. When there is a left margin, they accept
-matches that start after the left margin. In that case, a @samp{^}
-would be incorrect.
+@samp{^} would be superfluous. When there is a nonzero left margin,
+they accept matches that start after the left margin. In that case, a
+@samp{^} would be incorrect. However, a @samp{^} is harmless in modes
+where a left margin is never used.
@defvar paragraph-separate
This is the regular expression for recognizing the beginning of a line
An @dfn{array} is a single primitive object that has a slot for each
elements. All the elements are accessible in constant time, but the
-length of an existing array cannot be changed. Both strings and vectors
-are arrays.
+length of an existing array cannot be changed. Strings and vectors are
+the two types of arrays.
A list is a sequence of elements, but it is not a single primitive
object; it is made of cons cells, one cell per element. Finding the
| | List | | Array | |
| | | | ________ _______ | |
| |______| | | | | | | |
- | | | String | | Vector| | |
+ | | | Vector | | String| | |
| | |________| |_______| | |
| |______________________| |
|___________________________________|
@end group
@end example
-This function duplicates @code{aref} (@pxref{Array Functions}) and
-@code{nth} (@pxref{List Elements}), except that it works for any kind of
-sequence.
+This function generalizes @code{aref} (@pxref{Array Functions}) and
+@code{nth} (@pxref{List Elements}).
@end defun
@node Arrays
@code{aref} and @code{aset}, respectively (@pxref{Array Functions}).
@end itemize
- In principle, if you wish to have an array of characters, you could use
-either a string or a vector. In practice, we always choose strings for
-such applications, for four reasons:
+ In principle, if you wish to have an array of text characters, you
+could use either a string or a vector. In practice, we always choose
+strings for such applications, for four reasons:
@itemize @bullet
@item
buffer the way you can insert a string. @xref{Strings and Characters}.
@end itemize
+ By contrast, for an array of keyboard input characters (such as a key
+sequence), a vector may be necessary, because many keyboard input
+characters are outside the range that will fit in a string. @xref{Key
+Sequence Input}.
+
@node Array Functions
@section Functions that Operate on Arrays
and @code{b}.
However, these two operations are not precisely inverses. There are
-two kinds of exceptions:
+three kinds of exceptions:
@itemize @bullet
@item
@samp{1} and @samp{01} represent the same integer, and @samp{(a b)} and
@samp{(a .@: (b))} represent the same list. Reading will accept any of
the alternatives, but printing must choose one of them.
+
+@item
+Comments can appear at certain points in the middle of an object's
+read sequence without affecting the result of reading it.
@end itemize
@node Input Streams
In Emacs 18, reading a symbol discarded the delimiter terminating the
symbol. Thus, point would end up at the beginning of @samp{contents}
rather than after @samp{the}. The Emacs 19 behavior is superior because
-it correctly handles input such as @samp{bar(foo)}, where the delimiter
-that ends one object is needed as the beginning of another object.
+it correctly handles input such as @samp{bar(foo)}, where the
+open-parenthesis that ends one object is needed as the beginning of
+another object.
Here is an example of reading from a stream that is a marker,
initially positioned at the beginning of the buffer shown. The value
representation of meta and other modifiers for keyboard input
characters.
+ Strings are useful for holding regular expressions. You can also
+match regular expressions against strings (@pxref{Regexp Search}). The
+functions @code{match-string} (@pxref{Simple Match Data}) and
+@code{replace-match} (@pxref{Replacing Match}) are useful for
+decomposing and modifying strings based on regular expression matching.
+
Like a buffer, a string can contain text properties for the characters
in it, as well as the characters themselves. @xref{Text Properties}.
+All the Lisp primitives that copy text from strings to buffers or other
+strings also copy the properties of the characters being copied.
@xref{Text}, for information about functions that display strings or
copy them into buffers. @xref{Character Type}, and @ref{String Type},
@end defun
@defun substring string start &optional end
- This function returns a new string which consists of those characters
+This function returns a new string which consists of those characters
from @var{string} in the range from (and including) the character at the
index @var{start} up to (but excluding) the character at the index
@var{end}. The first character is at index zero.
But we recommend @code{copy-sequence} for this purpose (@pxref{Sequence
Functions}).
+If the characters copied from @var{string} have text properties, the
+properties are copied into the new string also. @xref{Text Properties}.
+
A @code{wrong-type-argument} error is signaled if either @var{start} or
@var{end} is not an integer or @code{nil}. An @code{args-out-of-range}
error is signaled if @var{start} indicates a character following
@cindex copying strings
@cindex concatenating strings
This function returns a new string consisting of the characters in the
-arguments passed to it. The arguments may be strings, lists of numbers,
-or vectors of numbers; they are not themselves changed. If
-@code{concat} receives no arguments, it returns an empty string.
+arguments passed to it (along with their text properties, if any). The
+arguments may be strings, lists of numbers, or vectors of numbers; they
+are not themselves changed. If @code{concat} receives no arguments, it
+returns an empty string.
@example
(concat "abc" "-def")
lambda expression thus becomes the function definition of the symbol.
(The term ``function definition'', meaning the contents of the function
cell, is derived from the idea that @code{defun} gives the symbol its
-definition as a function.) @xref{Functions}.
+definition as a function.) @code{defsubst} and @code{defalias} are two
+other ways of defining a function. @xref{Functions}.
@code{defmacro} defines a symbol as a macro. It creates a macro
object and stores it in the function cell of the symbol. Note that a
that cell can hold only one Lisp object at any given time.
@xref{Macros}.
- In GNU Emacs Lisp, a definition is not required in order to use a
-symbol as a variable or function. Thus, you can make a symbol a global
+ In Emacs Lisp, a definition is not required in order to use a symbol
+as a variable or function. Thus, you can make a symbol a global
variable with @code{setq}, whether you define it first or not. The real
purpose of definitions is to guide programmers and programming tools.
They inform programmers who read the code that certain symbols are
@end defun
@defun plist-put plist property value
-This stores @var{value} as the value of the @var{property} property
-stored in the property list @var{plist}. It may modify @var{plist}
-destructively, or it may construct new list structure without altering
-the old. The function returns the modified property list, so you can
-store that back in the place where you got @var{plist}. For example,
+This stores @var{value} as the value of the @var{property} property in
+the property list @var{plist}. It may modify @var{plist} destructively,
+or it may construct new list structure without altering the old. The
+function returns the modified property list, so you can store that back
+in the place where you got @var{plist}. For example,
@example
(setq my-plist '(bar t foo 4))
@end ifinfo
A syntax table is a vector of 256 elements; it contains one entry for
-each of the 256 @sc{ASCII} characters of an 8-bit byte. Each element is
+each of the 256 possible characters in an 8-bit byte. Each element is
an integer that encodes the syntax of the character in question.
Syntax tables are used only for moving across text, not for the Emacs
@node Standard Syntax Tables
@section Some Standard Syntax Tables
- Each of the major modes in Emacs has its own syntax table. Here are
-several of them:
+ Most of the major modes in Emacs have their own syntax tables. Here
+are several of them:
@defun standard-syntax-table
This function returns the standard syntax table, which is the syntax
@cindex buffer contents
Throughout this chapter, ``text'' refers to the characters in the
-buffer.
+buffer, together with their properties (when relevant).
@menu
* Near Point:: Examining text in the vicinity of point.
* Maintaining Undo:: How to enable and disable undo information.
How to control how much information is kept.
* Filling:: Functions for explicit filling.
+* Margins:: How to specify margins for filling commands.
* Auto Filling:: How auto-fill mode is implemented to break lines.
* Sorting:: Functions for sorting parts of the buffer.
* Columns:: Computing horizontal positions, and using them.
within the substrings.
This function ignores case when comparing characters
-if @code{case-fold-search} is non-@code{nil}.
+if @code{case-fold-search} is non-@code{nil}. It always ignores
+text properties.
Suppose the current buffer contains the text @samp{foobarbar
haha!rara!}; then in this example the two substrings are @samp{rbar }
(compare-buffer-substring nil 6 11 nil 16 21)
@result{} 2
@end example
-
-This function does not exist in Emacs version 18 and earlier.
@end defun
@node Insertion
-@section Insertion
+@section Inserting Text
@cindex insertion of text
@cindex text insertion
Insertion functions signal an error if the current buffer is
read-only.
+ These functions copy text characters from strings and buffers along
+with their properties. The inserted characters have exactly the same
+properties as the characters they were copied from. By contrast,
+characters specified as separate arguments, not part of a string or
+buffer, inherit their text properties from the neighboring text.
+
@defun insert &rest args
This function inserts the strings and/or characters @var{args} into the
current buffer, at point, moving point forward. In other words, it
at point, and another earlier in the line. @code{newline} does not
auto-fill if @var{number-of-newlines} is non-@code{nil}.
+This command indents to the left margin if that is not zero.
+@xref{Margins}.
+
The value returned is @code{nil}. In an interactive call, @var{count}
is the numeric prefix argument.
@end deffn
@end defvar
@node Deletion
-@section Deletion of Text
+@section Deleting Text
@cindex deletion vs killing
Deletion means removing part of the text in a buffer, without saving
If there is a fill prefix, and the second of the lines being joined
starts with the prefix, then @code{delete-indentation} deletes the
-fill prefix before joining the lines. @xref{Filling}.
+fill prefix before joining the lines. @xref{Margins}.
In the example below, point is located on the line starting
@samp{events}, and it makes no difference if there are trailing spaces
@deffn Command kill-region start end
This function kills the text in the region defined by @var{start} and
-@var{end}. The text is deleted but saved in the kill ring. The value
-is always @code{nil}.
+@var{end}. The text is deleted but saved in the kill ring, along with
+its text properties. The value is always @code{nil}.
In an interactive call, @var{start} and @var{end} are point and
the mark.
@deffn Command copy-region-as-kill start end
This command saves the region defined by @var{start} and @var{end} on
-the kill ring, but does not delete the text from the buffer. It returns
-@code{nil}. It also indicates the extent of the text copied by moving
-the cursor momentarily, or by displaying a message in the echo area.
+the kill ring (including text properties), but does not delete the text
+from the buffer. It returns @code{nil}. It also indicates the extent
+of the text copied by moving the cursor momentarily, or by displaying a
+message in the echo area.
The command does not set @code{this-command} to @code{kill-region}, so a
subsequent kill command does not append to the same kill ring entry.
@subsection Functions for Yanking
@dfn{Yanking} means reinserting an entry of previously killed text
-from the kill ring.
+from the kill ring. The text properties are copied too.
@deffn Command yank &optional arg
@cindex inserting killed text
@end example
@item @var{position}
-This element indicates where point was at an earlier time.
-Undoing this element sets point to @var{position}.
+This element indicates where point was at an earlier time. Undoing this
+element sets point to @var{position}. Deletion normally creates an
+element of this kind as well as a reinsertion element.
@item nil
This element is a boundary. The elements between two boundaries are
changes the buffer. Undo commands avoid confusion by saving the undo
list value at the beginning of a sequence of undo operations. Then the
undo operations use and update the saved value. The new elements added
-by undoing are not part of the saved value, so they don't interfere with
+by undoing are not part of this saved value, so they don't interfere with
continuing to undo.
@end defun
@dfn{Filling} means adjusting the lengths of lines (by moving the line
breaks) so that they are nearly (but no greater than) a specified
maximum width. Additionally, lines can be @dfn{justified}, which means
-that spaces are inserted between words to make the line exactly the
-specified width. The width is controlled by the variable
-@code{fill-column}. For ease of reading, lines should be no longer than
-70 or so columns.
+inserting spaces to make the left and/or right margins line up
+precisely. The width is controlled by the variable @code{fill-column}.
+For ease of reading, lines should be no longer than 70 or so columns.
You can use Auto Fill mode (@pxref{Auto Filling}) to fill text
automatically as you insert it, but changes to existing text may leave
Most of the commands in this section return values that are not
meaningful. All the functions that do filling take note of the current
-left margin, current right margin, and current justification style. If
-the current justification style is @code{none}, the filling functions
-don't actually do anything.
+left margin, current right margin, and current justification style
+(@pxref{Margins}). If the current justification style is
+@code{none}, the filling functions don't actually do anything.
+
+ Several of the filling functions have an argument @var{justify}.
+If it is non-@code{nil}, that requests some kind of justification. It
+can be @code{left}, @code{right}, @code{full}, or @code{center}, to
+request a specific style of justification. If it is @code{t}, that
+means to use the current justification style for this part of the text
+(see @code{current-justification}, below).
+
+ When you call the filling functions interactively, using a prefix
+argument implies the value @code{full} for @var{justify}.
-@deffn Command fill-paragraph justify-flag
+@deffn Command fill-paragraph justify
@cindex filling a paragraph
This command fills the paragraph at or after point. If
-@var{justify-flag} is non-@code{nil}, each line is justified as well.
+@var{justify} is non-@code{nil}, each line is justified as well.
It uses the ordinary paragraph motion commands to find paragraph
boundaries. @xref{Paragraphs,,, emacs, The Emacs Manual}.
@end deffn
-@deffn Command fill-region start end &optional justify-flag
+@deffn Command fill-region start end &optional justify
This command fills each of the paragraphs in the region from @var{start}
-to @var{end}. It justifies as well if @var{justify-flag} is
+to @var{end}. It justifies as well if @var{justify} is
non-@code{nil}.
The variable @code{paragraph-separate} controls how to distinguish
paragraphs. @xref{Standard Regexps}.
@end deffn
-@deffn Command fill-individual-paragraphs start end &optional justify-flag mail-flag
+@deffn Command fill-individual-paragraphs start end &optional justify mail-flag
This command fills each paragraph in the region according to its
individual fill prefix. Thus, if the lines of a paragraph were indented
with spaces, the filled paragraph will remain indented in the same
The first two arguments, @var{start} and @var{end}, are the beginning
and end of the region to be filled. The third and fourth arguments,
-@var{justify-flag} and @var{mail-flag}, are optional. If
-@var{justify-flag} is non-@code{nil}, the paragraphs are justified as
+@var{justify} and @var{mail-flag}, are optional. If
+@var{justify} is non-@code{nil}, the paragraphs are justified as
well as filled. If @var{mail-flag} is non-@code{nil}, it means the
function is operating on a mail message and therefore should not fill
the header lines.
described above.
@end defopt
-@deffn Command fill-region-as-paragraph start end &optional justify-flag
+@deffn Command fill-region-as-paragraph start end &optional justify
This command considers a region of text as a paragraph and fills it. If
the region was made up of many paragraphs, the blank lines between
paragraphs are removed. This function justifies as well as filling when
-@var{justify-flag} is non-@code{nil}. The precise value of
-@var{justify-flag} specifies a style of justification, as in
-@code{justify-current-line}, below.
+@var{justify} is non-@code{nil}.
In an interactive call, any prefix argument requests justification.
This variable's value specifies the style of justification to use for
text that doesn't specify a style with a text property. The possible
values are @code{left}, @code{right}, @code{full}, @code{center}, or
-@code{none}.
+@code{none}. The default value is @code{left}.
@end defopt
@defun current-justification
the text around point.
@end defun
+@defvar fill-paragraph-function
+This variable provides a way for major modes to override the filling of
+paragraphs. If the value is non-@code{nil}, @code{fill-paragraph} calls
+this function to do the work. If the function returns a non-@code{nil}
+value, @code{fill-paragraph} assumes the job is done, and immediately
+returns that value.
+
+The usual use of this feature is to fill comments in programming
+language modes. If the function needs to fill a paragraph in the usual
+way, it can do so as follows:
+
+@example
+(let ((fill-paragraph-function nil))
+ (fill-paragraph arg))
+@end example
+@end defvar
+
+@defvar use-hard-newlines
+If this variable is non-@code{nil}, the filling functions do not delete
+newlines that have the @code{hard} text property. These ``hard
+newlines'' act as paragraph separators.
+@end defvar
+
+@node Margins
+@section Margins for Filling
+
@defopt fill-prefix
This variable specifies a string of text that appears at the beginning
of normal text lines and should be disregarded when filling them. Any
additional whitespace. Lines that start with the fill prefix but no
additional whitespace are ordinary text lines that can be filled
together. The resulting filled lines also start with the fill prefix.
+
+The fill prefix follows the left margin whitespace, if any.
@end defopt
@defopt fill-column
The default value for @code{default-fill-column} is 70.
@end defvar
-@defvar fill-paragraph-function
-This variable provides a way for major modes to override the filling of
-paragraphs. If the value is non-@code{nil}, @code{fill-paragraph} calls
-this function to do the work. If the function returns a non-@code{nil}
-value, @code{fill-paragraph} assumes the job is done, and immediately
-returns that value.
-
-The usual use of this feature is to fill comments in programming
-language modes. If the function needs to fill a paragraph in the usual
-way, it can do so as follows:
-
-@example
-(let ((fill-paragraph-function nil))
- (fill-paragraph arg))
-@end example
-@end defvar
-
@deffn Command set-left-margin from to margin
This sets the @code{left-margin} property on the text from @var{from} to
@var{to} to the value @var{margin}. If Auto Fill mode is enabled, this
@end deffn
@deffn Command set-right-margin from to margin
-This sets the @code{fill-colmn} property on the text from @var{from} to
-@var{to} so as to yield a right margin of width @var{margin}. If Auto
-Fill mode is enabled, this command also refills the region to fit the
-new margin.
+This sets the @code{right-margin} property on the text from @var{from}
+to @var{to} to the value @var{margin}. If Auto Fill mode is enabled,
+this command also refills the region to fit the new margin.
@end deffn
@defun current-left-margin
This function returns the proper left margin value to use for filling
the text around point. The value is the sum of the @code{left-margin}
property of the character at the start of the current line (or zero if
-none), plus the value of the variable @code{left-margin}.
+none), and the value of the variable @code{left-margin}.
@end defun
@defun current-fill-column
@deffn Command move-to-left-margin &optional n force
This function moves point to the left margin of the current line. The
column moved to is determined by calling the function
-@code{current-left-margin}. If the argument @var{n} is specified,
+@code{current-left-margin}. If the argument @var{n} is non-@code{nil},
@code{move-to-left-margin} moves forward @var{n}@minus{}1 lines first.
If @var{force} is non-@code{nil}, that says to fix the line's
In no case does this function delete non-whitespace.
@end defun
+@defun indent-to-left-margin
+This is the default @code{indent-line-function}, used in Fundamental
+mode, Text mode, etc. Its effect is to adjust the indentation at the
+beginning of the current line to the value specified by the variable
+@code{left-margin}. This may involve either inserting or deleting
+whitespace.
+@end defun
+
+@defvar left-margin
+This variable specifies the base left margin column. In Fundamental
+mode, @key{LFD} indents to this column. This variable automatically
+becomes buffer-local when set in any fashion.
+@end defvar
+
@node Auto Filling
@comment node-name, next, previous, up
@section Auto Filling
For a description of functions that you can call explicitly to fill and
justify existing text, see @ref{Filling}.
+ Auto Fill mode also enables the functions that change the margins and
+justification style to refill portions of the text. @xref{Margins}.
+
@defvar auto-fill-function
The value of this variable should be a function (of no arguments) to be
called after self-inserting a space or a newline. It may be @code{nil},
Note that @code{sort-columns} uses the @code{sort} utility program,
and so cannot work properly on text containing tab characters. Use
@kbd{M-x @code{untabify}} to convert tabs to spaces before sorting.
-
-The @code{sort-columns} function did not work on VMS prior to Emacs 19.
@end deffn
@node Columns
is a trivial command that inserts a tab character.)
@end deffn
-@defun indent-to-left-margin
-This is the default @code{indent-line-function}, used in Fundamental
-mode, Text mode, etc. Its effect is to adjust the indentation at the
-beginning of the current line to the value specified by the variable
-@code{left-margin}. This may involve either inserting or deleting
-whitespace.
-@end defun
-
-@defvar left-margin
-This variable specifies the column for @code{indent-to-left-margin} to
-indent to. In Fundamental mode, @key{LFD} indents to this column. This
-variable automatically becomes buffer-local when set in any fashion.
-@end defvar
-
@deffn Command newline-and-indent
@comment !!SourceFile simple.el
This function inserts a newline, then indents the new line (the one
@defvar default-text-properties
This variable holds a property list giving default values for text
properties. Whenever a character does not specify a value for a
-property, the value stored in this list is used instead. Here is an
-example:
+property, neither directly nor through a category symbol, the value
+stored in this list is used instead. Here is an example:
@example
(setq default-text-properties '(foo 69))
properties is considered a buffer modification. Buffer text property
changes are undoable (@pxref{Undo}).
+@defun put-text-property start end prop value &optional object
+This function sets the @var{prop} property to @var{value} for the text
+between @var{start} and @var{end} in the string or buffer @var{object}.
+If @var{object} is @code{nil}, it defaults to the current buffer.
+@end defun
+
@defun add-text-properties start end props &optional object
This function modifies the text properties for the text between
@var{start} and @var{end} in the string or buffer @var{object}. If
@end example
@end defun
-@defun put-text-property start end prop value &optional object
-This function sets the @var{prop} property to @var{value} for the text
-between @var{start} and @var{end} in the string or buffer @var{object}.
-If @var{object} is @code{nil}, it defaults to the current buffer.
-@end defun
-
@defun remove-text-properties start end props &optional object
This function deletes specified text properties from the text between
@var{start} and @var{end} in the string or buffer @var{object}. If
writing your programs to examine characters one by one, it is much
faster to process chunks of text that have the same property value.
-Here are functions you can use to do this. In all cases, @var{object}
-defaults to the current buffer.
+Here are functions you can use to do this. They use @code{eq} for
+comparing property values. In all cases, @var{object} defaults to the
+current buffer.
For high performance, it's very important to use the @var{limit}
argument to these functions, especially the ones that search for a
-single property---otherwise, they may spend a long time considering
-changes in other properties while scanning to the end of the buffer.
+single property---otherwise, they may spend a long time scanning to the
+end of the buffer, if the property you are interested in does not change.
Remember that a position is always between two characters; the position
returned by these functions is between two characters with different
@node Special Properties
@subsection Properties with Special Meanings
+ Here is a table of text property names that have special built-in
+meanings. The following section lists a few more special property names
+that are used to control filling. All other names have no standard
+meaning, and you can use them as you like.
+
@table @code
@cindex category of text character
@kindex category @r{(text property)}
@kindex intangible @r{(text property)}
If a group of consecutive characters have equal and non-@code{nil}
@code{intangible} properties, then you cannot place point between them.
-If you move point forward into the group, point actually moves to the
-end of the group. If you try to move point backward into the group,
+If you try to move point forward into the group, point actually moves to
+the end of the group. If you try to move point backward into the group,
point actually moves to the start of the group.
When the variable @code{inhibit-point-motion-hooks} is non-@code{nil},
@end defvar
@node Format Properties
-@section Formatted Text Properties
+@subsection Formatted Text Properties
These text properties affect the behavior of the fill commands. They
-are used for representing formatted text. @xref{Filling}.
+are used for representing formatted text. @xref{Filling}, and
+@ref{Margins}.
-@table code
+@table @code
@item hard
If a newline character has this property, it is a ``hard'' newline.
The fill commands do not alter hard newlines and do not move words
@code{use-hard-newlines} is non-@code{nil}.
@item right-margin
-This property specifies the right margin for filling this part of the
+This property specifies an extra right margin for filling this part of the
text.
@item left-margin
-This property specifies the left margin for filling this part of the
+This property specifies an extra left margin for filling this part of the
text.
@item justification
You can save text properties in files, and restore text properties
when inserting the files, using these two hooks:
-@defvar write-region-annotation-functions
+@defvar write-region-annotate-functions
This variable's value is a list of functions for @code{write-region} to
run to encode text properties in some fashion as annotations to the text
being written in the file. @xref{Writing to Files}.
difficult to write, and slow. Instead, choose a set of possible data
types that are reasonably flexible, and not too hard to encode.
+@xref{Format Conversion}, for a related feature.
+
+@c ??? In next edition, merge this info Format Conversion.
+
@node Not Intervals
@subsection Why Text Properties are not Intervals
@cindex intervals
@cindex Outline mode
@cindex undo avoidance
-If @var{noundo} is non-@code{nil}, then @code{subst-char-in-region}
-does not record the change for undo and does not mark the buffer as
-modified. This feature is useful for changes that are not considered
-significant, such as when Outline mode changes visible lines to
-invisible lines and vice versa.
+If @var{noundo} is non-@code{nil}, then @code{subst-char-in-region} does
+not record the change for undo and does not mark the buffer as modified.
+This feature is used for controlling selective display (@pxref{Selective
+Display}).
@code{subst-char-in-region} does not move point and returns
@code{nil}.
characters that were actually changed by the translation. This does
not count characters that were mapped into themselves in the
translation table.
-
-This function is available in Emacs versions 19 and later.
@end defun
@node Registers
@end defvar
@defvar before-change-function
-This variable holds one function to call before any buffer modification
-(or @code{nil} for no function). It is called just like the functions
-in @code{before-change-functions}.
+This obsolete variable holds one function to call before any buffer
+modification (or @code{nil} for no function). It is called just like
+the functions in @code{before-change-functions}.
@end defvar
@defvar after-change-function
-This variable holds one function to call after any buffer modification
+This obsolete variable holds one function to call after any buffer modification
(or @code{nil} for no function). It is called just like the functions in
@code{after-change-functions}.
@end defvar
This variable is a normal hook that is run whenever a buffer is changed
that was previously in the unmodified state.
@end defvar
-
- The variables described in this section are meaningful only starting
-with Emacs version 19.
library program, at least if there is more than one entry point to the
program.
+@item
+If a file requires certain other library programs to be loaded
+beforehand, then the comments at the beginning of the file should say
+so. Also, use @code{require} to make sure they are loaded.
+
@item
If one file @var{foo} uses a macro defined in another file @var{bar},
-@var{foo} should contain @code{(require '@var{bar})} before the first
-use of the macro. (And @var{bar} should contain @code{(provide
-'@var{bar})}, to make the @code{require} work.) This will cause
-@var{bar} to be loaded when you byte-compile @var{foo}. Otherwise, you
-risk compiling @var{foo} without the necessary macro loaded, and that
-would produce compiled code that won't work right. @xref{Compiling
-Macros}.
+@var{foo} should contain this expression before the first use of the
+macro:
+
+@example
+(eval-when-compile (require '@var{bar}))
+@end example
+
+@noindent
+(And @var{bar} should contain @code{(provide '@var{bar})}, to make the
+@code{require} work.) This will cause @var{bar} to be loaded when you
+byte-compile @var{foo}. Otherwise, you risk compiling @var{foo} without
+the necessary macro loaded, and that would produce compiled code that
+won't work right. @xref{Compiling Macros}.
+
+Using @code{eval-when-compile} avoids loading @var{bar} when
+the compiled version of @var{foo} is @emph{used}.
@item
If you define a major mode, make sure to run a hook variable using
say which functions are replaced, and how the behavior of the
replacements differs from that of the originals.
-@item
-If a file requires certain standard library programs to be loaded
-beforehand, then the comments at the beginning of the file should say
-so.
-
@item
Please keep the names of your Emacs Lisp source files to 13 characters
or less. This way, if the files are compiled, the compiled files' names
Do not use @code{message}, @code{throw}, @code{sleep-for},
or @code{beep} to report errors.
+@item
+An error message should start with a capital letter but should not end
+with a period.
+
@item
Try to avoid using recursive edits. Instead, do what the Rmail @kbd{e}
command does: use a new local keymap that contains one command defined
is calling another compiled function.
@item
-Using the primitive list-searching functions @code{memq}, @code{assq}, or
-@code{assoc} is even faster than explicit iteration. It may be worth
-rearranging a data structure so that one of these primitive search
-functions can be used.
+Using the primitive list-searching functions @code{memq}, @code{member},
+@code{assq}, or @code{assoc} is even faster than explicit iteration. It
+may be worth rearranging a data structure so that one of these primitive
+search functions can be used.
@item
Certain built-in functions are handled specially in byte-compiled code,
display of the documentation string will become slow. So use this to
describe the most important commands in your major mode, and then use
@samp{\\@{@dots{}@}} to display the rest of the mode's keymap.
-
-@item
-Don't use the term ``Elisp'', since that is or was a trademark.
-Use the term ``Emacs Lisp''.
@end itemize
@node Comment Tips
@code{condition-case} (@pxref{Errors}).
@end itemize
+ Variables can also have buffer-local bindings (@pxref{Buffer-Local
+Variables}); a few variables have terminal-local bindings
+(@pxref{Multiple Displays}). These kinds of bindings work somewhat like
+ordinary local bindings, but they are localized depending on ``where''
+you are in Emacs, rather than localized in time.
+
@defvar max-specpdl-size
@cindex variable limit error
@cindex evaluation error
evaluates it and sets @var{symbol} to the result. (If @var{value} is
omitted, the value of @var{symbol} is not changed in any case.)
+When you evaluate a top-level @code{defvar} form with @kbd{C-M-x} in
+Emacs Lisp mode (@code{eval-defun}), a special feature of
+@code{eval-defun} evaluates it as a @code{defconst}. The purpose of
+this is to make sure the variable's value is reinitialized, when you ask
+for it specifically.
+
If @var{symbol} has a buffer-local binding in the current buffer,
@code{defvar} sets the default value, not the local value.
@xref{Buffer-Local Variables}.
@end defun
If a user option variable has a @code{variable-interactive} property,
-@code{set-variable} uses that value to control reading the new value for
-the variable. The property's value is used as if it were the argument
-to @code{interactive}.
+the @code{set-variable} command uses that value to control reading the
+new value for the variable. The property's value is used as if it were
+the argument to @code{interactive}.
@strong{Warning:} If the @code{defconst} and @code{defvar} special
forms are used while the variable has a local binding, they set the
@defun add-to-list symbol element
This function sets the variable @var{symbol} by consing @var{element}
onto the old value, if @var{element} is not already a member of that
-value. The value of @var{symbol} had better be a list already.
+value. It returns the resulting list, whether updated or not. The
+value of @var{symbol} had better be a list already before the call.
+
+The argument @var{symbol} is not implicitly quoted; @code{add-to-list}
+is an ordinary function, like @code{set} and unlike @code{setq}. Quote
+the argument yourself if that is what you want.
Here's a scenario showing how to use @code{add-to-list}:
the effect will be.
@end itemize
+ In either case, you should define the variable with @code{defvar}.
+This helps other people understand your program by telling them to look
+for inter-function usage. It also avoids a warning from the byte
+compiler. Choose the variable's name to avoid name conflicts---don't
+use short names like @code{x}.
+
@node Buffer-Local Variables
@section Buffer-Local Variables
@cindex variables, buffer-local
(setq foo 'a)
(let ((foo 'temp))
(set-buffer "b")
- @dots{})
+ @var{body}@dots{})
@group
foo @result{} 'a ; @r{The old buffer-local value from buffer @samp{a}}
; @r{is now the default value.}
between different kinds of bindings; it knows only which variable the
binding was made for.
+If the variable is terminal-local, this function signals an error. Such
+variables cannot have buffer-local bindings as well. @xref{Multiple
+Displays}.
+
@strong{Note:} do not use @code{make-local-variable} for a hook
variable. Instead, use @code{make-local-hook}. @xref{Hooks}.
@end deffn
The value returned is @var{variable}.
@end deffn
+@defun local-variable-p variable &optional buffer
+This returns @code{t} if @var{variable} is buffer-local in buffer
+@var{buffer} (which defaults to the current buffer); otherwise,
+@code{nil}.
+@end defun
+
@defun buffer-local-variables &optional buffer
This function returns a list describing the buffer-local variables in
buffer @var{buffer}. It returns an association list (@pxref{Association
list does @emph{not} change the local values of the variables.
@end defun
-@defun local-variable-p variable
-This returns @code{t} if @var{variable} is buffer-local in the current
-buffer. It is much faster to get the answer this way than to examine
-the value of @code{buffer-local-variables}.
-@end defun
-
@deffn Command kill-local-variable variable
This function deletes the buffer-local binding (if any) for
@var{variable} (a symbol) in the current buffer. As a result, the
@cindex window
@cindex selected window
- A @dfn{window} is the physical area of the screen in which a buffer is
-displayed. The term is also used to refer to a Lisp object that
+ A @dfn{window} in Emacs is the physical area of the screen in which a
+buffer is displayed. The term is also used to refer to a Lisp object that
represents that screen area in Emacs Lisp. It should be
clear from the context which is meant.
- There is always at least one window in any frame. In each frame, at
-any time, one and only one window is designated as @dfn{selected within
-the frame}. The frame's cursor appears in that window. There is also
-one selected frame; and the window selected within that frame is
-@dfn{the selected window}. The selected window's buffer is usually the
-current buffer (except when @code{set-buffer} has been used).
-@xref{Current Buffer}.
-
- For practical purposes, a window exists only while it is displayed on the
-terminal. Once removed from the display, the window is effectively
-deleted and should not be used, @emph{even though there may still be
-references to it} from other Lisp objects. Restoring a saved window
-configuration is the only way for a window no longer on the screen to
-come back to life. (@xref{Deleting Windows}.)
+ Emacs groups windows into frames. A frame represents an area of
+screen available for Emacs to use. Each frame always contains at least
+one window, but you can subdivide it vertically or horizontally into
+multiple nonoverlapping Emacs windows.
+
+ In each frame, at any time, one and only one window is designated as
+@dfn{selected within the frame}. The frame's cursor appears in that
+window. At ant time, one frame is the selected frame; and the window
+selected within that frame is @dfn{the selected window}. The selected
+window's buffer is usually the current buffer (except when
+@code{set-buffer} has been used). @xref{Current Buffer}.
+
+ For practical purposes, a window exists only while it is displayed in
+a frame. Once removed from the frame, the window is effectively deleted
+and should not be used, @emph{even though there may still be references
+to it} from other Lisp objects. Restoring a saved window configuration
+is the only way for a window no longer on the screen to come back to
+life. (@xref{Deleting Windows}.)
Each window has the following attributes:
@cindex multiple windows
Users create multiple windows so they can look at several buffers at
once. Lisp libraries use multiple windows for a variety of reasons, but
-most often to give different views of the same information. In Rmail,
-for example, you can move through a summary buffer in one window while
-the other window shows messages one at a time as they are reached.
+most often to display related information. In Rmail, for example, you
+can move through a summary buffer in one window while the other window
+shows messages one at a time as they are reached.
The meaning of ``window'' in Emacs is similar to what it means in the
context of general-purpose window systems such as X, but not identical.
-The X Window System subdivides the screen into X windows; Emacs uses one
-or more X windows, called @dfn{frames} in Emacs terminology, and
-subdivides each of them into (nonoverlapping) Emacs windows. When you
-use Emacs on an ordinary display terminal, Emacs subdivides the terminal
-screen into Emacs windows.
+The X Window System places X windows on the screen; Emacs uses one or
+more X windows as frames, and subdivides them into
+Emacs windows. When you use Emacs on a character-only terminal, Emacs
+treats the whole terminal screen as one frame.
@cindex terminal screen
@cindex screen of terminal
@item @code{visible}
Count all windows in all visible frames.
+@item 0
+Count all windows in all visible or iconified frames.
+
@item anything else
Count precisely the windows in the selected frame, and no others.
@end table
If it is @code{t}, operate on all frames.
@item
If it is @code{visible}, operate on all visible frames.
+@item 0
+If it is 0, operate on all visible or iconified frames.
@item
If it is a frame, operate on that frame.
@end itemize
@end example
@end defun
+@defmac save-selected-window forms@dots{}
+This macro records the selected window, executes @var{forms}
+in sequence, then restores the earlier selected window.
+It does not save or restore anything about the sizes, arrangement
+or contents of windows; therefore, if the @var{forms} change them,
+the changes are permanent.
+@end defmac
+
@cindex finding windows
The following functions choose one of the windows on the screen,
offering various criteria for the choice.
@item
If it is @code{visible}, consider windows on all visible frames.
@item
+If it is 0, consider windows on all visible or iconified frames.
+@item
If it is a frame, consider windows on that frame.
@end itemize
@end defun
Consider all windows in all visible frames. (To get useful results, you
must ensure @var{window} is in a visible frame.)
+@item @code{t}
+Consider all windows in all visible or iconified frames.
+
@item anything else
Consider precisely the windows in @var{window}'s frame, and no others.
@end table
@item
If it is @code{visible}, consider windows on all visible frames.
@item
+If it is 0, consider windows on all visible or iconified frames.
+@item
If it is a frame, consider windows on that frame.
@end itemize
@end defun
-@deffn Command replace-buffer-in-windows buffer
-This function replaces @var{buffer} with some other buffer in all
-windows displaying it. The other buffer used is chosen with
-@code{other-buffer}. In the usual applications of this function, you
-don't care which other buffer is used; you just want to make sure that
-@var{buffer} is no longer displayed.
-
-This function returns @code{nil}.
-@end deffn
-
@node Displaying Buffers
@section Displaying Buffers in Windows
@cindex switching to a buffer
@code{nil}, then the selected window is considered sufficient display
for @var{buffer-or-name}, so that nothing needs to be done.
+All the variables that affect @code{display-buffer} affect
+@code{pop-to-buffer} as well. @xref{Choosing Window}.
+
If @var{buffer-or-name} is a string that does not name an existing
buffer, a buffer by that name is created. The major mode for the new
buffer is set according to the variable @code{default-major-mode}.
@xref{Auto Major Mode}.
@end defun
+@deffn Command replace-buffer-in-windows buffer
+This function replaces @var{buffer} with some other buffer in all
+windows displaying it. The other buffer used is chosen with
+@code{other-buffer}. In the usual applications of this function, you
+don't care which other buffer is used; you just want to make sure that
+@var{buffer} is no longer displayed.
+
+This function returns @code{nil}.
+@end deffn
+
@node Choosing Window
@section Choosing a Window for Display
buffer specially.
By default, special display means to give the buffer a dedicated frame.
+
+If an element is a list, instead of a string, then the @sc{car} of the
+list is the buffer name, and the rest of the list says how to create the
+frame. There are two possibilities for the rest of the list. It can be
+an alist, specifying frame parameters, or it can contain a function and
+arguments to give to it. (The function's first argument is always the
+buffer to be displayed; the arguments from the list come after that.)
@end defvar
@defvar special-display-regexps
specially.
By default, special display means to give the buffer a dedicated frame.
+
+If an element is a list, instead of a string, then the @sc{car} of the
+list is the regular expression, and the rest of the list says how to
+create the frame. See above, under @code{special-display-buffer-names}.
@end defvar
@defvar special-display-function
@code{special-display-popup-frame} to use when it creates a frame.
@end defopt
+@defvar same-window-buffer-names
+A list of buffer names for buffers that should be displayed in the
+selected window. If the buffer's name is in this list,
+@code{display-buffer} handles the buffer by switching to it in the
+selected window.
+@end defvar
+
+@defvar same-window-regexps
+A list of regular expressions that specify buffers that should be
+displayed in the selected window. If the buffer's name matches any of
+the regular expressions in this list, @code{display-buffer} handles the
+buffer by switching to it in the selected window.
+@end defvar
+
@c Emacs 19 feature
@defvar display-buffer-function
This variable is the most flexible way to customize the behavior of
lines. Negative values of @var{count}, or @code{nil}, are handled
as in @code{scroll-up}.
-The window that is scrolled is normally the one following the selected
-window in the cyclic ordering of windows---the window that
-@code{next-window} would return. @xref{Cyclic Window Ordering}.
-
You can specify a buffer to scroll with the variable
@code{other-window-scroll-buffer}. When the selected window is the
minibuffer, the next window is normally the one at the top left corner.
Creating or deleting windows counts as a size change, and therefore
causes these functions to be called. Changing the frame size also
counts, because it changes the sizes of the existing windows.
+
+It is not a good idea to use @code{save-window-excursion} in these
+functions, because that always counts as a size change, and it would
+cause these functions to be called over and over. In most cases,
+@code{save-selected-window} is what you need here.
@end defvar
@node Coordinates and Windows
@var{configuration} must be a value that was previously returned by
@code{current-window-configuration}.
+This function always counts as a window size change and triggers
+execution of the @code{window-size-change-functions}. (It doesn't know
+how to tell whether the new configuration actually differs from the old
+one.)
+
Here is a way of using this function to get the same effect
as @code{save-window-excursion}:
However, it does not include the value of point in the current buffer;
use @code{save-excursion} if you wish to preserve that.
+Don't use this construct when @code{save-selected-window} is all you need.
+
+Exit from @code{save-window-excursion} always triggers execution of the
+@code{window-size-change-functions}. (It doesn't know how to tell
+whether the restored configuration actually differs from the one in
+effect at the end of the @var{forms}.)
+
The return value is the value of the final form in @var{forms}.
For example:
HCoop / bpt / emacs.git / commitdiff