mirror/emacs
1
0
Fork 0
mirror of https://git.savannah.gnu.org/git/emacs.git synced 2025-01-21 18:23:59 +00:00
Code Issues Releases Activity

*** empty log message ***

Browse Source
This commit is contained in:
Karl Heuer 1995-06-06 19:21:15 +00:00
parent 5c4276bc6d
commit bfe721d172
42 changed files with 1533 additions and 1122 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

54
lispref/backups.texi
View File

@ -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

19
lispref/buffers.texi
View File

@ -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

265
lispref/commands.texi
View File

@ -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

35
lispref/compile.texi
View File

@ -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
documentation string (@pxref{Accessing Documentation}).
@item interactive
The interactive spec (if any). This can be a string or a Lisp

7
lispref/control.texi
View File

@ -940,11 +940,11 @@ including those signaled with @code{error}:
(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
@ -1005,6 +1005,9 @@ message @samp{peculiar error} is used.
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

23
lispref/debugging.texi
View File

@ -172,8 +172,8 @@ for @var{function-name} in the minibuffer.
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}.
@ -217,7 +217,8 @@ Entering:
@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}
@ -329,12 +330,12 @@ cancels a @kbd{b} command on that frame.
@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
@ -376,7 +377,7 @@ whatever called @code{debug}. This is the only way the function
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.
@ -564,7 +565,7 @@ This function is used only by the debugger.
@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.

121
lispref/display.texi
View File

@ -45,6 +45,11 @@ Even more powerful is @code{redraw-display}:
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
@ -59,11 +64,6 @@ has been suspended and resumed. Non-@code{nil} means yes, @code{nil}
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
@ -154,10 +154,10 @@ then truncation is always used for side-by-side windows (within one
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
@ -171,15 +171,17 @@ with the display table; see @ref{Display Tables}.
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
@ -248,6 +250,17 @@ how to display a message and prevent it from being logged:
@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
@ -284,7 +297,7 @@ especially useful in a program to display the list of entries in a data
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
@ -314,13 +327,16 @@ by a visible newline, it displays an ellipsis.
@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
@ -329,7 +345,7 @@ been partially replaced by the invisible text feature (@pxref{Invisible
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
@ -469,9 +485,7 @@ given time.
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
@ -539,6 +553,10 @@ the display and later (presumably) move point forward. The argument
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.
@ -580,10 +598,10 @@ Type RET when done reading
@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.
@ -626,7 +644,7 @@ applies only on that window.
@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
@ -662,7 +680,7 @@ overlay, @code{t}, the beginning and end of the text range just
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)}
@ -685,7 +703,7 @@ invisible, which means that it does not appear on the screen.
@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)}
@ -890,6 +908,10 @@ character.
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}.
@ -898,6 +920,7 @@ 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.
@ -951,6 +974,19 @@ new frames.
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
@ -979,6 +1015,11 @@ These functions return the foreground color (or background color,
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
@ -987,7 +1028,7 @@ This function returns the name of the font of face @var{face}.
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
@ -1048,6 +1089,12 @@ This variable specifies the maximum distance to scan for a matching
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
@ -1089,10 +1136,13 @@ default is @code{nil}.
@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
@ -1132,7 +1182,7 @@ specify a glyph to use instead of @samp{\}.)
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,
@ -1390,11 +1440,6 @@ running under X) or @code{nil} (if Emacs is running on an ordinary
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

4
lispref/edebug.texi
View File

@ -214,7 +214,7 @@ must tell it; @xref{Instrumenting Macro Calls}, for details.
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.
@ -626,7 +626,7 @@ Evaluate expression @var{exp} in the context outside of Edebug
(@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

36
lispref/elisp.texi
View File

@ -180,8 +180,6 @@ Appendices
* 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.
@ -422,7 +420,7 @@ Loading
* 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
@ -650,6 +648,32 @@ Windows
* 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.
@ -664,8 +688,6 @@ Motion
* 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.
@ -693,6 +715,7 @@ Text
* 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.
@ -769,7 +792,7 @@ Processes
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
@ -886,7 +909,6 @@ Object Internals
@include locals.texi
@include maps.texi
@include hooks.texi
@include anti.texi
@include index.texi

34
lispref/errors.texi
View File

@ -52,6 +52,10 @@ See @code{/} and @code{%} in @ref{Numbers}.
@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}.
@ -105,6 +109,10 @@ The values of the symbols @code{nil} and @code{t}
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}.
@ -120,4 +128,30 @@ may not be changed.@*
@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

66
lispref/eval.texi
View File

