Commit bfe721d1 authored by Karl Heuer's avatar Karl Heuer
Browse files

*** empty log message ***

parent 5c4276bc
......@@ -65,11 +65,12 @@ permanent local; @code{kill-local-variables} does not alter it.
@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
......@@ -107,10 +108,12 @@ The default value is this:
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
......@@ -506,7 +509,7 @@ If this variable is non-@code{nil}, buffers that are visiting files
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.
......@@ -515,6 +518,9 @@ Normally, if any buffers are auto-saved, a message that says
@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
......@@ -545,17 +551,22 @@ in response.
If it is -1, that means auto-saving is temporarily shut off in this
buffer due to a substantial deletion. Explicitly saving the buffer
stores a positive value in this variable, thus reenabling auto-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
......@@ -612,9 +623,9 @@ regenerate the contents.
@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
......@@ -635,16 +646,3 @@ Font Lock mode uses this hook to recompute the fonts for the updated
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
......@@ -45,11 +45,11 @@ current buffer. Each buffer, including the current buffer, may or may
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
......@@ -212,7 +212,7 @@ Any argument called @var{buffer} must be an actual buffer
object, not a name.
Buffers that are ephemeral and generally uninteresting to the user
have names starting with a space, so that the @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}.
......@@ -567,7 +567,7 @@ A buffer visiting a write-protected file is normally read-only.
Here, the purpose is to show the user that editing the buffer with the
aim of saving it in the file may be futile or undesirable. The user who
wants to change the buffer text despite this can do so after clearing
the read-only flag with @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
......@@ -779,6 +779,9 @@ Therefore, when you kill a buffer, you should also take the precautions
associated with changing the current buffer (unless you happen to know
that the buffer being killed isn't current). @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:
......@@ -853,7 +856,7 @@ when set for any reason. @xref{Buffer-Local Variables}.
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
......
......@@ -82,40 +82,10 @@ and also when the command loop is first entered. At that time,
@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
......@@ -502,7 +472,7 @@ that is, if @var{object} is a command. Otherwise, returns @code{nil}.
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.
......@@ -647,6 +617,9 @@ is a symbol with a function definition, but this is not guaranteed.
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
......@@ -662,7 +635,7 @@ 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.
......@@ -737,17 +710,6 @@ frame, the value is the frame to which the event was redirected.
@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
......@@ -798,11 +760,25 @@ An input character event consists of a @dfn{basic code} between 0 and
@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
......@@ -811,42 +787,95 @@ Thus, the code for @kbd{C-a} is just 1.
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
......@@ -1258,6 +1287,11 @@ the window manager. Its standard definition is @code{ignore}; since the
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
......@@ -1380,6 +1414,20 @@ This function returns non-@code{nil} if @var{object} is a mouse movement
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
......@@ -1476,7 +1524,13 @@ limited to the range of 0 to 255 as text characters are.
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
......@@ -1493,9 +1547,36 @@ If the keyboard character value is in the range of 0 to 127, it can go
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
......@@ -1609,8 +1690,9 @@ not perform case conversion in this way.
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
......@@ -1626,7 +1708,7 @@ You can define meanings for mouse clicks in special window parts by
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: ")
......@@ -1686,8 +1768,9 @@ the echo area.
@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)
......@@ -1794,8 +1877,8 @@ as part of a command or explicitly by a Lisp program.
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
......@@ -1852,12 +1935,15 @@ available. The value is @code{t} if @code{sit-for} waited the full
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
......@@ -1882,12 +1968,15 @@ This function simply pauses for @var{seconds} seconds without updating
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
......@@ -2312,7 +2401,7 @@ the user whether to proceed.
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.
......@@ -2374,14 +2463,6 @@ executed once. If it is 0, @var{macro} is executed over and over until it
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
......@@ -2396,7 +2477,15 @@ command can test this variable to behave differently while a 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
......@@ -24,6 +24,12 @@ however, as fast as true compiled code.
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.
......@@ -98,10 +104,13 @@ expanded when they are compiled, so the macros must already be defined
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},
......@@ -191,10 +200,10 @@ This function recompiles every @samp{.el} file in @var{directory} that
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
......@@ -265,7 +274,7 @@ turn off this feature by setting @code{byte-compile-dynamic-docstrings}
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;-*-
......@@ -372,7 +381,7 @@ At top level, this is analogous to the Common Lisp idiom
@end defspec
@node Byte-Code Objects
@section Byte-Code Objects
@section Byte-Code Function Objects
@cindex compiled function
@cindex byte-code function
......@@ -408,10 +417,10 @@ symbols used as function names and variable names.
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