@ -73,6 +73,12 @@ of the form @code{(car x)}: the subform @code{x} must first be evaluated
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
@ -90,17 +96,12 @@ is complete. The form may also make changes that persist; these changes
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
@ -108,10 +109,14 @@ write code that evaluates a form that is computed at run time, such as
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
@ -143,19 +148,6 @@ The number of currently active calls to @code{eval} is limited to
@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
@ -172,6 +164,12 @@ expressions. @xref{How Programs Do Loading}.
@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
@ -296,9 +294,9 @@ unchanged.
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
@ -654,14 +652,15 @@ definition loaded from that file. @xref{Autoload}.
@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
@ -700,9 +699,8 @@ Here are some examples of expressions that use @code{quote}:
@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.

103
lispref/files.texi
View File

@ -79,6 +79,11 @@ For historical reasons, these functions have names starting with
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
@ -132,16 +137,6 @@ visiting the file @var{filename}.
@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
@ -161,10 +156,11 @@ When this command is called interactively, it prompts for
@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}.
@ -208,6 +204,7 @@ as the name if that name is free; otherwise, it appends a string such as
@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
@ -368,9 +365,11 @@ the intended name after it is clear there are no errors. This procedure
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
@ -401,9 +400,11 @@ current buffer after point. It returns a list of the absolute file name
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
@ -427,10 +428,6 @@ contents of the buffer (actually, just the accessible portion) with the
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
@ -484,19 +481,16 @@ the buffer as visiting another file (@var{visit}). The argument
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
@ -737,8 +731,8 @@ time as a list of two numbers. @xref{File Attributes}.
@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
@ -1330,9 +1324,16 @@ backup version numbers, or trailing tildes.
@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
@ -1825,7 +1826,8 @@ This function creates a directory named @var{dirname}.
@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
@ -1887,7 +1889,8 @@ Here are the operations that a magic file name handler gets to handle:
@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},
@ -1977,9 +1980,10 @@ is a good way to come up with one.
@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.
@ -2014,7 +2018,7 @@ which specify the part of the buffer it should convert. It should convert
the text by editing it in place. Since this can change the length of the
text, @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.
@ -2061,23 +2065,26 @@ It keeps checking them until none of them is applicable.
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
@ -2098,7 +2105,7 @@ is always local in all buffers.
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

197
lispref/frames.texi
View File

@ -18,9 +18,10 @@ horizontally into smaller windows.
@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
@ -48,7 +49,7 @@ 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
@ -66,8 +67,8 @@ an X window frame; otherwise, it makes a terminal frame.
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
@ -120,7 +121,8 @@ argument, it is like @code{make-frame} (@pxref{Creating Frames}).
@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
@ -128,9 +130,18 @@ This function opens a connection to the X display @var{display}. It
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
@ -147,9 +158,8 @@ Just what parameters a frame has depends on what display mechanism it
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.
@ -196,11 +206,11 @@ file. After reading that file, Emacs checks @code{initial-frame-alist},
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
@ -211,8 +221,9 @@ the initial frame, specify the same parameters in
@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
@ -220,20 +231,18 @@ an initial minibuffer-only frame---if such a frame is needed, according
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
@ -267,8 +276,9 @@ negative @var{pos} value.
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
@ -278,8 +288,9 @@ negative @var{pos} value.
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
@ -312,8 +323,8 @@ The number of the X window for the frame.
@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
@ -351,6 +362,10 @@ value is a string, that specifies a file containing a bitmap to use.
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.
@ -414,9 +429,10 @@ by the window manager in its usual fashion.
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
@ -479,13 +495,13 @@ the left or top edge of the screen. A negative integer relates the
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
@ -494,10 +510,11 @@ position outside the screen.
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
@ -538,7 +555,7 @@ invisible frames). The default value of @code{frame-title-format} uses
@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
@ -598,6 +615,8 @@ The second argument, @var{minibuf}, says which frames to consider:
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.
@ -611,6 +630,9 @@ Like @code{next-frame}, but cycles through all frames in the opposite
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
@ -644,6 +666,9 @@ This function returns the window on @var{frame} that is selected within
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
@ -653,11 +678,10 @@ you can get it with @code{minibuffer-window} (@pxref{Minibuffer Misc}).
However, you can also create a frame with no minibuffer. Such a frame
must use the minibuffer window of some other frame. When you create the
frame, you can specify explicitly the 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
@ -665,7 +689,7 @@ 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
@ -697,7 +721,7 @@ lasts until overridden by a subsequent call to @code{switch-frame}.
Only the selected terminal frame is actually displayed on the terminal.
Each terminal screen except for the initial one has a number, and the
number of the selected frame appears in the mode line after the word
@samp{Emacs}.
@samp{Emacs} (@pxref{Mode Line Variables}).
@c ??? This is not yet implemented properly.
@defun select-frame frame
@ -758,7 +782,7 @@ change it.
@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
@ -882,6 +906,11 @@ The usual purpose of tracking mouse motion is to indicate on the screen
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.
@ -991,7 +1020,7 @@ can have the following form:
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
@ -1005,8 +1034,8 @@ individual items in that menu and provide help for them. If instead you
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
@ -1144,40 +1173,8 @@ This function stores @var{string} into the first cut buffer (cut buffer
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
@ -1221,39 +1218,27 @@ defined, the value is @code{nil}.
@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
@ -1263,8 +1248,8 @@ get information about the capabilities and origin of an X display that
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.

51
lispref/functions.texi
View File

@ -79,7 +79,9 @@ Structures}.
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
@ -150,9 +152,11 @@ function. For example:
@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.
@ -374,17 +378,17 @@ actually appears inside the Lisp world and can be used by the Emacs help
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
@ -532,11 +536,21 @@ deliberate redefinition from unintentional redefinition.
@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
@ -645,8 +659,8 @@ find them in data structures (especially in hook variables and property
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
@ -1007,7 +1021,7 @@ Functions}.
@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))
@ -1027,6 +1041,9 @@ defines @code{foo} rather than @code{old-foo}, it does not produce the
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
@ -1063,7 +1080,7 @@ Evaluation}.)
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

41
lispref/help.texi
View File

@ -60,7 +60,7 @@ documentation is displayed. This allows documentation strings to refer
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
@ -81,14 +81,17 @@ function @code{documentation-property} knows how to extract it.
@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}.
@ -105,10 +108,10 @@ use to print nice-looking hardcopy for the file
@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
@ -124,14 +127,10 @@ non-@code{nil}; the @var{verbatim} argument exists only as of Emacs 19.)
@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

4
lispref/hooks.texi
View File

@ -3,7 +3,7 @@
@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
@ -122,5 +122,5 @@ special way (they are passed arguments, or else their values are used).
@item window-setup-hook
@item write-contents-hooks
@item write-file-hooks
@item write-region-annotation-functions
@item write-region-annotate-functions
@end table

24
lispref/internals.texi
View File

@ -103,8 +103,8 @@ running. It is useful to include this string in bug reports.
@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
@ -113,20 +113,20 @@ echo area.
@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,
@ -135,12 +135,12 @@ convenient in the future.
@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
@ -332,7 +332,7 @@ that the subsequent garbage collection does not happen immediately when
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
@ -727,6 +727,10 @@ in this buffer, and their values, with the exception of local variables
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}.
@ -920,4 +924,8 @@ The file descriptor for output to the process.
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

4
lispref/intro.texi
View File

@ -536,7 +536,7 @@ manual. You may want to skip this section and refer back to it later.
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,
@ -554,7 +554,7 @@ in this font or form: @var{first-number}.
@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}.

53
lispref/keymaps.texi
View File

@ -74,7 +74,7 @@ intermediate bindings (found for the events before the last) are all
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
@ -207,6 +207,7 @@ otherwise. More precisely, this function tests for a list whose
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}
@ -570,9 +571,8 @@ 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.
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
@ -594,7 +594,7 @@ menu bar display. So if a menu bar key sequence comes in, you should
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
@ -650,12 +650,11 @@ event of the key sequence is looked up in @var{keymap}.
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
@ -685,7 +684,7 @@ binding of @var{othertype} in @var{othermap} and uses that.
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
@ -935,6 +934,10 @@ key name). For example, @code{(control ?a)} is equivalent to
@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
@ -1145,6 +1148,13 @@ or
(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.
@ -1431,8 +1441,8 @@ You can also supply a second string, called the help string, as follows:
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.
@ -1445,6 +1455,11 @@ the menu item only if the expression's value is non-@code{nil}. When a
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
@ -1539,10 +1554,14 @@ When the user has found the desired alternative from the menu, he or she
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.
@ -1616,8 +1635,8 @@ were @code{nil}. @xref{Active Keymaps}.
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:

16
lispref/lists.texi
View File

@ -543,9 +543,9 @@ Here are some examples where the final argument is not a list:
@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
@ -979,11 +979,6 @@ function would create new cons cells to store the elements in their
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
@ -1106,8 +1101,8 @@ sample-list
@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
@ -1178,6 +1173,9 @@ GNU Emacs Lisp are derived from Maclisp, not Common Lisp. The Common
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

42
lispref/loading.texi
View File

@ -37,7 +37,7 @@ containing Lisp code.
* 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.
@ -50,7 +50,7 @@ containing Lisp code.
@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
@ -136,9 +136,10 @@ default value is specified in @file{emacs/src/paths.h} when Emacs is
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
@ -192,9 +193,7 @@ calls to @code{load}.
@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
@ -213,9 +212,9 @@ functions should use @code{read}.
@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
@ -378,11 +377,16 @@ To avoid the problem, write this:
(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})
@ -393,10 +397,10 @@ has been loaded before:
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
@ -500,9 +504,10 @@ 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
@ -544,7 +549,8 @@ This command unloads the library that provided feature @var{feature}.
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
@ -615,7 +621,7 @@ do (1), you can do it immediately---there is no need to wait for when
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.

9
lispref/locals.texi
View File

@ -28,6 +28,9 @@ define such variables for their internal use; we don't list them here.
@item buffer-display-table
@pxref{Display Tables}
@item buffer-file-format
@pxref{Format Conversion}
@item buffer-file-name
@pxref{Buffer File Name}
@ -40,6 +43,9 @@ define such variables for their internal use; we don't list them here.
@item buffer-file-type
@pxref{Files and MS-DOS}
@item buffer-invisibility-spec
@pxref{Invisible Text}
@item buffer-offer-save
@pxref{Saving Buffers}
@ -121,6 +127,9 @@ define such variables for their internal use; we don't list them here.
@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}

69
lispref/macros.texi
View File

@ -163,8 +163,11 @@ macro in the same file where it is used and before its first use.
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
@ -176,9 +179,9 @@ from the macro call.
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
@ -207,7 +210,7 @@ called interactively.
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
@ -226,9 +229,9 @@ two forms yield identical results:
@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
@ -244,9 +247,9 @@ argument of @code{,} and puts the value in the list structure:
@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
@ -280,12 +283,12 @@ Here are some examples:
@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
@ -363,10 +366,10 @@ Here's an equivalent definition simplified through use of backquote:
(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
@ -400,11 +403,11 @@ Here is a macro definition that creates this expansion:
@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
@ -427,11 +430,11 @@ number of times:
"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
@ -469,11 +472,11 @@ this way:
(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

65
lispref/maps.texi
View File

@ -29,9 +29,15 @@ A sparse keymap used by C mode.
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
@ -42,10 +48,6 @@ A full keymap used by Debugger mode.
@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}.
@ -66,6 +68,38 @@ A full keymap used by Electric Command History mode.
@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.@*
@ -91,6 +125,7 @@ A sparse keymap used by the @kbd{e} command of Info.
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.
@ -107,7 +142,28 @@ A sparse keymap used by Lisp mode.
@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}),
@ -118,6 +174,7 @@ where it describes the main use of the @kbd{C-c} prefix key.
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

8
lispref/markers.texi
View File

@ -496,10 +496,10 @@ The return value is not meaningful.
@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

64
lispref/minibuf.texi
View File

@ -61,7 +61,7 @@ name on command symbols (@pxref{Minibuffer Misc}).
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
@ -87,6 +87,11 @@ also be used to read a Lisp object in textual form. The most basic
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
@ -199,12 +204,9 @@ possible to put a space into the string, by quoting it.
@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}
@ -213,27 +215,9 @@ following bindings:
@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
@ -805,6 +789,11 @@ can be completed because the next character is not uniquely determined.
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
@ -1000,7 +989,8 @@ This variable is used by @code{read-file-name}. Its value controls
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.
@ -1085,7 +1075,7 @@ match for some possibility; @code{nil} otherwise.
@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
@ -1357,6 +1347,16 @@ This command replaces the minibuffer contents with the value of the next
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}.
@ -1415,16 +1415,6 @@ minibuffer, a nonnegative integer. If no minibuffers are active, it
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
@ -1442,5 +1432,5 @@ window is selected.
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.

172
lispref/modes.texi
View File

@ -395,6 +395,8 @@ rest of @code{lisp-mode-variables}.
@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
@ -486,25 +488,25 @@ state of Emacs.)
@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
@ -516,6 +518,15 @@ lists unconditionally; @code{nil} means ignore them; anything else means
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
@ -553,8 +564,8 @@ This function sets the major mode of @var{buffer} to the value of
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
@ -757,7 +768,7 @@ minor modes in effect.
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.
@ -805,15 +816,15 @@ a positive integer, a symbol other than @code{nil} or @code{-}, or a
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
@ -847,10 +858,9 @@ check for an existing element, to avoid duplication. For example:
@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
@ -861,34 +871,6 @@ special cases (designed for abbrevs and Auto Fill mode). (Do not try
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
@ -906,8 +888,8 @@ minor modes.
@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
@ -940,7 +922,7 @@ strings, symbols, and numbers kept in the buffer-local variable
@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
@ -967,7 +949,7 @@ value is a list, each element may be a list, a symbol, or a string.
@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}.
@ -1010,8 +992,8 @@ the top of the window is to use a list like this: @code{(-3 "%p")}.
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
@ -1037,7 +1019,7 @@ directory.
"%n"
")%]----"
@group
(line-number-mode "L%l--")
'(line-number-mode "L%l--")
'(-3 . "%p")
"-%-"))
@end group
@ -1056,19 +1038,22 @@ other variables could have the same effects on the mode line if
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
@ -1111,18 +1096,16 @@ The default value of @code{minor-mode-alist} is:
@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
@ -1155,10 +1138,11 @@ The default value of @code{default-mode-line-format} is:
mode-name
@end group
@group
mode-line-process
minor-mode-alist
"%n"
mode-line-process
")%]----"
(line-number-mode "L%l--")
(-3 . "%p")
"-%-")
@end group
@ -1293,15 +1277,15 @@ the functions are called with arguments, or their values are meaningful.
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)
@ -1328,41 +1312,11 @@ expression.
(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
@ -1376,7 +1330,7 @@ lambda expression or a symbol with a function definition), it is
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)

113
lispref/numbers.texi
View File

@ -249,9 +249,10 @@ Here's a function to do this:
@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}
@ -356,7 +357,9 @@ This returns @var{number}, converted to an integer by rounding upward
@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
@ -386,8 +389,8 @@ For example,
@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
@ -413,7 +416,7 @@ This returns the absolute value of @var{number}.
@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
(+)
@ -430,8 +433,7 @@ The @code{-} function serves two purposes: negation and subtraction.
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)
@ -445,8 +447,7 @@ function does not check for overflow.
@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
(*)
@ -562,8 +563,9 @@ For any two numbers @var{dividend} and @var{divisor},
@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
@ -640,6 +642,40 @@ As the examples illustrate, shifting the pattern of bits one place to
the left produces a number that is twice the value of the previous
number.
Shifting a pattern of bits two places to the left produces results
like this (with 8-bit binary numbers):
@example
@group
(lsh 3 2)
@result{} 12
;; @r{Decimal 3 becomes decimal 12.}
00000011 @result{} 00001100
@end group
@end example
On the other hand, shifting one place to the right looks like this:
@example
@group
(lsh 6 -1)
@result{} 3
;; @r{Decimal 6 becomes decimal 3.}
00000110 @result{} 00000011
@end group
@group
(lsh 5 -1)
@result{} 2
;; @r{Decimal 5 becomes decimal 2.}
00000101 @result{} 00000010
@end group
@end example
@noindent
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
@ -668,41 +704,6 @@ which becomes the following when left shifted:
1111 1111 1111 1111 1111 1111 1110
@end group
@end example
Shifting the pattern of bits two places to the left produces results
like this (with 8-bit binary numbers):
@example
@group
(lsh 3 2)
@result{} 12
;; @r{Decimal 3 becomes decimal 12.}
00000011 @result{} 00001100
@end group
@end example
On the other hand, shifting the pattern of bits one place to the right
looks like this:
@example
@group
(lsh 6 -1)
@result{} 3
;; @r{Decimal 6 becomes decimal 3.}
00000110 @result{} 00000011
@end group
@group
(lsh 5 -1)
@result{} 2
;; @r{Decimal 5 becomes decimal 2.}
00000101 @result{} 00000010
@end 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.
@end defun
@defun ash integer1 count
@ -713,8 +714,8 @@ is negative.
@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:
@ -1008,18 +1009,8 @@ Emacs's process @sc{id} number.
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.

111
lispref/objects.texi
View File

@ -115,6 +115,11 @@ the end of line. The Lisp reader discards comments; they do not become
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
@ -305,17 +310,30 @@ equivalent to @samp{?\^I} and to @samp{?\^i}:
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
@ -324,11 +342,24 @@ of the program, but may guide the understanding of people who read it.
@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
@ -343,11 +374,17 @@ or as @samp{?\M-\101}. Likewise, you can write @kbd{C-M-b} as
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
@ -355,8 +392,15 @@ the computer in any way.
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
@ -423,14 +467,13 @@ do such a thing.
@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
@ -762,7 +805,14 @@ string containing just a single double-quote character.
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}.
@ -917,8 +967,9 @@ the evaluator handles this data type specially when it appears as a
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
@ -998,6 +1049,12 @@ a local keymap (@pxref{Keymaps}); and,
@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
@ -1006,7 +1063,10 @@ override global bindings or values. These are used to customize the
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
@ -1187,7 +1247,7 @@ and modify syntax tables.
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
@ -1196,12 +1256,12 @@ table is actually a vector of length 261. @xref{Display Tables}.
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
@ -1521,6 +1581,9 @@ use @code{string=} (@pxref{Text Comparison}).
@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

126
lispref/os.texi
View File

@ -59,6 +59,10 @@ It loads the initialization library for the window system, if you are
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.
@ -101,7 +105,7 @@ It displays the initial echo area message, unless you have suppressed
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}.
@ -179,6 +183,11 @@ Emacs does not subsequently load the @file{default.el} file.
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}
@ -543,9 +552,8 @@ through various functions. These variables include the name of the
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
@ -554,14 +562,26 @@ AIX.
@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.
@ -575,6 +595,9 @@ AT&T System V.
@item vax-vms
VAX VMS.
@item windows-nt
Microsoft windows NT.
@item xenix
SCO Xenix 386.
@end table
@ -650,13 +673,6 @@ function works by modifying @code{process-environment}; binding that
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
@ -677,6 +693,13 @@ process-environment
@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.
@ -785,18 +808,6 @@ you to ``fake out'' Emacs by telling the functions what to return. The
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.
@ -822,16 +833,16 @@ zone.
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
@ -912,8 +923,8 @@ This stands for the full name of the month.
@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
@ -959,11 +970,11 @@ This stands for the numeric day of week (0-6). Sunday is day 0.
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
@ -974,8 +985,8 @@ This stands for the time zone abbreviation.
@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})
@ -1002,7 +1013,8 @@ Sunday.
@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
@ -1011,10 +1023,8 @@ 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
@ -1028,7 +1038,7 @@ any further alteration for daylight savings time.
@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.
@ -1100,7 +1110,9 @@ functions.
@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
@ -1142,7 +1154,7 @@ is non-@code{nil} if Emacs uses @sc{xon/xoff} (@kbd{C-q}, @kbd{C-s})
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.
@ -1151,14 +1163,6 @@ is the character Emacs currently uses for quitting, usually @kbd{C-g}.
@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
@ -1185,7 +1189,7 @@ The @key{META} key.
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
@ -1513,8 +1517,10 @@ for flow control is not an official standard. Interestingly, on the
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
@ -1575,7 +1581,7 @@ calls @var{function} with no arguments.
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.)

84
lispref/positions.texi
View File

@ -37,9 +37,9 @@ to allow editing and insertion at different places.
Like other positions, point designates a place between two characters
(or before the first character, or after the last character), rather
than a particular character. 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.
@ -119,8 +119,6 @@ or relative to the edges of the selected window. @xref{Point}.
* 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
@ -422,36 +420,6 @@ to use and more reliable (no dependence on goal column, etc.).
@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.
@ -532,7 +500,8 @@ the form @code{(@var{hpos} . @var{vpos})}.
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
@ -585,49 +554,6 @@ When you use @code{compute-motion} for the minibuffer, you need to use
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

47
lispref/processes.texi
View File

@ -46,7 +46,7 @@ This function returns @code{t} if @var{object} is a process,
* 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
@ -313,7 +313,7 @@ inputinput@point{}
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
@ -321,12 +321,12 @@ from it. A non-@code{nil} value means the data is non-text; @code{nil}
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
@ -396,9 +396,8 @@ command.
@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},
@ -945,7 +944,7 @@ Now Emacs does this automatically; filter functions never need to do it
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}.
@ -1043,6 +1042,13 @@ thus specified are added together, and @code{accept-process-output}
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}.
@ -1095,15 +1101,10 @@ would be unpredictable. If you want to permit quitting inside a
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
@ -1111,6 +1112,11 @@ 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.
@ -1186,12 +1192,13 @@ to complete, and then terminate the connection or child process.
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
@ -1201,7 +1208,9 @@ what to do about closure of the connection.
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

26
lispref/searching.texi
View File

@ -974,7 +974,8 @@ This function returns, as a string, the text matched in the last search
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
@ -1083,10 +1084,14 @@ This function replaces the text in the buffer (or in @var{string}) that
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
@ -1207,10 +1212,10 @@ that shows the problem that arises if you fail to save the match data:
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
@ -1318,9 +1323,10 @@ this matches a line that starts with a formfeed character.
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

22
lispref/sequences.texi
View File

@ -15,8 +15,8 @@ collection of elements.
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
@ -36,7 +36,7 @@ But it is possible to add elements to the list, or remove elements.
| | List | | Array | |
| | | | ________ _______ | |
| |______| | | | | | | |
| | | String | | Vector| | |
| | | Vector | | String| | |
| | |________| |_______| | |
| |______________________| |
|___________________________________|
@ -191,9 +191,8 @@ otherwise, they trigger an @code{args-out-of-range} error.
@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
@ -232,9 +231,9 @@ The elements of an array may be referenced or changed with the functions
@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
@ -253,6 +252,11 @@ strings. For example, you cannot insert a vector of characters into a
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

11
lispref/streams.texi
View File

@ -52,7 +52,7 @@ text produces a list (but not the same list) with elements @code{a}
and @code{b}.
However, these two operations are not precisely inverses. There are
two kinds of exceptions:
three kinds of exceptions:
@itemize @bullet
@item
@ -66,6 +66,10 @@ One object can have multiple textual representations. For example,
@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
@ -160,8 +164,9 @@ whitespace preceding the significant text.
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

20
lispref/strings.texi
View File

@ -70,8 +70,16 @@ characters. @xref{Character Type}, for more information about
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},
@ -116,7 +124,7 @@ putting strings together, or by taking them apart.
@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.
@ -175,6 +183,9 @@ of @var{string}.
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
@ -190,9 +201,10 @@ beginning of a buffer is at index 1.
@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")

17
lispref/symbols.texi
View File

@ -151,7 +151,8 @@ expression and storing it in the function cell of the symbol. This
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
@ -160,8 +161,8 @@ both macro and function definitions are kept in the function cell, and
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
@ -503,11 +504,11 @@ stored in the property list @var{plist}. For example,
@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))

6
lispref/syntax.texi
View File

@ -43,7 +43,7 @@ this chapter.
@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
@ -650,8 +650,8 @@ exceed that many.
@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

250
lispref/text.texi
View File

@ -26,7 +26,7 @@ interactive call, point and the mark are used for these arguments.
@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.
@ -41,6 +41,7 @@ buffer.
* Maintaining Undo:: How to enable and disable undo information.
How to control how much information is kept.
* Filling:: Functions for explicit filling.
* Margins:: How to specify margins for filling commands.
* Auto Filling:: How auto-fill mode is implemented to break lines.
* Sorting:: Functions for sorting parts of the buffer.
* Columns:: Computing horizontal positions, and using them.
@ -239,7 +240,8 @@ the result is one plus the index of the first differing characters
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 }
@ -250,12 +252,10 @@ at the second character.
(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
@ -280,6 +280,12 @@ point} and the latter insertion @dfn{before point}.
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
@ -393,6 +399,9 @@ result in this case is to insert two newlines at different places: one
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
@ -414,7 +423,7 @@ buffer-local when set in any fashion.
@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
@ -544,7 +553,7 @@ instead. The value is @code{nil}.
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
@ -713,8 +722,8 @@ and if so appends the killed text to the most recent entry.
@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.
@ -728,9 +737,10 @@ text into the kill ring from a read-only buffer.
@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.
@ -745,7 +755,7 @@ support Emacs 18. For Emacs 19, it is better to use @code{kill-new} or
@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
@ -975,8 +985,9 @@ Here's how you might undo the change:
@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
@ -1018,7 +1029,7 @@ but it is convenient to have it in C.
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
@ -1089,10 +1100,9 @@ change group is never discarded separate no matter how big it is.
@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
@ -1100,28 +1110,38 @@ it improperly filled. Then you must fill the text explicitly.
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.
@deffn Command fill-paragraph justify-flag
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
@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
@ -1129,8 +1149,8 @@ fashion.
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.
@ -1147,13 +1167,11 @@ This variable alters the action of @code{fill-individual-paragraphs} as
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.
@ -1187,7 +1205,7 @@ whitespace.
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
@ -1195,6 +1213,32 @@ This function returns the proper justification style to use for filling
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
@ -1203,6 +1247,8 @@ a paragraph; so is any line that starts with the fill prefix followed by
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
@ -1225,23 +1271,6 @@ buffers that do not override it. This is the same as
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
@ -1249,17 +1278,16 @@ command also refills the region to fit the new margin.
@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
@ -1272,7 +1300,7 @@ character after point.
@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
@ -1286,6 +1314,20 @@ to delete is determined by calling @code{current-left-margin}.
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
@ -1297,6 +1339,9 @@ as inserted. This section describes the hook used by Auto Fill mode.
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},
@ -1539,8 +1584,6 @@ containing position @var{beg}, and the entire line containing position
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
@ -1689,20 +1732,6 @@ the current line; except that if that function is
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
@ -2107,8 +2136,8 @@ This function returns the entire property list of the character at
@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))
@ -2134,6 +2163,12 @@ can affect how the buffer looks on the screen, any change in the text
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
@ -2157,12 +2192,6 @@ properties of a range of text:
@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
@ -2214,13 +2243,14 @@ consecutive characters have the same value for a property. Rather than
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
@ -2314,6 +2344,11 @@ for @var{object} is the current buffer.
@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)}
@ -2370,8 +2405,8 @@ on the screen. @xref{Invisible Text}, for details.
@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},
@ -2444,12 +2479,13 @@ property has no effect.
@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
@ -2457,11 +2493,11 @@ across them. However, this property takes effect only if the variable
@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
@ -2541,7 +2577,7 @@ adjoining text.
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}.
@ -2597,6 +2633,10 @@ names or property values---because a program that general is probably
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
@ -2659,11 +2699,10 @@ defined by @var{start} and @var{end}.
@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}.
@ -2700,8 +2739,6 @@ The return value of @code{translate-region} is the number of
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
@ -2875,13 +2912,13 @@ buffer that's about to change is always the current buffer.
@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
@ -2916,6 +2953,3 @@ to call. Here is an example:
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.

49
lispref/tips.texi
View File

@ -59,15 +59,29 @@ It is often useful to put a call to @code{provide} in each separate
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
@ -155,11 +169,6 @@ standard Emacs, prominent comments at the beginning of the file should
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
@ -211,6 +220,10 @@ When you encounter an error condition, call the function @code{error}
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
@ -265,10 +278,10 @@ Function calls are slow in Emacs Lisp even when a compiled function
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,
@ -431,10 +444,6 @@ It is not practical to use @samp{\\[@dots{}]} very many times, because
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

49
lispref/variables.texi
View File

@ -231,6 +231,12 @@ Macro calls (@pxref{Macros}).
@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
@ -409,6 +415,12 @@ is not even evaluated, and @var{symbol}'s value remains unchanged. If
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}.
@ -532,9 +544,9 @@ then the variable is a user option.
@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
@ -714,7 +726,12 @@ an element to a list if it is not already present in the list.
@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}:
@ -944,6 +961,12 @@ Then you can bind the variable in other programs, knowing reliably what
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
@ -1027,7 +1050,7 @@ example of what to avoid:
(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.}
@ -1107,6 +1130,10 @@ variable does not work. This is because @code{let} does not distinguish
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
@ -1119,6 +1146,12 @@ local to the current buffer at the time.
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
@ -1153,12 +1186,6 @@ Note that storing new values into the @sc{cdr}s of cons cells in this
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

138
lispref/windows.texi
View File

@ -36,25 +36,29 @@ displayed in windows.
@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}.
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.
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}.)
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:
@ -93,17 +97,16 @@ how recently the window was selected
@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
@ -300,6 +303,9 @@ Count all windows in all existing frames.
@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
@ -370,6 +376,8 @@ If it is @code{nil}, operate on the selected frame.
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
@ -405,6 +413,14 @@ The return value is @var{window}.
@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.
@ -427,6 +443,8 @@ If it is @code{t}, consider windows on all frames.
@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
@ -503,6 +521,9 @@ Consider all windows in all existing frames.
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
@ -611,20 +632,12 @@ If it is @code{t}, consider windows on all frames.
@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
@ -716,12 +729,25 @@ already displayed in the selected window and @var{other-window} is
@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
@ -804,6 +830,13 @@ If the buffer's name is in this list, @code{display-buffer} handles the
buffer specially.
By default, special display means to give the buffer a dedicated frame.
If an element is a list, instead of a string, then the @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
@ -813,6 +846,10 @@ expressions in this list, @code{display-buffer} handles the buffer
specially.
By default, special display means to give the buffer a dedicated frame.
If an element is a list, instead of a string, then the @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
@ -841,6 +878,20 @@ This variable holds frame parameters for
@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
@ -1125,10 +1176,6 @@ This function scrolls the text in another window upward @var{count}
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.
@ -1539,6 +1586,11 @@ comparing the old size data with the new.
Creating or deleting windows counts as a size change, and therefore
causes these functions to be called. Changing the frame size also
counts, because it changes the sizes of the existing windows.
It is not a good idea to use @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
@ -1627,6 +1679,11 @@ buffers to the state specified by @var{configuration}. The argument
@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}:
@ -1649,6 +1706,13 @@ that is visible. It also includes the choice of selected window.
However, it does not include the value of point in the current buffer;
use @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: